claude-dev-env 1.95.0 → 2.0.0

package/_shared/pr-loop/scripts/reviews_disabled.py

@@ -7,10 +7,11 @@
     enabled lists bugbot, disabled bugbot   -> bugbot   flag: off (opt-out wins)
     disabled empty                          -> bugteam  ok:   runs
     disabled lists copilot                  -> copilot  flag: off
+    disabled lists codex                    -> codex    flag: off
 
 Bugbot is off by default and runs only when the enabled list names it.
-Bugteam and copilot run by default and stop only when the disabled list
-names them; both lists parse case-insensitively and tolerate whitespace.
+Bugteam, copilot, and codex run by default and stop only when the disabled
+list names them; both lists parse case-insensitively and tolerate whitespace.
 """
 
 from __future__ import annotations
@@ -22,6 +23,7 @@ import sys
 from pr_loop_shared_constants.reviews_disabled_constants import (
     CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN,
     CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
+    CLAUDE_REVIEWS_DISABLED_CODEX_TOKEN,
     CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN,
     CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME,
     CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR,
@@ -33,6 +35,7 @@ from pr_loop_shared_constants.reviews_disabled_constants import (
 __all__ = [
     "CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN",
     "CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN",
+    "CLAUDE_REVIEWS_DISABLED_CODEX_TOKEN",
     "CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN",
     "CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME",
     "CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR",
@@ -41,6 +44,7 @@ __all__ = [
     "is_bugbot_disabled_via_env",
     "is_bugbot_opted_out_via_env",
     "is_bugteam_disabled_via_env",
+    "is_codex_disabled_via_env",
     "is_copilot_disabled_via_env",
     "main",
 ]
@@ -129,6 +133,17 @@ def is_copilot_disabled_via_env() -> bool:
     )
 
 
+def is_codex_disabled_via_env() -> bool:
+    """Check whether CLAUDE_REVIEWS_DISABLED opts the Codex reviewer out.
+
+    Returns:
+        True when the env var lists the ``codex`` token.
+    """
+    return _is_reviewer_listed_in_env(
+        CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME, CLAUDE_REVIEWS_DISABLED_CODEX_TOKEN
+    )
+
+
 def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
     """Parse command-line arguments for the reviewer opt-out and opt-in gate check.
 
@@ -148,6 +163,7 @@ def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
             CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN,
             CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
             CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN,
+            CLAUDE_REVIEWS_DISABLED_CODEX_TOKEN,
         ],
         help="Reviewer token to test against the CLAUDE_REVIEWS_DISABLED / CLAUDE_REVIEWS_ENABLED gates",
     )
@@ -168,6 +184,7 @@ def main(all_arguments: list[str]) -> int:
         CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN: is_bugbot_disabled_via_env,
         CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN: is_bugteam_disabled_via_env,
         CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN: is_copilot_disabled_via_env,
+        CLAUDE_REVIEWS_DISABLED_CODEX_TOKEN: is_codex_disabled_via_env,
     }
     return 0 if disabled_checker_by_reviewer[arguments.reviewer]() else 1
 

package/_shared/pr-loop/scripts/test_code_rules_gate.py

@@ -0,0 +1,278 @@
+"""Behavioral tests for the gate's empty-file-set loudness and inspected-count report.
+
+Covers the three acceptance criteria of the loud-empty change:
+- A run whose resolved file set is empty exits non-zero and says so; a set
+  emptied only by the ``--only-under`` scope exits clean with the loud count.
+- A run over new, untracked modules inspects them.
+- Every run reports how many files it inspected.
+"""
+
+import importlib.util
+import os
+import subprocess
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+
+def _load_gate_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_gate.py"
+    spec = importlib.util.spec_from_file_location(
+        "code_rules_gate_empty_set_under_test", module_path
+    )
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+gate_module = _load_gate_module()
+
+
+def _control_violation_module_content() -> str:
+    """Return module content the enforcer must block.
+
+    The control violation is a formatted-string logging call. The source
+    fragment is assembled from pieces so this test file itself does not
+    carry the flagged pattern.
+    """
+    formatted_call = "logger.info(" + 'f"announcing {name}")'
+    return (
+        '"""Fresh module with a logging violation."""\n'
+        "import logging\n\n"
+        'logger = logging.getLogger("fresh_violation")\n\n\n'
+        "def announce(name: str) -> None:\n"
+        f"    {formatted_call}\n"
+    )
+
+
+def run_git_in_repository(repository_root: Path, *arguments: str) -> str:
+    completion = subprocess.run(
+        ["git", *arguments],
+        cwd=str(repository_root),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=True,
+        env=gate_module.repository_environment(),
+    )
+    return completion.stdout
+
+
+def initialize_git_repository(repository_root: Path) -> None:
+    run_git_in_repository(repository_root, "init", "--initial-branch=main")
+    run_git_in_repository(repository_root, "config", "user.email", "test@example.com")
+    run_git_in_repository(repository_root, "config", "user.name", "Test")
+    run_git_in_repository(repository_root, "config", "commit.gpgsign", "false")
+    disabled_hooks_directory = repository_root / "disabled-git-hooks"
+    disabled_hooks_directory.mkdir()
+    run_git_in_repository(
+        repository_root, "config", "core.hooksPath", str(disabled_hooks_directory)
+    )
+
+
+def commit_all_files(repository_root: Path, commit_message: str) -> None:
+    run_git_in_repository(repository_root, "add", "-A")
+    run_git_in_repository(repository_root, "commit", "-m", commit_message)
+
+
+@pytest.fixture(autouse=True)
+def isolated_git_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    for each_variable_name in list(os.environ):
+        if each_variable_name.startswith("GIT_"):
+            monkeypatch.delenv(each_variable_name, raising=False)
+
+
+@pytest.fixture()
+def temporary_git_repository(tmp_path: Path) -> Path:
+    repository_root = tmp_path / "repository_under_test"
+    repository_root.mkdir()
+    initialize_git_repository(repository_root)
+    (repository_root / "seed.txt").write_text("seed\n", encoding="utf-8")
+    commit_all_files(repository_root, "seed commit")
+    return repository_root
+
+
+def test_diff_mode_with_empty_file_set_exits_non_zero_and_says_so(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """HEAD == base and nothing untracked: the gate refuses to vouch for nothing.
+
+    A diff that resolves zero candidate files means the gate inspected
+    nothing — a bad merge base or a wrong directory looks exactly like this.
+    Issue #62's contract: that run exits non-zero and says so, because a
+    silent pass over zero files is trusted like a real pass.
+    """
+    monkeypatch.chdir(temporary_git_repository)
+
+    exit_code = gate_module.main(["--base", "HEAD"])
+
+    captured = capsys.readouterr()
+    assert exit_code != 0
+    assert "inspected 0 file(s)" in captured.err
+    assert "empty" in captured.err.lower()
+
+
+def test_diff_mode_changes_outside_only_under_prefixes_exit_clean_and_report(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Changes exist but none under the given prefixes: a scoped no-op exits 0.
+
+    The candidate set is non-empty, so the gate's wiring is proven live; the
+    ``--only-under`` scope legitimately excludes every candidate. That run
+    reports the zero count loudly and exits clean, so scoped gate loops keep
+    converging on branches whose changes sit outside the scoped tree.
+    """
+    (temporary_git_repository / "notes.txt").write_text("note\n", encoding="utf-8")
+    monkeypatch.chdir(temporary_git_repository)
+
+    exit_code = gate_module.main(["--base", "HEAD", "--only-under", "src"])
+
+    captured = capsys.readouterr()
+    assert exit_code == 0
+    assert "inspected 0 file(s)" in captured.err
+
+
+def test_diff_mode_inspects_untracked_module_and_reports_count(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A brand-new untracked module joins the file set and is validated."""
+    untracked_module = temporary_git_repository / "fresh_module.py"
+    untracked_module.write_text(
+        '"""Fresh module."""\n\n\ndef greet() -> str:\n    return "hello"\n',
+        encoding="utf-8",
+    )
+    monkeypatch.chdir(temporary_git_repository)
+
+    exit_code = gate_module.main(["--base", "HEAD"])
+
+    captured = capsys.readouterr()
+    assert "inspected 1 file(s)" in captured.err
+    assert exit_code == 0
+
+
+def test_diff_mode_blocks_violation_in_untracked_module(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """An untracked module whose content the enforcer rejects fails the gate."""
+    untracked_module = temporary_git_repository / "fresh_violation.py"
+    untracked_module.write_text(
+        _control_violation_module_content(),
+        encoding="utf-8",
+    )
+    monkeypatch.chdir(temporary_git_repository)
+
+    exit_code = gate_module.main(["--base", "HEAD"])
+
+    captured = capsys.readouterr()
+    assert exit_code != 0
+    assert "inspected 1 file(s)" in captured.err
+    assert "fresh_violation.py" in captured.err
+
+
+def test_explicit_paths_run_reports_inspected_count(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """The count line appears on explicit-path runs too, so a caller always sees it."""
+    module_path = temporary_git_repository / "explicit_module.py"
+    module_path.write_text(
+        '"""Explicit module."""\n\n\ndef ping() -> str:\n    return "pong"\n',
+        encoding="utf-8",
+    )
+    commit_all_files(temporary_git_repository, "add explicit module")
+    monkeypatch.chdir(temporary_git_repository)
+
+    exit_code = gate_module.main(["explicit_module.py"])
+
+    captured = capsys.readouterr()
+    assert exit_code == 0
+    assert "inspected 1 file(s)" in captured.err
+
+
+def test_staged_mode_with_nothing_staged_reports_zero_inspected(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Staged mode keeps its exit contract for an empty commit but names the count."""
+    monkeypatch.chdir(temporary_git_repository)
+
+    exit_code = gate_module.main(["--staged"])
+
+    captured = capsys.readouterr()
+    assert exit_code == 0
+    assert "inspected 0 file(s)" in captured.err
+
+
+def test_untracked_paths_helper_lists_only_untracked_files(
+    temporary_git_repository: Path,
+) -> None:
+    tracked_path = temporary_git_repository / "tracked.py"
+    tracked_path.write_text('"""Tracked."""\n', encoding="utf-8")
+    commit_all_files(temporary_git_repository, "add tracked module")
+    untracked_path = temporary_git_repository / "untracked.py"
+    untracked_path.write_text('"""Untracked."""\n', encoding="utf-8")
+
+    resolved_paths = gate_module.paths_from_git_untracked(temporary_git_repository)
+
+    resolved_names = {each_path.name for each_path in resolved_paths}
+    assert "untracked.py" in resolved_names
+    assert "tracked.py" not in resolved_names
+
+
+def _gate_import_names_in_source(module_source: str) -> set[str]:
+    """Collect the names a source file imports from ``code_rules_gate``.
+
+    Args:
+        module_source: Python source text to scan for the gate import block.
+
+    Returns:
+        The imported-name set from the ``from code_rules_gate import (...)``
+        statement in the source, empty when no such block exists.
+    """
+    _, _, after_open = module_source.partition("from code_rules_gate import (")
+    import_block, _, _ = after_open.partition(")")
+    return {
+        each_line.strip().rstrip(",")
+        for each_line in import_block.splitlines()
+        if each_line.strip() and not each_line.strip().startswith("#")
+    }
+
+
+def test_entry_exposes_every_symbol_the_preflight_hook_imports() -> None:
+    """The gate entry re-exports the whole surface the spawn-preflight hook uses.
+
+    The code-verifier spawn-preflight hook imports gate helpers by name at
+    runtime; a name the entry drops breaks that hook's import and silently
+    turns its deny paths into allows.
+    """
+    hook_path = (
+        Path(__file__).resolve().parents[3]
+        / "hooks"
+        / "blocking"
+        / "code_verifier_spawn_preflight_gate.py"
+    )
+    hook_imported_names = _gate_import_names_in_source(
+        hook_path.read_text(encoding="utf-8")
+    )
+
+    assert hook_imported_names, "hook no longer imports from code_rules_gate"
+    missing_names = sorted(
+        each_name
+        for each_name in hook_imported_names
+        if not hasattr(gate_module, each_name)
+    )
+    assert not missing_names, f"gate entry drops hook imports: {missing_names}"

package/_shared/pr-loop/scripts/tests/test_code_rules_gate_constants.py

@@ -7,9 +7,7 @@ from types import ModuleType
 
 def _load_constants_module() -> ModuleType:
     module_path = (
-        Path(__file__).parent.parent
-        / "pr_loop_shared_constants"
-        / "code_rules_gate_constants.py"
+        Path(__file__).parent.parent / "pr_loop_shared_constants" / "code_rules_gate_constants.py"
     )
     specification = importlib.util.spec_from_file_location(
         "pr_loop_shared_constants.code_rules_gate_constants", module_path
@@ -29,29 +27,14 @@ def test_max_violations_per_check_is_typed_integer() -> None:
     assert constants_module.MAX_VIOLATIONS_PER_CHECK == 3
 
 
-def test_expected_tuple_pair_length_is_typed_integer() -> None:
-    assert isinstance(constants_module.EXPECTED_TUPLE_PAIR_LENGTH, int)
-    assert constants_module.EXPECTED_TUPLE_PAIR_LENGTH == 2
-
-
 def test_all_code_file_extensions_is_frozenset() -> None:
     assert isinstance(constants_module.ALL_CODE_FILE_EXTENSIONS, frozenset)
-    assert constants_module.ALL_CODE_FILE_EXTENSIONS == frozenset(
-        {".py", ".js", ".ts", ".tsx", ".jsx"}
-    )
-
-
-def test_all_literal_keyword_exemptions_is_frozenset() -> None:
-    assert isinstance(constants_module.ALL_LITERAL_KEYWORD_EXEMPTIONS, frozenset)
-    assert constants_module.ALL_LITERAL_KEYWORD_EXEMPTIONS == frozenset(
-        {"true", "false", "none", "null"}
+    assert (
+        frozenset({".py", ".js", ".ts", ".tsx", ".jsx"})
+        == constants_module.ALL_CODE_FILE_EXTENSIONS
     )
 
 
-def test_config_path_segment() -> None:
-    assert constants_module.CONFIG_PATH_SEGMENT == "/config/"
-
-
 def test_tests_path_segment() -> None:
     assert constants_module.TESTS_PATH_SEGMENT == "/tests/"
 
@@ -73,10 +56,6 @@ def test_test_filename_prefix() -> None:
     assert constants_module.TEST_FILENAME_PREFIX == "test_"
 
 
-def test_minimum_column_name_length_after_first_char() -> None:
-    assert constants_module.MINIMUM_COLUMN_NAME_LENGTH_AFTER_FIRST_CHAR == 2
-
-
 def test_git_name_status_added_prefix() -> None:
     assert constants_module.GIT_NAME_STATUS_ADDED_PREFIX == "A"
 
@@ -89,17 +68,8 @@ def test_expected_rename_column_count() -> None:
     assert constants_module.EXPECTED_RENAME_COLUMN_COUNT == 3
 
 
-def test_column_key_pattern_template_renders_with_minimum_length() -> None:
-    rendered_pattern = constants_module.COLUMN_KEY_PATTERN_TEMPLATE.format(
-        minimum_length=constants_module.MINIMUM_COLUMN_NAME_LENGTH_AFTER_FIRST_CHAR
-    )
-    assert rendered_pattern == r"^[a-z][a-z0-9_]{2,}$"
-
-
 def test_git_diff_name_only_null_terminated_command_prefix_includes_dash_z() -> None:
-    command_prefix = (
-        constants_module.ALL_GIT_DIFF_NAME_ONLY_NULL_TERMINATED_COMMAND_PREFIX
-    )
+    command_prefix = constants_module.ALL_GIT_DIFF_NAME_ONLY_NULL_TERMINATED_COMMAND_PREFIX
     assert command_prefix == ("git", "diff", "--name-only", "-z")
 
 
@@ -110,10 +80,7 @@ def test_banned_noun_span_pattern_extracts_definition_line_and_span() -> None:
     )
     match = constants_module.BANNED_NOUN_VIOLATION_PATTERN.search(message)
     assert match is not None
-    definition_line = int(
-        match.group(constants_module.BANNED_NOUN_DEFINITION_LINE_GROUP_INDEX)
-    )
+    definition_line = int(match.group(constants_module.BANNED_NOUN_DEFINITION_LINE_GROUP_INDEX))
     line_span = int(match.group(constants_module.BANNED_NOUN_SPAN_GROUP_INDEX))
     assert definition_line == 1
     assert line_span == 3
-

package/_shared/pr-loop/scripts/tests/test_reviews_disabled.py

@@ -143,6 +143,35 @@ def test_is_copilot_disabled_via_env_true_when_listed_among_other_tokens(
     assert reviews_disabled.is_bugbot_disabled_via_env() is True
 
 
+def test_is_codex_disabled_via_env_returns_true_when_env_lists_codex(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "codex")
+    assert reviews_disabled.is_codex_disabled_via_env() is True
+
+
+def test_is_codex_disabled_via_env_returns_false_when_env_is_empty(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
+    assert reviews_disabled.is_codex_disabled_via_env() is False
+
+
+def test_is_codex_disabled_via_env_returns_false_when_only_bugbot_listed(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugbot")
+    assert reviews_disabled.is_codex_disabled_via_env() is False
+
+
+def test_is_codex_disabled_via_env_true_when_listed_among_other_tokens(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", " BugBot , CoDex ")
+    assert reviews_disabled.is_codex_disabled_via_env() is True
+    assert reviews_disabled.is_bugbot_disabled_via_env() is True
+
+
 def test_cli_main_returns_zero_when_named_reviewer_disabled(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
@@ -185,3 +214,17 @@ def test_cli_main_returns_one_for_copilot_when_only_bugbot_disabled(
 ) -> None:
     monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugbot")
     assert reviews_disabled.main(["--reviewer", "copilot"]) == 1
+
+
+def test_cli_main_supports_codex_reviewer(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "codex")
+    assert reviews_disabled.main(["--reviewer", "codex"]) == 0
+
+
+def test_cli_main_returns_one_for_codex_when_only_bugbot_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugbot")
+    assert reviews_disabled.main(["--reviewer", "codex"]) == 1

package/_shared/pr-loop/worker-spawn.md

@@ -0,0 +1,186 @@
+# Worker-spawn protocol
+
+Single home for the worker-spawn dispatcher contract and for Claude-only
+slash-step host routing. Skills that need a role-bound headless worker call
+[`scripts/resolve_worker_spawn.py`](../../scripts/resolve_worker_spawn.py)
+(or import `resolve_worker_spawn`) and read this page for the tier walk, inputs,
+JSON result shape, host rules, and setup. Skills that run a Claude-only slash
+step (for example `/code-review`) read the code-review host-routing section.
+
+Composed helpers (preflight, headless runners, and the code-review invoker)
+stay documented at their own modules; this page states how callers use them.
+
+## Three tiers
+
+Walk order is fixed: soft-gate preflight for tier 1, then tier 1, then host
+branching for tiers 2 and 3.
+
+| Tier | Name | Who runs it |
+|---|---|---|
+| 1 | Grok headless | Python helper: `grok_worker_preflight` then `grok_headless_runner.run_headless_worker` |
+| 2 | `claude_agent_required` | **Not** the Python helper. A stop signal so the **calling skill / harness** runs the Claude Code Agent tool itself |
+| 3 | Claude headless | Python helper: `claude_chain_runner.run_claude` with `-p --output-format json --agent <stem>`, prompt body on stdin from the prompt file, and subprocess `cwd` set to the caller's working directory |
+
+### `claude_agent_required` boundary
+
+A Python helper cannot spawn Claude Code Agent-tool subagents. On a **Claude**
+host, when the claude headless tier is **not** enabled (`--enable-claude-tier`
+absent / `is_claude_tier_enabled=False`), a grok fallthrough records tier 2 with
+reason `claude_agent_required`, leaves `tier_used` null, and returns. The
+calling skill must then run the Agent tool in-process.
+
+On a **ThirdParty** host, or when the claude tier is enabled on a Claude host,
+the dispatcher continues to tier 3.
+
+## Tier-1 fleets via grok-spawn
+
+For a fleet of tier-1 grok workers (batch spec in, reports out), use the
+**grok-spawn** skill when that skill is installed on the host (it ships on a
+sibling stack and is not part of this dispatcher page). When present, that
+skill owns the batch playbook and flag profiles under its reference docs.
+This page stays the single-worker dispatcher contract (`resolve_worker_spawn`).
+
+The calling session owns verification and every commit, push, or GitHub post.
+Workers never commit or post.
+
+## Required inputs
+
+### CLI
+
+```
+python resolve_worker_spawn.py \
+  --role <role> \
+  --prompt-file <path> \
+  --cwd <dir> \
+  --run-temp-dir <dir> \
+  [--timeout-seconds N] \
+  [--enable-claude-tier]
+```
+
+| Flag | Required | Meaning |
+|---|---|---|
+| `--role` | no (default `bugteam`) | Role name for preflight agent-set checks; mapped to the primary agent stem for headless `--agent` (for example `bugteam` → `code-quality-agent`, `clean-coder` → `clean-coder`; unknown roles fall back to the raw role string) |
+| `--prompt-file` | yes | Prompt file path for headless workers |
+| `--cwd` | yes | Working directory for headless grok and claude workers |
+| `--run-temp-dir` | yes | Run-scoped directory for leader sockets and preflight cache (created if missing) |
+| `--timeout-seconds` | no (default `600`) | Per-tier timeout in seconds |
+| `--enable-claude-tier` | no | Allow tier 3 on a Claude host |
+
+There is no separate outcome-file flag. The result surface is **stdout JSON**
+plus the process exit code.
+
+### Import API
+
+`resolve_worker_spawn(...)` takes keyword-only arguments:
+`role`, `prompt_file`, `working_directory`, `timeout_seconds`,
+`is_claude_tier_enabled`, `run_state_directory`, `max_turns`.
+`encode_spawn_outcome` turns a `SpawnOutcome` into the same JSON shape the CLI
+prints.
+
+## JSON result shape
+
+Stdout is one JSON object:
+
+```json
+{
+  "tier_used": 1,
+  "ok": true,
+  "attempts": [
+    {"tier": 1, "ok": true, "reason": null}
+  ],
+  "output": "<serving tier stdout>",
+  "returncode": 0
+}
+```
+
+| Key | Meaning |
+|---|---|
+| `tier_used` | Serving tier number (`1` or `3`), or `null` when no tier served |
+| `ok` | Whether the serving call completed successfully |
+| `attempts` | Ordered list of tries: each `{tier, ok, reason}` |
+| `output` | Captured stdout from the serving tier (empty when none) |
+| `returncode` | Process return code from the last tier run (or config-error code) |
+
+`attempts` is in tried order. A Claude-host stop records tier `2` with
+`reason: "claude_agent_required"`. Preflight or grok fallthrough reasons use the
+preflight/runner classification strings (for example `grok_binary_missing`,
+`usage_limit`).
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | A tier served (`tier_used` is not null) |
+| `2` | Exhausted — no tier served |
+| `3` | Config error: the `--prompt-file` path is not an existing file (`output` = `prompt_file_missing`) or claude chain configuration missing or invalid |
+
+## Host detection
+
+After a grok fallthrough the dispatcher calls `detect_host_profile()` from
+`tier_model_ids` (advisor scripts). Detection order:
+
+1. `ADVISOR_HOST_PROFILE` when set — must be `Claude` or `ThirdParty` (any letter case).
+2. `THIRD_PARTY` when truthy — `1`, `true`, `yes`, or `on`.
+3. Default: `Claude`.
+
+Profiles are the real names `Claude` and `ThirdParty` (not a separate Grok host
+profile). Grok is tier 1 on every host; host profile only chooses the post-grok
+branch (Agent-tool handoff vs headless claude chain).
+
+## Code-review host routing
+
+Claude-only slash steps need a Claude Code harness. The built-in
+`/code-review` command is the main case. The host-routing pair is:
+
+- `detect_host_profile()` from `tier_model_ids` — same host detection as the
+  worker-spawn dispatcher above
+- `invoke_code_review` — host-aware invoker for `/code-review` (lives next to
+  `resolve_worker_spawn` under the package scripts tree)
+
+Mode decision:
+
+| Host profile | Session model | Mode | Who runs `/code-review` |
+|---|---|---|---|
+| `Claude` | `opus` | `in_session` | The calling skill runs the slash command in-process |
+| `Claude` | any other alias | `chain` | Headless spawn through `claude_chain_runner` |
+| `ThirdParty` | any | `chain` | Headless spawn through `claude_chain_runner` |
+
+The review always runs at effort **high** on model **opus**. Chain mode builds
+a single-turn prompt `/code-review high --fix`, pins `--model opus`, sets
+subprocess `cwd` to the PR working tree, and reads stdin from the empty stream
+so the spawn does not wait for input.
+
+After a chain run, a non-empty `git status --porcelain` means the review
+applied fixes. The calling host commits and pushes those fixes per the fix
+protocol. The chain process never commits or posts. A clean stamp requires
+`returncode == 0` and a non-null `served_command` plus a clean tree —
+`dirty_tree` false alone is not enough when the chain failed or never served.
+
+GitHub transport (`pr-loop-cloud-transport`) is a separate axis from this
+harness branch. That skill routes `gh` vs MCP; it does not change which host
+can run Claude-only slash commands.
+
+## Leader-socket rule
+
+Every concurrent grok process gets its own `--leader-socket` path under the
+caller-supplied run temp directory. The headless runner mints a unique
+`grok-leader-<uuid>.sock` per invocation. Preflight auth and ping probes use
+their own fixed socket filenames under the same directory so they never share a
+socket with a live worker.
+
+## Cloud setup
+
+Unattended grok auth uses the `XAI_API_KEY` environment variable. Install the
+CLI via the vendor curl installer or the `@xai-official/grok` package. Keep
+agent definitions and hook config in parity with `npx claude-dev-env` so the
+preflight role-agent check and local `~/.claude` layout match what the worker
+expects.
+
+Use placeholders for account-specific values; do not hardcode personal paths or
+keys in skills or docs.
+
+## GitHub transport
+
+`pr-loop-cloud-transport` is a separate axis. This utility never posts reviews,
+opens PRs, or substitutes `gh` for MCP. GitHub reachability and cloud session
+routing stay outside the worker-spawn contract.