# PR#138: The Status `ai-review/codex` Names Who Acts Next

Version: patch

> **WARNING:** This document describes only the change applied in this PR.
> It may already be outdated once the next PR is merged.
> Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.

## Problem

Gitea shows each `pending` status with the same yellow dot.
For `ai-review/codex`, that is the state of a running review and also the state that waits for the approval of a human,
e.g. "Codex review: a human approval of the head unlocks the merge".
So the human cannot see at a glance whether something still happens or whether it is their turn.

## Non-Goals

- No other state: a `warning` blocks the merge as well, but turns the summary of the PR red;
  Gitea 1.27.3 combines `warning` as `failure` (`modules/commitstatus/commit_status.go`, `Combine`).
- No change of the statuses of werkrevisor (`ai-review/gate`, `ai-review/assessment`).

## Specification

### Feature: the description of `ai-review/codex` starts with who acts next

#### Scenario#138.01: a status that waits for a human starts with "human 👤:"

… so that the human sees that it is their turn.

- **Given** a PR whose Codex review is critical and has no approval of a human for its head
- **When** the Codex runner updates the status `ai-review/codex`
- **Then** its description starts with "human 👤:"

##### Verified by

- [test_codexrunner.CodexRunnerTest.test_a_status_that_waits_for_a_human_starts_with_human](../../tests/test_codexrunner.py)

#### Scenario#138.02: each description starts with who acts next

… so that a status that still changes by itself is not mistaken for one that waits.

- **Given** a PR in one of the states queued, RED, sandbox broken, running, open findings, waiting for a human or passed
- **When** the Codex runner updates the status `ai-review/codex`
- **Then** its description starts with "queued ⏳:", "operator 🔧:", "running ⚙️:", "author ✍️:", "human 👤:", "done ✅:"
  or "done ☑️:"

##### Verified by

- [test_codexrunner.CodexRunnerTest.test_each_description_starts_with_who_acts_next](../../tests/test_codexrunner.py)
- [test_codexrunner.CodexRunnerTest.test_the_descriptions_are_the_documented_ones](../../tests/test_codexrunner.py)
- [test_codexrunner.CodexRunnerTest.test_a_broken_sandbox_stops_the_reviews](../../tests/test_codexrunner.py)
- [test_codexrunner.CodexRunnerTest.test_a_red_head_gets_no_codex_review](../../tests/test_codexrunner.py)
- [test_codexrunner.CodexRunnerTest.test_a_failed_run_is_retried_and_then_reported](../../tests/test_codexrunner.py)

## Solution

- `werkrevisor/codexrunner.py`: the descriptions are constants; each starts with who acts next and a symbol:

  | State | Description |
  |---|---|
  | `pending` | `queued ⏳: Codex reviews after werkrevisor` |
  | `pending` | `author ✍️: werkrevisor found RED; push a commit that fixes the cause` |
  | `pending` | `operator 🔧: the Codex sandbox fails on the workstation; see the runner log` |
  | `pending` | `running ⚙️: Codex review` |
  | `pending` | `author ✍️: resolve <n> open Codex finding(s)` |
  | `pending` | `human 👤: approve the head to unlock the merge` |
  | `error` | `human 👤: Codex review failed; approve the head to merge` |
  | `success` | `done ✅: Codex review passed` |
  | `success` | `done ☑️: Codex review failed; a human approved the head` |

  The blue `☑️` marks a pass that only the approval of a human gave, after a failed Codex review.
  The states stay as they were.
  After the deployment, the first run sets the status of each open PR without "WIP: " once more, with the new text;
  a WIP PR keeps its old text until it is ready again (review round 2).
- `tests/test_codexrunner.py`: the existing tests use the constants;
  a new test pins each text literally (review round 1), two new tests for the scenarios.
- A broken sandbox gets `operator 🔧:` instead of `queued ⏳:`, since Codex runs again only after a repair (review round 1).
- A RED head gets `author ✍️:` instead of `queued ⏳:`, since Codex skips it until a new commit (review round 2).
- `README.md`: section `[codex]`.
- `docs/werkrevisor.werkbaum`: node `#model.codex.who`.
- `werkrevisor/__init__.py` and `statistics/build.gradle.kts`: version 0.65.2, above PR#137 with 0.65.1.

Gitea stores the 4-byte symbols: the result comments of werkrevisor hold 🟠 and 🟡 already.

## Open Questions

None.