werkrevisor/docs/prs/2026-10-23-PR#138-codex-status-who.md

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

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
• test_codexrunner.CodexRunnerTest.test_the_descriptions_are_the_documented_ones
• test_codexrunner.CodexRunnerTest.test_a_broken_sandbox_stops_the_reviews
• test_codexrunner.CodexRunnerTest.test_a_red_head_gets_no_codex_review
• test_codexrunner.CodexRunnerTest.test_a_failed_run_is_retried_and_then_reported

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.