claude-dev-env 2.3.0 → 2.4.0

package/scripts/invoke_code_review.py

@@ -15,20 +15,19 @@ the spawn does not wait for interactive input. Result JSON on stdout only::
 
     {"mode", "served_command", "returncode", "dirty_tree"}
 
-A clean stamp requires a successful serve (``returncode == 0``, and for chain
-mode a non-null ``served_command``) plus ``dirty_tree`` false. A failed chain
-or config/host error leaves the tree clean but must not advance past
-CODE_REVIEW — use ``is_code_review_clean_stamp_allowed``.
+``--record-stamp`` forces chain mode, loops a capped number of review passes,
+and mints a clean stamp only when a pass exits 0 with a stable surface hash.
 
 Import ``invoke_code_review`` for the outcome object, or run as a CLI::
 
     python invoke_code_review.py --cwd <dir> --session-model <alias>
-        [--timeout-seconds N]
+        [--timeout-seconds N] [--record-stamp] [effort]
 """
 
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import json
 import subprocess
 import sys
@@ -36,6 +35,7 @@ import threading
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass
 from pathlib import Path
+from types import ModuleType
 
 if str(Path(__file__).resolve().parent) not in sys.path:
     sys.path.insert(0, str(Path(__file__).resolve().parent))
@@ -57,24 +57,47 @@ from claude_chain_runner import (  # noqa: E402
 )
 from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
     CHAIN_CONFIG_ERROR_EXIT_CODE,
+    collect_forwarded_text_codec,
 )
 from dev_env_scripts_constants.code_review_constants import (  # noqa: E402
+    ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER,
+    CLI_EFFORT_HELP,
+    CLI_EFFORT_METAVAR,
+    CLI_RECORD_STAMP_HELP,
     CLI_SESSION_MODEL_FLAG,
+    CODE_REVIEW_FIX_FLAG,
     CODE_REVIEW_MODEL_ALIAS,
-    CODE_REVIEW_PROMPT,
+    CODE_REVIEW_SLASH_COMMAND,
+    DEFAULT_CODE_REVIEW_EFFORT,
+    EFFORT_TOKEN_LIST_SEPARATOR,
     GIT_BINARY,
     GIT_PORCELAIN_FLAG,
     GIT_STATUS_SUBCOMMAND,
     HOST_PROFILE_ERROR_RETURNCODE,
     IN_SESSION_RETURNCODE,
+    INVALID_EFFORT_MESSAGE,
+    INVALID_EFFORT_RETURNCODE,
+    MAXIMUM_STAMP_MINT_PASSES,
     MODE_CHAIN,
     MODE_IN_SESSION,
     PERMISSION_MODE_BYPASS,
     PERMISSION_MODE_FLAG,
+    RECORD_STAMP_FLAG,
+    RESULT_KEY_BOUND_HASH,
     RESULT_KEY_DIRTY_TREE,
     RESULT_KEY_MODE,
+    RESULT_KEY_PASS_COUNT,
     RESULT_KEY_RETURNCODE,
     RESULT_KEY_SERVED_COMMAND,
+    RESULT_KEY_STAMP_MINTED,
+    STAMP_DID_NOT_CONVERGE_MESSAGE,
+    STAMP_DID_NOT_CONVERGE_RETURNCODE,
+    STAMP_STORE_IMPORT_FAILURE_MESSAGE,
+    STAMP_STORE_LIVE_SURFACE_HASH_NAME,
+    STAMP_STORE_MODULE_FILE_NAME,
+    STAMP_STORE_MODULE_NAME,
+    STAMP_STORE_RECORD_CLEAN_STAMP_NAME,
+    STAMP_STORE_RESOLVE_REPO_ROOT_NAME,
     SUCCESSFUL_REVIEW_RETURNCODE,
 )
 from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
@@ -115,6 +138,25 @@ class CodeReviewOutcome:
     is_dirty_tree: bool
 
 
+@dataclass(frozen=True)
+class StampMintOutcome:
+    """Outcome of a ``--record-stamp`` minting run.
+
+    ::
+
+        stable rc 0 pass  -> is_stamp_minted True, bound_hash set
+        cap hit / unstable -> is_stamp_minted False, non-zero returncode
+
+    The attributes carry the last review, whether a stamp was minted, the pass
+    count, and the surface hash the stamp was bound to when minted.
+    """
+
+    review_outcome: CodeReviewOutcome
+    is_stamp_minted: bool
+    pass_count: int
+    bound_hash: str | None
+
+
 review_claude_runner = run_claude
 review_host_profile_detector = detect_host_profile
 review_git_status_runner = subprocess.run
@@ -125,6 +167,65 @@ TextCapturingSubprocessRunner = Callable[
 ]
 
 
+def _stamp_store_file_path() -> Path:
+    """Return the stamp store module path in the sibling hooks/blocking tree."""
+    blocking_directory = Path(__file__).resolve().parent.parent / "hooks" / "blocking"
+    return blocking_directory / STAMP_STORE_MODULE_FILE_NAME
+
+
+def _load_store_from_spec(store_file_path: Path) -> ModuleType:
+    """Import the stamp store from *store_file_path*, re-raising a missing dep."""
+    blocking_directory_string = str(store_file_path.parent)
+    if blocking_directory_string not in sys.path:
+        sys.path.insert(0, blocking_directory_string)
+    module_spec = importlib.util.spec_from_file_location(
+        STAMP_STORE_MODULE_NAME, store_file_path
+    )
+    if module_spec is None or module_spec.loader is None:
+        raise ModuleNotFoundError(
+            f"could not create import spec for {store_file_path}",
+            name=STAMP_STORE_MODULE_NAME,
+        )
+    store_module = importlib.util.module_from_spec(module_spec)
+    sys.modules[STAMP_STORE_MODULE_NAME] = store_module
+    try:
+        module_spec.loader.exec_module(store_module)
+    except ModuleNotFoundError:
+        del sys.modules[STAMP_STORE_MODULE_NAME]
+        raise
+    return store_module
+
+
+def load_code_review_stamp_store() -> ModuleType:
+    """Import the stamp store module from the installed or repo hooks tree.
+
+    ::
+
+        code_review_stamp_store.py present -> module with record_clean_stamp
+        module file missing                -> ModuleNotFoundError (loud)
+
+    A genuine missing dependency of the store still raises rather than being
+    swallowed, so ``--record-stamp`` fails loudly when it cannot mint.
+
+    Returns:
+        The loaded ``code_review_stamp_store`` module.
+
+    Raises:
+        ModuleNotFoundError: When the store file is absent or a real import
+            dependency of the store is missing.
+    """
+    store_file_path = _stamp_store_file_path()
+    if not store_file_path.is_file():
+        raise ModuleNotFoundError(
+            f"code review stamp store not found at {store_file_path}",
+            name=STAMP_STORE_MODULE_NAME,
+        )
+    cached_module = sys.modules.get(STAMP_STORE_MODULE_NAME)
+    if cached_module is not None:
+        return cached_module
+    return _load_store_from_spec(store_file_path)
+
+
 def is_opus_session_model(session_model: str) -> bool:
     """Return True when *session_model* is the opus short alias (any letter case).
 
@@ -152,8 +253,6 @@ def decide_review_mode(*, host_profile: str, session_model: str) -> str:
             # ok: "in_session"
         decide_review_mode(host_profile="Claude", session_model="sonnet")
             # ok: "chain"
-        decide_review_mode(host_profile="ThirdParty", session_model="opus")
-            # ok: "chain"
 
     Args:
         host_profile: Detected host profile (``Claude`` or ``ThirdParty``).
@@ -168,20 +267,42 @@ def decide_review_mode(*, host_profile: str, session_model: str) -> str:
     return MODE_CHAIN
 
 
-def build_code_review_arguments() -> list[str]:
+def build_code_review_prompt(effort: str) -> str:
+    """Build the single-turn slash-command prompt for the given effort.
+
+    ::
+
+        build_code_review_prompt("low")   # ok: "/code-review low --fix"
+        build_code_review_prompt("xhigh") # ok: "/code-review xhigh --fix"
+
+    Args:
+        effort: A validated effort token from the ascending order tuple.
+
+    Returns:
+        The ``/code-review <effort> --fix`` prompt string.
+    """
+    return f"{CODE_REVIEW_SLASH_COMMAND} {effort} {CODE_REVIEW_FIX_FLAG}"
+
+
+def build_code_review_arguments(
+    effort: str = DEFAULT_CODE_REVIEW_EFFORT,
+) -> list[str]:
     """Return the argv tokens passed to ``run_claude`` for a chain review.
 
     ::
 
-        build_code_review_arguments()
-            # ok: ["-p", CODE_REVIEW_PROMPT, "--model", "opus", ...]
+        build_code_review_arguments("high")
+            # ok: ["-p", "/code-review high --fix", "--model", "opus", ...]
+
+    Args:
+        effort: Effort token embedded in the slash-command prompt.
 
     Returns:
         Ordered claude CLI arguments for the headless opus review slash command.
     """
     return [
         SINGLE_TURN_FLAG,
-        CODE_REVIEW_PROMPT,
+        build_code_review_prompt(effort),
         MODEL_FLAG,
         CODE_REVIEW_MODEL_ALIAS,
         OUTPUT_FORMAT_FLAG,
@@ -191,6 +312,29 @@ def build_code_review_arguments() -> list[str]:
     ]
 
 
+def validate_effort_token(effort: str) -> str | None:
+    """Return an error message when *effort* is unknown or unsupported.
+
+    ::
+
+        validate_effort_token("low")    # ok: None
+        validate_effort_token("ultra")  # flag: error mentioning ultra
+        validate_effort_token("bogus")  # flag: error listing allowed tokens
+
+    Args:
+        effort: Caller-supplied effort token.
+
+    Returns:
+        None when the token is allowed; otherwise a human-readable error.
+    """
+    if effort in ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER:
+        return None
+    allowed_tokens = EFFORT_TOKEN_LIST_SEPARATOR.join(
+        ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER
+    )
+    return INVALID_EFFORT_MESSAGE.format(effort=effort, allowed=allowed_tokens)
+
+
 def is_working_tree_dirty(working_directory: Path) -> bool:
     """Return True when the tree is dirty or ``git status`` fails.
 
@@ -282,7 +426,9 @@ def _run_claude_with_empty_stdin(
 ) -> ChainInvocationOutcome:
     working_directory_path = str(working_directory)
     with _CHAIN_RUNNER_LOCK:
-        previous_runner = chain_runner.chain_subprocess_runner
+        previous_runner: TextCapturingSubprocessRunner = (
+            chain_runner.chain_subprocess_runner
+        )
 
         def _runner_with_empty_stdin(
             all_invocation_tokens: Sequence[str],
@@ -296,6 +442,7 @@ def _run_claude_with_empty_stdin(
                 timeout_for_run = float(maybe_timeout)
             else:
                 timeout_for_run = None
+            forwarded_text_codec = collect_forwarded_text_codec(all_keywords)
             completed_process: subprocess.CompletedProcess[str] = previous_runner(
                 all_invocation_tokens,
                 capture_output=True,
@@ -304,6 +451,7 @@ def _run_claude_with_empty_stdin(
                 check=False,
                 stdin=subprocess.DEVNULL,
                 cwd=working_directory_path,
+                **forwarded_text_codec,
             )
             return completed_process
 
@@ -347,24 +495,55 @@ def _failure_code_review_outcome(returncode: int) -> CodeReviewOutcome:
         is_dirty_tree=False,
     )
 
+def _run_chain_review(
+    *,
+    working_directory: Path,
+    timeout_seconds: int,
+    effort: str,
+) -> CodeReviewOutcome:
+    all_claude_arguments = build_code_review_arguments(effort)
+    chain_outcome = _run_claude_with_empty_stdin(
+        all_claude_arguments,
+        timeout_seconds=timeout_seconds,
+        working_directory=working_directory,
+    )
+    return _chain_outcome(chain_outcome, working_directory=working_directory)
+
+
 def invoke_code_review(
     *,
     working_directory: Path,
     session_model: str,
     timeout_seconds: int,
+    effort: str = DEFAULT_CODE_REVIEW_EFFORT,
+    is_force_chain: bool = False,
 ) -> CodeReviewOutcome:
     """Run or hand off ``/code-review`` based on host profile and session model.
 
+    ::
+
+        Claude + opus, is_force_chain False -> in_session (no spawn)
+        Claude + opus, is_force_chain True  -> chain (headless spawn)
+        any host with sonnet                -> chain
+
     Args:
         working_directory: PR working tree used as cwd for the chain spawn.
-        session_model: Caller-stated session model short alias (for example
-            ``opus`` or ``sonnet``).
+        session_model: Caller-stated session model short alias.
         timeout_seconds: Timeout applied to each chain binary invocation.
+        effort: Effort token embedded in the ``/code-review`` prompt.
+        is_force_chain: When True, always spawn chain mode (used by
+            ``--record-stamp`` so the invoker observes the review).
 
     Returns:
         Structured outcome including mode, served binary, return code, and
         whether the working tree is dirty after a chain run.
     """
+    if is_force_chain:
+        return _run_chain_review(
+            working_directory=working_directory,
+            timeout_seconds=timeout_seconds,
+            effort=effort,
+        )
     host_profile = review_host_profile_detector()
     review_mode = decide_review_mode(
         host_profile=host_profile,
@@ -372,13 +551,193 @@ def invoke_code_review(
     )
     if review_mode == MODE_IN_SESSION:
         return _in_session_outcome()
-    all_claude_arguments = build_code_review_arguments()
-    chain_outcome = _run_claude_with_empty_stdin(
-        all_claude_arguments,
+    return _run_chain_review(
+        working_directory=working_directory,
         timeout_seconds=timeout_seconds,
+        effort=effort,
+    )
+
+
+def _surface_hash_before_and_after_are_stable(
+    before_hash: str | None,
+    after_hash: str | None,
+) -> bool:
+    if before_hash is None:
+        return False
+    if after_hash is None:
+        return False
+    return before_hash == after_hash
+
+
+def _mint_stamp_for_stable_pass(
+    *,
+    store_module: ModuleType,
+    working_directory: Path,
+    surface_hash: str,
+    effort: str,
+) -> bool:
+    resolve_repo_root = getattr(store_module, STAMP_STORE_RESOLVE_REPO_ROOT_NAME)
+    record_clean_stamp = getattr(store_module, STAMP_STORE_RECORD_CLEAN_STAMP_NAME)
+    repo_root = resolve_repo_root(str(working_directory))
+    if repo_root is None:
+        return False
+    record_clean_stamp(repo_root, surface_hash, effort)
+    return True
+
+
+def _mint_outcome_when_stable_clean(
+    *,
+    store_module: ModuleType,
+    working_directory: Path,
+    effort: str,
+    pass_number: int,
+    before_hash: str,
+    review_outcome: CodeReviewOutcome,
+) -> StampMintOutcome | None:
+    is_minted = _mint_stamp_for_stable_pass(
+        store_module=store_module,
         working_directory=working_directory,
+        surface_hash=before_hash,
+        effort=effort,
+    )
+    if not is_minted:
+        return None
+    return StampMintOutcome(
+        review_outcome=review_outcome,
+        is_stamp_minted=True,
+        pass_count=pass_number,
+        bound_hash=before_hash,
+    )
+
+
+def _unminted_pass_outcome(
+    review_outcome: CodeReviewOutcome, pass_number: int
+) -> StampMintOutcome:
+    return StampMintOutcome(
+        review_outcome=review_outcome,
+        is_stamp_minted=False,
+        pass_count=pass_number,
+        bound_hash=None,
+    )
+
+
+def _stamp_outcome_for_pass(
+    *,
+    store_module: ModuleType,
+    working_directory: Path,
+    effort: str,
+    pass_number: int,
+    before_hash: str | None,
+    after_hash: str | None,
+    review_outcome: CodeReviewOutcome,
+) -> StampMintOutcome | None:
+    is_stable = _surface_hash_before_and_after_are_stable(before_hash, after_hash)
+    is_successful = is_successful_code_review(review_outcome)
+    is_empty_surface = before_hash is None and after_hash is None
+    if is_successful and is_empty_surface:
+        return _unminted_pass_outcome(review_outcome, pass_number)
+    if is_successful and is_stable and before_hash is not None:
+        minted = _mint_outcome_when_stable_clean(
+            store_module=store_module,
+            working_directory=working_directory,
+            effort=effort,
+            pass_number=pass_number,
+            before_hash=before_hash,
+            review_outcome=review_outcome,
+        )
+        if minted is not None:
+            return minted
+    if is_stable:
+        return _unminted_pass_outcome(review_outcome, pass_number)
+    return None
+
+
+def _run_one_stamp_mint_pass(
+    *,
+    store_module: ModuleType,
+    live_surface_hash: Callable[..., str | None],
+    working_directory: Path,
+    timeout_seconds: int,
+    effort: str,
+    pass_number: int,
+) -> tuple[CodeReviewOutcome, StampMintOutcome | None]:
+    before_hash = live_surface_hash(str(working_directory))
+    review_outcome = invoke_code_review(
+        working_directory=working_directory,
+        session_model=CODE_REVIEW_MODEL_ALIAS,
+        timeout_seconds=timeout_seconds,
+        effort=effort,
+        is_force_chain=True,
+    )
+    after_hash = live_surface_hash(str(working_directory))
+    maybe_outcome = _stamp_outcome_for_pass(
+        store_module=store_module,
+        working_directory=working_directory,
+        effort=effort,
+        pass_number=pass_number,
+        before_hash=before_hash,
+        after_hash=after_hash,
+        review_outcome=review_outcome,
+    )
+    return review_outcome, maybe_outcome
+
+
+def _iterate_stamp_mint_passes(
+    *,
+    store_module: ModuleType,
+    live_surface_hash: Callable[..., str | None],
+    working_directory: Path,
+    timeout_seconds: int,
+    effort: str,
+    maximum_passes: int,
+) -> StampMintOutcome:
+    last_review_outcome = _failure_code_review_outcome(
+        STAMP_DID_NOT_CONVERGE_RETURNCODE
+    )
+    for each_pass_number in range(1, maximum_passes + 1):
+        last_review_outcome, maybe_mint_outcome = _run_one_stamp_mint_pass(
+            store_module=store_module,
+            live_surface_hash=live_surface_hash,
+            working_directory=working_directory,
+            timeout_seconds=timeout_seconds,
+            effort=effort,
+            pass_number=each_pass_number,
+        )
+        if maybe_mint_outcome is not None:
+            return maybe_mint_outcome
+    return _unminted_pass_outcome(last_review_outcome, maximum_passes)
+
+
+def invoke_code_review_and_record_stamp(
+    *,
+    working_directory: Path,
+    session_model: str,
+    timeout_seconds: int,
+    effort: str,
+    maximum_passes: int = MAXIMUM_STAMP_MINT_PASSES,
+) -> StampMintOutcome:
+    """Force chain review passes until the surface is stable, then mint a stamp.
+
+    Args:
+        working_directory: PR working tree used as cwd for each chain spawn.
+        session_model: Session model short alias (unused; chain mode forced).
+        timeout_seconds: Timeout applied to each chain binary invocation.
+        effort: Effort token the clean review records on the stamp.
+        maximum_passes: Hard cap on review passes before giving up.
+
+    Returns:
+        A StampMintOutcome for the last review and whether a stamp was minted.
+    """
+    del session_model
+    store_module = load_code_review_stamp_store()
+    return _iterate_stamp_mint_passes(
+        store_module=store_module,
+        live_surface_hash=getattr(store_module, STAMP_STORE_LIVE_SURFACE_HASH_NAME),
+        working_directory=working_directory,
+        timeout_seconds=timeout_seconds,
+        effort=effort,
+        maximum_passes=maximum_passes,
     )
-    return _chain_outcome(chain_outcome, working_directory=working_directory)
 
 
 def encode_code_review_outcome(
@@ -400,12 +759,28 @@ def encode_code_review_outcome(
     }
 
 
-def _build_argument_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        description=(
-            "Run built-in /code-review at high effort on opus, host-aware."
-        )
-    )
+def encode_stamp_mint_outcome(
+    mint_outcome: StampMintOutcome,
+) -> dict[str, object]:
+    """Encode a stamp-mint outcome as the JSON-serializable payload.
+
+    Args:
+        mint_outcome: The ``--record-stamp`` outcome to encode.
+
+    Returns:
+        A plain dict with the review fields plus mint metadata.
+    """
+    encoded_payload = encode_code_review_outcome(mint_outcome.review_outcome)
+    encoded_payload[RESULT_KEY_STAMP_MINTED] = mint_outcome.is_stamp_minted
+    encoded_payload[RESULT_KEY_PASS_COUNT] = mint_outcome.pass_count
+    encoded_payload[RESULT_KEY_BOUND_HASH] = mint_outcome.bound_hash
+    if not mint_outcome.is_stamp_minted:
+        if mint_outcome.pass_count >= MAXIMUM_STAMP_MINT_PASSES:
+            encoded_payload[RESULT_KEY_RETURNCODE] = STAMP_DID_NOT_CONVERGE_RETURNCODE
+    return encoded_payload
+
+
+def _add_review_arguments(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         CWD_FLAG,
         dest="working_directory",
@@ -426,37 +801,174 @@ def _build_argument_parser() -> argparse.ArgumentParser:
         default=DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS,
         help="Timeout in seconds applied to each chain binary invocation.",
     )
+
+
+def _add_stamp_and_effort_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        RECORD_STAMP_FLAG,
+        dest="is_record_stamp",
+        action="store_true",
+        help=CLI_RECORD_STAMP_HELP,
+    )
+    parser.add_argument(
+        CLI_EFFORT_METAVAR,
+        nargs="?",
+        default=DEFAULT_CODE_REVIEW_EFFORT,
+        help=CLI_EFFORT_HELP,
+    )
+
+
+def _build_argument_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Run built-in /code-review at a chosen effort on opus, host-aware."
+        )
+    )
+    _add_review_arguments(parser)
+    _add_stamp_and_effort_arguments(parser)
     return parser
 
 
+def _emit_invalid_effort_and_exit_code(effort: str) -> int:
+    error_message = validate_effort_token(effort)
+    if error_message is None:
+        return SUCCESSFUL_REVIEW_RETURNCODE
+    sys.stderr.write(error_message + "\n")
+    return INVALID_EFFORT_RETURNCODE
+
+
+def _import_failure_payload() -> dict[str, object]:
+    failure_outcome = _failure_code_review_outcome(INVALID_EFFORT_RETURNCODE)
+    encoded_payload = encode_code_review_outcome(failure_outcome)
+    encoded_payload[RESULT_KEY_STAMP_MINTED] = False
+    encoded_payload[RESULT_KEY_PASS_COUNT] = 0
+    encoded_payload[RESULT_KEY_BOUND_HASH] = None
+    return encoded_payload
+
+
+def _no_mint_outcome(returncode: int) -> StampMintOutcome:
+    return StampMintOutcome(
+        review_outcome=_failure_code_review_outcome(returncode),
+        is_stamp_minted=False,
+        pass_count=0,
+        bound_hash=None,
+    )
+
+
+def _mint_or_config_outcome(
+    *,
+    working_directory: Path,
+    session_model: str,
+    timeout_seconds: int,
+    effort: str,
+) -> StampMintOutcome:
+    try:
+        return invoke_code_review_and_record_stamp(
+            working_directory=working_directory,
+            session_model=session_model,
+            timeout_seconds=timeout_seconds,
+            effort=effort,
+        )
+    except ChainConfigurationError:
+        return _no_mint_outcome(CHAIN_CONFIG_ERROR_EXIT_CODE)
+    except ValueError:
+        return _no_mint_outcome(HOST_PROFILE_ERROR_RETURNCODE)
+
+
+def _emit_import_failure(import_error: ModuleNotFoundError) -> int:
+    sys.stderr.write(
+        STAMP_STORE_IMPORT_FAILURE_MESSAGE.format(error=import_error) + "\n"
+    )
+    sys.stdout.write(json.dumps(_import_failure_payload()) + "\n")
+    return INVALID_EFFORT_RETURNCODE
+
+
+def _record_stamp_exit_code(mint_outcome: StampMintOutcome) -> int:
+    if mint_outcome.is_stamp_minted:
+        return mint_outcome.review_outcome.returncode
+    if mint_outcome.pass_count >= MAXIMUM_STAMP_MINT_PASSES:
+        return STAMP_DID_NOT_CONVERGE_RETURNCODE
+    return mint_outcome.review_outcome.returncode
+
+
+def _emit_mint_outcome(mint_outcome: StampMintOutcome) -> int:
+    encoded_payload = encode_stamp_mint_outcome(mint_outcome)
+    did_not_converge = (
+        not mint_outcome.is_stamp_minted
+        and mint_outcome.pass_count >= MAXIMUM_STAMP_MINT_PASSES
+    )
+    if did_not_converge:
+        sys.stderr.write(
+            STAMP_DID_NOT_CONVERGE_MESSAGE.format(pass_count=mint_outcome.pass_count)
+            + "\n"
+        )
+    sys.stdout.write(json.dumps(encoded_payload) + "\n")
+    return _record_stamp_exit_code(mint_outcome)
+
+
+def _run_record_stamp_cli(
+    *,
+    working_directory: Path,
+    session_model: str,
+    timeout_seconds: int,
+    effort: str,
+) -> int:
+    try:
+        mint_outcome = _mint_or_config_outcome(
+            working_directory=working_directory,
+            session_model=session_model,
+            timeout_seconds=timeout_seconds,
+            effort=effort,
+        )
+    except ModuleNotFoundError as import_error:
+        return _emit_import_failure(import_error)
+    return _emit_mint_outcome(mint_outcome)
+
+
+def _run_plain_review_cli(*, parsed_arguments: argparse.Namespace, effort: str) -> int:
+    try:
+        review_outcome = invoke_code_review(
+            working_directory=parsed_arguments.working_directory,
+            session_model=parsed_arguments.session_model,
+            timeout_seconds=parsed_arguments.timeout_seconds,
+            effort=effort,
+        )
+    except ChainConfigurationError:
+        review_outcome = _failure_code_review_outcome(CHAIN_CONFIG_ERROR_EXIT_CODE)
+    except ValueError:
+        review_outcome = _failure_code_review_outcome(HOST_PROFILE_ERROR_RETURNCODE)
+    sys.stdout.write(json.dumps(encode_code_review_outcome(review_outcome)) + "\n")
+    return review_outcome.returncode
+
+
 def main(all_command_arguments: list[str]) -> int:
     """Run the invoker for CLI arguments and print the JSON outcome.
 
-    ``ChainConfigurationError`` and host ``ValueError`` still emit result JSON
-    on stdout (no traceback-only failure). The non-zero return code and null
-    ``served_command`` block a clean stamp.
+    ``--record-stamp`` forces chain mode and mints only on a surface-stable
+    returncode-0 pass; an unknown or ``ultra`` effort exits non-zero before any
+    review runs.
 
     Args:
         all_command_arguments: The argument vector after the program name.
 
     Returns:
-        The outcome return code (``0`` for in-session; chain return code otherwise).
+        The outcome return code (``0`` for in-session; chain return code
+        otherwise; non-zero when effort is invalid or minting fails to converge).
     """
     parser = _build_argument_parser()
     parsed_arguments = parser.parse_args(all_command_arguments)
-    try:
-        review_outcome = invoke_code_review(
+    effort_token = str(parsed_arguments.effort)
+    invalid_effort_exit_code = _emit_invalid_effort_and_exit_code(effort_token)
+    if invalid_effort_exit_code != SUCCESSFUL_REVIEW_RETURNCODE:
+        return invalid_effort_exit_code
+    if parsed_arguments.is_record_stamp:
+        return _run_record_stamp_cli(
             working_directory=parsed_arguments.working_directory,
             session_model=parsed_arguments.session_model,
             timeout_seconds=parsed_arguments.timeout_seconds,
+            effort=effort_token,
         )
-    except ChainConfigurationError:
-        review_outcome = _failure_code_review_outcome(CHAIN_CONFIG_ERROR_EXIT_CODE)
-    except ValueError:
-        review_outcome = _failure_code_review_outcome(HOST_PROFILE_ERROR_RETURNCODE)
-    encoded_payload = encode_code_review_outcome(review_outcome)
-    sys.stdout.write(json.dumps(encoded_payload) + "\n")
-    return review_outcome.returncode
+    return _run_plain_review_cli(parsed_arguments=parsed_arguments, effort=effort_token)
 
 
 if __name__ == "__main__":