<!-- Source: https://console.uubright.com/docs/lead/ -->
# Lead tasks and workers

In the app, a workspace's lead is its **[Manager](https://console.uubright.com/docs/manager/)** and the tasks it
starts are its **workers**. This page uses the API's names.

The owner can mark a task as a lead when creating it with `POST /api/sessions`:

```json
{"prompt":"Plan and delegate this work","lead":{"workersAuto":false,"maxWorkers":4,"budgetUsd":5}}
```

Set `"agent":"codex"` to run the lead or workspace Manager with Codex. Its
`ccr-lead` tools create and follow workers just as a Claude lead's do. In a room,
Codex also receives `ccr-room` and the same room instructions. A handoff to
Codex carries the lead limits, workers and room handle to the new task, and moves
the workspace's Manager pointer when the old lead was its Manager. The old lead
stops when the new lead is ready.

The owner can later send `PATCH /api/sessions/:id` with `{"lead":{...}}`.
Only the owner token may set a lead's limits (`maxWorkers`, `budgetUsd`) or change an
existing task's `lead`. A paired device may create a lead with the default limits,
optionally with `workersAuto`, so a phone can start a workspace's
[Manager](https://console.uubright.com/docs/manager/); that gives the device nothing it couldn't already start as
separate tasks. Runner tokens can't set `lead` at all.
Settings on a lead are independent of room auto-pass. `maxWorkers` defaults to 8
live workers (maximum configurable value 32), `budgetUsd` defaults to $100
(maximum configurable value $10,000), and each worker accepts at most 10 lead
messages per rolling hour. Promoting an idle task restarts its runner so the tools and lead note
become available. A task currently working receives them when it next resumes. Changing an existing
lead's limits doesn't restart it: they apply the next time it starts a worker.

### Monthly budget

`budgetUsd` is a **monthly** budget. It counts the reported cost of the lead and all the workers it
started, live or finished, in the current calendar month of the **server's local time zone** (the
service's `TZ`; Workspace settings shows which). It resets at midnight on the first of each month, with
nothing to run: each task keeps its reported cost per month (`costByMonth`) and the month's spend is
their sum. Codex reports no cost, so Codex workers count as $0. Records from before this version had
their months rebuilt once from their event logs when the server started, reading each log in chunks
without keeping it in memory; spend a log can't place is counted in the month of the task's last update.

Spend is reported at API prices whatever the billing. On a **subscription login** that is an estimate, not a
bill, so reaching the budget is a **warning**: the Budget reached card appears in Needs you, says so, and the
lead keeps starting workers. Setting **Hard cap** (`hardCap: true` in `lead`, owner token only) makes it stop
at the budget anyway.

A login counts as a subscription only when the server confirms it. Claude Code reports no API key
(`apiKeySource: "none"`) for a claude.ai login, Bedrock, Vertex and a gateway alike, so the server also
requires all of these: the task is on the account route (not the CCR gateway), it wasn't continued on Claude
API, the environment it gets has no API key, gateway, Bedrock or Vertex setting (including saved model
access), and `claude auth status` with that environment reports a claude.ai first-party login with a
subscription type. For a Codex lead, `codex login status` must report a ChatGPT login. Every Claude worker
with spend this month must pass the same test. Anything else, including unknown billing, stops new workers
at the budget.

When this month's spend reaches the budget and it stops, `task_create` is refused with the spend and the reset date,
and the lead gets a **Budget reached** card in Needs you (`budgetHold` on the task) with the spend so far
and **Raise to $X** (double the budget, or enough to cover 1.5 times this month's spend, at most
$10,000; it never lowers a budget raised since, and at $10,000 the card says the budget is at its maximum instead). Running workers carry on. Raising the budget is the owner token's alone: a paired device sees
the card with Raise greyed out, and `PATCH` from it gets `403`. The card goes when the owner raises the
budget above this month's spend, or when the month ends.

Workspace settings has a **Manager limits** section for the workspace's Manager: this month's and
lifetime spend, Workers running against the cap, Codex workers, the billing and whether the budget warns or
stops, the reset date, and the budget, Workers at once, Workers may use Auto and Hard cap. Turning Hard cap
off asks first, like raising a limit. **Start your Manager** shows the limits the Manager will start with. Raising a limit there asks first. A paired device sees the values only.

In a room, messages between a lead and a worker it created pass automatically in
either direction, even when room auto-pass is off. This uses a room turn, wakes the
recipient, and appears in the room log as passed by `lead-pair`. Workers messaging
each other and unrelated tasks messaging the lead still wait for the owner unless
room auto-pass is on. A lead's posts to the owner are updates, under **Updates** in Needs you,
and don't notify; when it needs the owner to choose, it asks a
[decision](https://console.uubright.com/docs/tasks/#answer-decisions) with `ask_owner`.
Room budgets, deadlines, pause and turn limits apply to these passes.

The lead gets `ccr-lead` MCP tools. `task_create` accepts a `brief`, optional
`title`, `agent`, `projectId`, `permissionMode`, and `files`
(see [File overlaps](#file-overlaps)). Without `agent`, a worker uses the lead's own
agent if this computer has it, otherwise the one it has; the tool's description lists
the agents on this computer. A worker
inherits the lead's workspace and room, and by default its project or repository.
It is recorded with `createdBy` set to the lead task id. Workers do not become
leads. Worker permission mode cannot be wider than the lead's mode. The owner can
allow worker Auto explicitly with `workersAuto: true`; that does not allow
`bypassPermissions`.

| Tool | Result |
|---|---|
| `task_create` | Start a worker and return its compact status, with a `warning` when its `files` overlap another open worker's. `reviews` (a PR URL) makes it that PR's reviewer: only then can it [record a verdict](#the-review-loop). |
| `task_message` | Queue a message to one of this lead's workers, marked as from the lead. |
| `task_status` | State, counts and titles of open approvals and questions, last assistant text (up to 500 characters), branch, known PR URL, usage, `changedFiles` and `overlaps` for any task in the lead's workspace. |
| `task_wait` | Wait on any workspace task's events for idle after its queued turn, waiting for the owner, failed, exited, or a new PR; `timeoutMs` is capped at 60,000. Returns the same compact status. |
| `task_list` | List `mine` (default), `room`, or `workspace` tasks, each with its `changedFiles` (up to 20) and `overlaps`. |
| `task_stop` | Stop one of this lead's workers, keeping its workspace. |
| `task_retire` | Free the disk of one of this lead's workers that is stopped or exited. Its unpushed and uncommitted work is backed up first; its record, log and deliverables stay. See [Retire and delete](https://console.uubright.com/docs/tasks/#retire-and-delete). |
| `review_pr` | Start a fresh read-only reviewer for an open PR, on the agent opposite to the author's: `repo` (`OWNER/NAME`), `number`, optional `focus`. It ends in a PASS or FAIL verdict on the PR's head. See [Local PR review](#local-pr-review). |
| `task_review_done` | Record an independent review's outcome for a PR at its current head; releases a [risky PR](#risky-prs) held for review once the reviewer said PASS. |

`task_status` and `task_wait` give a lead read access to **every task in its
workspace**, including tasks it did not create. In the Default workspace, that
means every task on the server. They can see the task's last assistant text,
owner-request titles, PR and usage. Only workers that lead created can receive
`task_message`, `task_stop` or `task_retire`, and `task_retire` refuses a worker
that is still running or has a durable job running. The lead note asks leads to retire workers they stopped or
replaced; the server also [retires quiet workers](https://console.uubright.com/docs/tasks/#automatic-retire) whose
work is pushed or whose PR is merged or closed.

Lead actions appear as plain events in the lead's task view and as notices in
its room. The MCP server reaches the control plane through the runner's local
socket and authenticated WebSocket. The task never receives the owner token.
Non-lead tasks do not have the `ccr-lead` MCP server. The control plane also
checks the owner's grant on every tool call.

The tools cannot answer approvals or questions, merge, manage credentials,
delete tasks or data, or increase their own limits. Those actions remain with
the owner. Retiring deletes nothing that can't be made again. A lead may inspect
tasks in its room or workspace, but may message, stop and retire only workers it
created.

## Running several workers

Parallel work is only faster when the pieces don't touch each other. Conflicting branches cost a merge and a full test run every time something else lands, so a one-hour change can take three. The lead follows these rules:

1. **Plan by features, schedule by files.** Plan the work as features, as usual. Before running them in parallel, note which files each will change. Features that overlap run one after another, or go to one worker; features in separate parts of the code run in parallel. Keeping the code modular means more features land in separate files.
2. **One owner per area.** Each part of the code base (for example the sidebar, the runner, the relay) has one worker at a time. Follow-ups in that area go to the same worker.
3. **At most two open PRs per area, and no stacks.** Merge before starting the next change in the same place. Split large work into small PRs that each merge on their own, not into a chain of PRs on top of each other.
4. **Test capacity is shared.** Workers run the tests for what they touched; the full suite runs once, when the PR is about to merge. Long commands run as jobs or in the foreground with a timeout, never as a background command the agent then waits on.
5. **Review before the final full run.** Review the change first and send all findings in one message. Risky PRs get an independent review the server enforces: see [Risky PRs](#risky-prs).
6. **Remove conflict magnets early.** Generated files committed to the repository, versions bumped by hand in every change, and single large files that every feature edits make every pair of branches conflict. Fix those first.

### File overlaps

The control plane keeps rule 1 checkable. For every open worker it tracks the
files its branch changes:

- **Worktree:** at the end of each turn that changed something, the runner diffs
  the worktree (commits, staged and unstaged edits, new files) against the commit
  the task started from. This works for host and container tasks alike.
- **PR:** when PR watch sees a new head commit on a tracked PR, it reads the PR's
  file list through `gh api` (renames count under both names). A failed read keeps
  the last list.

A task's changed files are both lists together, for its open PRs only. Open work
is any task other than a lead, reviewer or chat that isn't retired and is either
live or has an open PR; a task whose PRs all merged or closed no longer counts.

`task_status` and `task_list` return `changedFiles` (up to 50 and 20,
`changedFilesTotal` when there are more), any `declaredFiles`, and `overlaps`:
other open work in the same project (or, without a project, the same repository)
whose changed or declared files include the same files, each as
`{taskId, title, files}`.

`task_create` takes optional `files`, the repository-relative paths or globs the
worker is expected to change (`src/server/public/board.js`,
`src/server/*.ts`, `docs/`; `*` stays inside one directory, `**` crosses
directories, a trailing `/` means everything under it; at most 100). They are
stored on the worker as `declaredFiles`. If they overlap an open worker's changed
or declared files, the result carries a `warning` naming each worker and the
files, and the lead's log records it. It is a warning, not a refusal: the worker
starts either way, so the lead can run the work in order or hand it to one worker.

The board shows a small amber "Overlaps …" line on each affected worker's card.

### Reviewer verdict on every Worker PR

On a server that can run a reviewer (host mode, with Claude Code or Codex
installed), every Worker's PR waits for an independent reviewer's **PASS** on its
current head commit before the lead hears it is ready:

| Card | When | What releases it |
|---|---|---|
| **Needs reviewer verdict** | no [`review_pr`](#local-pr-review) verdict yet | a PASS on this head |
| **Verdict stale · new commits** | the verdict is for an older head | a PASS on the new head |
| **Reviewer FAIL** | the reviewer found a P0 or P1 on this head (or said FAIL) | a PASS on a new head, or the owner |

A FAIL can't be released by any agent: not by the lead's `task_review_done`, and not by
asking the worker. The worker fixes the findings and pushes, and a new review runs. The owner can still
let the current commits through with **Skip review**, and decides on merging, as always.
Once the head has a PASS, a PR that touches no risky path is released; a risky one
still needs the recorded review below. On servers that can't run reviewers
(Docker mode), only risky paths are held, as before, so nothing waits on a review
that can't run. A FAIL that did run still holds the PR there.

The verdict shows on the task's PR card ("Reviewer PASS · 1 P3 · abc1234 · Codex
(other agent)"), on the ready-to-merge card in Needs you, on the board and in
the review queue, and in the lead's ready and held messages. It's always tied to one head commit; after a push it
reads "Reviewer verdict is for abc1234; new commits since".

### Risky PRs

Some changes cost much more when they're wrong than others. A PR is **risky**
when its diff touches the repository's risky paths. When a worker reports such a
PR `ready`, the control plane holds it as "needs independent review": the lead
gets a held message naming the risky areas and files instead of a plain Ready,
the board's card says **Risky · review needed**, and the review queue marks it.
It stays held, after the reviewer verdict above, until both:

1. an independent review has run on the PR's current head commit: a local
   [`review_pr`](#local-pr-review) that posted its comment, or a reviewer task the
   lead started (passed as `reviewer`); and
2. the lead has recorded the outcome with `task_review_done`.

| Argument | |
|---|---|
| `pr` | The PR's URL, or `#number` when only one PR in the workspace has it. |
| `verdict` | `approve` (no blocking findings left) or `fix` (fixes needed first; the PR stays held as **Reviewed · fixes requested**). |
| `rechecked` | `true` once the lead has rechecked fixes pushed after the review. |
| `reviewer` | The reviewer task's id, for a review that wasn't `review_pr`. It can't be the author or the lead. |
| `note` | Optional, up to 500 characters. |

When new commits arrive after a review, the PR is held again as **Reviewed ·
recheck needed**, and recording the new head needs `rechecked: true`. Each record
applies to the head commit it was made on. A PR that touches no risky path needs
only the reviewer verdict, where one is required.

The owner or a paired device can waive a held review with **Skip review** and a
reason of 10–500 characters. The server checks the live PR head, records the
authenticated actor, reason, full head SHA and time in the task and activity
audit, then marks `uubright/review` successful on that exact head with a
**Review waived** description. A later push is pending again. Agents cannot
waive a review. The waiver response follows the durable audit write; only that
PR's card and commit status are reconciled asynchronously, and a failed status
write is shown on the card and retried.

#### Risky paths: `.uubright/review.json`

The patterns are read from the repository's `.uubright/review.json` on the PR's
**base** branch, never from the PR itself, so a PR can't make itself safe. A PR
that edits `.uubright/review.json` is always risky. The file is optional:

```json
{
  "defaults": false,
  "risky": {
    "Auth and permissions": ["src/server/devices.ts", "src/drivers/**"],
    "Relay crypto": ["src/relay/**", "src/server/public/relay/e2ee.js"]
  }
}
```

- `risky` maps an area name (shown to the lead and on the board) to paths and
  globs, as for `task_create` `files`: `*` stays inside one directory, `**`
  crosses directories, a trailing `/` means everything under it.
- `defaults` (default `true`) keeps the built-in areas below; an area with the
  same name as a built-in one replaces it. `false` uses only the file's areas.
- `$comment` is ignored.
- `autoReview` is optional and off by default. See [Automatic PR review](#automatic-pr-review).

Without the file, or with an invalid one (the lead's message says why), these
built-in areas apply: auth and permissions (`**/*auth*`, `**/*permission*`,
`**/*login*`, `**/*token*`, `**/*credential*`, `**/*sandbox*`), secrets
(`**/*secret*`, `**/.env*`, `**/*keychain*`, `**/*vault*`), deletion and retire
(`**/*delete*`, `**/*retire*`, `**/*cleanup*`, `**/*purge*`, `**/migrations/**`),
crypto (`**/*crypto*`, `**/*encrypt*`, `**/*e2ee*`, `**/*cipher*`), and automatic
model turns and retries (`**/*retry*`, `**/*retries*`, `**/*cron*`,
`**/*schedule*`, `**/*webhook*`). The ccr-cloud repository has its own file
listing its device and owner-token code, plugin secret stores, retire and
cleanup, relay crypto, and the stall check, recovery, PR routing, rooms and
messaging that start model turns by themselves.

The PR's files are read through `gh api` whenever PR watch sees a new head (see
[File overlaps](#file-overlaps)), and its risk is worked out at the same time.

## Manager playbook

Practices that made a long run of parallel work go well, and the mistakes behind them. They apply to any Manager, whatever the project.

**Briefing workers**
- Start workers in Auto mode unless the owner says otherwise. A worker that stops to ask for every command is slower than one you review afterwards.
- Give each worker a complete brief: the goal, decisions already made (and by whom), files other workers are changing right now, the final check to run, and how to report. A clear task needs no plan round trip; a fuzzy one does.
- Codex workers open PRs and post comments with the `gh` CLI, not the GitHub connector: connector calls wait for a manual approval even in Auto mode.
- Reuse a worker that just finished in the same area for the next change there; it already knows the code.

**Reviewing**
- Changes that touch secrets, credentials, deletion of user data, auth, encryption, or anything that runs automatically and costs money (nudges, retries) are [risky PRs](#risky-prs): the server holds their Ready until a separate reviewer has run on the current head and you record the outcome with `task_review_done`. Give the reviewer an attack list, not your conclusion: "can the agent read the secret", "can retire lose a stash", "can a nudge repeat forever".
- Ask the reviewer to reproduce each finding, and when the worker says it is fixed, send the same reviewer back to rerun its reproductions against the fix. Fixes for a security finding often open a second path; one recheck round is cheap (the hold returns on every new head and needs `rechecked: true`).
- Check facts at the source, not from summaries: a review summary can be stale, a remote-tracking ref can point at a deleted branch, a worker's "Ready" may predate its last push.
- Check licenses before borrowing code or skills. A bundled library can carry a copyleft dependency (and code you can read is not always code you may ship).

**Bugs the owner reports**
- Reproduce first, with a failing test, then fix; post the root cause in one or two plain sentences. Several of the worst bugs looked like one thing and were another (a crash that showed as a page-load error, a test-browser quirk that looked like a Safari freeze).
- Give the owner a workaround right away if one exists, then the fix.

**Merging and deploying**
- One heavy test run at a time on a shared host. Under load, timing-sensitive tests fail and hide real results; rerun a failure alone before believing it, and record genuinely flaky tests.
- Don't rerun a full check just because the base moved; the merge itself reruns it. Do rerun after changing code.
- Run the owner journeys (or the project's end-to-end check) before deploying a batch, on a quiet host.
- Production deploys of services the owner runs, and merges in repositories the owner merges, stay with the owner: give the exact command and check the result afterwards.

**Talking to the owner**
- Lead with the result. Link every PR, issue and file you mention.
- Ask decisions with `ask_owner`: one short question, each choice with a label and a one-line description, your recommendation marked. Don't ask what you can check yourself.
- Say plainly when a merge went in with a caveat (a flaky test rerun, a skipped check) and why.
- Destructive actions stay with the owner; anything automatic that frees space must back up first and never touch work it can't restore.

## Worker states and stalls

A worker can end a turn saying it will check on something later with nothing set
to wake it, and then sit idle unnoticed. To prevent that, every worker reports
where it stands with the `ccr-task` tool `report_state`, and its note tells it to
call the tool at the end of every turn:

| State | Arguments | Meaning |
|---|---|---|
| `done` | | Finished; nothing more to do. |
| `ready` | `pr`: a PR URL, or the number of a PR the task opened | Ready for review. |
| `waiting_on` | `on`: `lead`, `owner`, `job:<id>`, `review:<pr>` or `external:<what>`; optional `until`, an ISO time | Waiting, and on what. |
| `blocked` | `reason` | Can't go on without help. |

Every state takes an optional one-line `note` for the lead. Workers are tasks
with `createdBy` (started by a lead's `task_create`) or `parentTaskId` (started
through the API by another task, such as a Manager), and members of a room that
has a lead, when they are created. Only workers get the tool; an API worker with
`parentTaskId` has it even outside a room, so it can reach its lead.

The state is stored on the task (`workerState`), shown beside the task's status in
its header, and logged in its feed. A state is current until the worker's next
turn starts; a turn that ends without a new report leaves no current state.

Once a minute the control plane checks idle workers:

- **No current state and no running job for over 5 minutes:** the worker is
  marked stalled and gets an automatic message: "Say what you're waiting on with
  report_state, or start a job that wakes you". It is nudged once per reason
  (no state, a state from before its latest turn, a job that stopped, a wait past
  its until): a new report clears the flag, but a later stall for the same
  reason is only flagged, so a worker can't answer every nudge with the same
  non-answer. Tasks the owner started (a room member with no parent task) are
  flagged but never nudged or woken.
- **`waiting_on` `lead` for over 10 minutes:** the lead gets one message naming
  the worker and its note, and is listed on the Stalled row.
- **`waiting_on` `job:<id>`:** fine while the job runs; its end wakes the worker.
  A report naming a job that isn't running is refused, with the reason, so the
  worker reports what it is actually waiting on.
- **`waiting_on` with `until`:** the time must be at least 5 minutes ahead. Once
  it passes (other than for lead or owner), the worker is woken once per until
  value to recheck.
- **`ready`:** for a [risky PR](#risky-prs) still held, the lead gets one held
  message per head and hold instead. Otherwise the lead gets one message per PR, however often it is reported,
  and the PR shows in the board's **Review queue** until it merges or closes, the
  worker reports something else, or the owner or a lead stops or retires the worker. The server tracks a reported
  PR on GitHub, whatever its repository, so the queue follows its real state. Comments already on it aren't news,
  and a PR closed and reopened comes back. An idle worker retired automatically, or one whose sandbox stopped, keeps
  its open PR in the queue. If GitHub doesn't answer, the item stays and says **PR state unknown**.
- **`waiting_on owner`:** becomes a decision card in **Needs you**, so it never sits only in chat. Put the question
  in `note` and the choices in `options`. An open `ask_owner` card from the same worker is enough on its own.
- **`blocked`:** the lead gets one message per reason.

Each automatic nudge or wake is a model turn, so a worker gets at most 3 an hour
and 10 in its lifetime. After that it is only flagged on the Stalled row ("no
automatic nudges left") for the lead or the owner to look at.

A worker waiting on the owner (`waiting_on` `owner`, or an open decision,
approval or form), with a running job, a recovery card, or a message about to
start is covered and never flagged. The board's **Stalled** row lists each
workspace's uncovered idle workers with the reason, the tasks whose running turn
[stalled](https://console.uubright.com/docs/reliability/#stalled-tasks) (they keep their recovery card in Needs you), and leads
a worker has waited on for too long.


### The review loop

The server keeps every open PR moving, so nobody has to watch GitHub. Once a minute it works out what each PR needs
at its current head and sends only what hasn't gone yet. Its record, `review-loop.json` in the data folder, survives a
restart.

| The PR | What happens |
|---|---|
| **PASS on its head** | The Manager is woken once. A non-risky PR under `merge: manager` stays on the Manager page; the Manager uses the gated merge script and posts the result in Updates. If merging is the owner's, a **Ready to merge** card goes to Needs you only when GitHub would merge it, with reminders after 4 and 8 hours. Until then the board says what blocks it and who acts next. |
| **FAIL on its head** | The Manager is woken once, and the blocked board card names the author as the next actor. A local reviewer or designated Worker reviewer queues one sanitized exact-head repair brief to the author, including under Ask routing. The Manager can inspect queued, delivered, and new-head handoff status without reviewer text. |
| **New commits after a FAIL** | Once the head has rested 3 minutes (20 if its author is still working), the Worker named to review the PR gets the new head and its findings if it's alive and hasn't pushed; otherwise `review_pr` runs for the Manager. The Manager is told. A fork PR, whoever opened it, or one no task tracks by an author without write access, is never rechecked by itself: the Manager is woken once per FAIL to decide. |
| **No verdict on the head for 60 minutes** | An idle reviewer is nudged once, then the Manager is woken 60 minutes later. With no reviewer alive, the Manager is woken at once. A running reviewer or author is left alone. |
| **New PR no task tracks** | It shows on the board, and the Manager is woken to assign a review. PRs already open at a repository's first scan show, but don't wake anyone. |

A **verdict** is a record on the server, never what a PR comment says, because every task posts to GitHub as one login
and a comment can be edited. It is one of:

- a [`review_pr`](#local-pr-review) reviewer's verdict;
- `ccr-task report_review` from a Worker started with `task_create reviews: <PR URL>`. Only that Worker can record on
  that PR, at the head GitHub says is current, with the full SHA, once per head. A task that pushed anything can't. It
  moves the loop, but doesn't release the verdict hold, which needs `review_pr` or the owner. A FAIL queues a server-written
  repair brief with severity counts and the validated review-comment link. The Manager can inspect its safe handoff
  state with `task_status`; a capped brief retries after a restart, and a new head retires the old brief;
- the Manager's `task_review_done` naming a `reviewer`.

**People with their own GitHub login** count only if the owner lists them in the workspace's `trustedReviewers`
(`PATCH /api/workspaces/<id>`, owner token). A listed login's comment counts if its first line has `PASS` or `FAIL` with
the head's full 40-character SHA beside it. An edited PASS doesn't count, a login the agents use or the PR's author can't
be listed into counting, and a comment's PASS never outranks a record on its head.

A **FAIL on the head pulls a PASS**, whichever came first: it only ever stops a merge. A held PR's card says why and has
no Merge button. So does a PR whose files weren't all read at this head, or whose `review.json` couldn't be read.

**Watched repositories** are the workspace's projects, plus repositories where a tracked PR lives and this login can
push. Open PRs are listed every 3 minutes with ETags.

**Cost:** each wake is a model turn, so a Manager gets at most one message a tick and 6 an hour, one PR at most 3 of
those, and a PR gets at most 5 automatic rechecks, at most 4 an hour per workspace. An untrusted PR wakes the Manager
once as new and once as stale until it gets a verdict, however often its author pushes, and new untrusted PRs are held to
3 an hour per workspace. Quiet hours hold wakes, rechecks
and nudges until morning. Anything held goes out later, together; the board card says why it waits. PR titles, comment
text and fork file names never reach the Manager; it gets risky areas, the owner's card gets the paths.

**Who merges:** the owner, by default. This repository sets `"merge": "manager"` in `.uubright/review.json` on the base branch. It leaves
tracked PRs whose risk was read at this head and is empty to the Manager, so no owner card appears for them. The Manager
uses `scripts/merge-pr.sh` after the exact head passes review. The policy changes who is told; it grants no permission.
Risky paths, held PRs and PRs no task tracks remain the owner's. Only a ready owner decision appears in Needs you;
drafts, failed or pending checks, unresolved threads and conflicts stay blocked on the board with the reason and next actor.
A PR no task tracks gets the same Merge bar as a tracked one, read again at the tap.

Everything the loop does is on the PR's board card and in the activity log.

## PR review routing

The control plane polls every PR tracked by a task through `gh api`, using the task's
workspace GitHub login or token. It needs no inbound webhook. A runner PR action
is tracked automatically. When an agent opens one with `gh pr create`, the server
also detects the URL in that command's output; an assistant's statement that it
opened a PR can identify one too. Before adoption, the server checks that the
open PR is in the task repository and uses its work branch or a branch the task
pushed. For an assistant statement, it also checks the PR author against the
workspace GitHub login and the PR creation time for other branches. Merely
mentioning or reviewing a PR does not attach it. A lead's own PR routes to
the lead. The owner can use **Track PR…** on any task to attach a PR, or stop
tracking one. Several PRs can be tracked independently on one task. Review comments,
reviews, issue comments, and failed checks become a Needs-you item on the author
task by default. Open that task and select **Send** to queue a message containing
the feedback links and shortened bodies. The message asks the author to address
the feedback, reply on each comment, push, and leave merging to the owner.

Set `prRouting` to `auto` on a task or its lead to send new feedback directly to
the author. The task's setting takes precedence. A room can also set
`prRouting`; a lead setting takes precedence over the room. Automatic routing
shares the lead's 10 messages per worker per hour cap. Feedback that hits the
cap remains on the task for the owner to send. Same-login comments posted during
the author task's turn are treated as its own replies; comments posted while it
was idle still route, including owner and lead comments from the same GitHub
account. After a reviewed PR receives an author push, its lead gets a
re-review message.

The task card shows check results, merged or closed status, and when checks are
green, the PR is mergeable, and review threads are resolved, **Ready to merge**.
Merging from the app is always the owner's; no agent receives a merge request, and a repository's `"merge": "manager"` only changes who is told (see [the review loop](#the-review-loop)).

## Local PR review

The console writes the classic GitHub commit status `uubright/review` on each
exact PR head. A newly discovered head and a review in progress are **pending**;
an independent PASS is **success** and FAIL is **failure**. Pushing another
commit starts a new pending status, so an old PASS cannot turn the new head
green. The status description is short and its link opens the task. For an
outside PR, it opens the Manager task when one is available. The PR comment and
local review record remain the source of the verdict.

The workspace GitHub credential needs **Commit statuses: Read and write** on
each repository (a classic personal access token needs the `repo` scope). A
missing permission makes `review_pr` return a specific setup error before it
starts a reviewer. The PR card also shows a status posting error until the
credential is fixed and the next poll retries. Set `CCR_CLOUD_PUBLIC_URL` to
the console's reachable address so GitHub's status link opens the task from
other devices.

`review_pr` (or `POST /api/reviews` with the owner token, for the owner's own
assistant) reviews a PR on this host instead of waiting for GitHub's Codex
review. Leads are told to use it, and on repositories that rely on it, such as
the ccr-cloud repos, not to wait for GitHub's Codex review. The PR is untrusted
input throughout.

### Automatic PR review

An owner can opt a watched repository in by committing this setting to its
default branch:

```json
{
  "autoReview": {
    "enabled": true,
    "maxConcurrent": 2,
    "skipDrafts": true
  }
}
```

The default is `enabled: false`, `maxConcurrent: 2`, `skipDrafts: true`.
`maxConcurrent` accepts 1–16. The console reads this setting from the
repository default branch, regardless of the PR's target branch or head, and
caches successful reads for 30 seconds. A PR author cannot opt in by targeting
an unprotected branch with their own setting. A
failed refresh pauses automatic scheduling until the next successful read,
including manual fallback wakes and rechecks, so the PR cannot opt itself in or weaken its own gate.
No team repository is opted in by this release. The repository also needs a
local checkout and the GitHub permissions described above.

When enabled, the review loop starts an independent `review_pr` on each new or
updated head after it rests for 3 minutes (up to 20 while its author works).
It includes drafts only when `skipDrafts` is false. The loop holds at most
`maxConcurrent` active reviewers per repository across workspaces; an old-head
review must finish before the new head of that PR starts. A durable reservation
and reviewer record prevent another paid review of the same head after a
restart. To bound a busy repository, each tick examines at most 16 eligible
PRs, reads at most 16 base policies, and attempts at most four review launches, rotating through the rest on
later ticks. A durable per-repository budget starts at most 12 paid automatic
reviews per rolling hour; queued PRs resume as the window clears. Host reviewer
capacity and quiet hours still apply. The first scan does not buy reviews of
heads already open before the loop starts; later pushes are eligible. Owner
stops and ignored PRs are never launched automatically. Manual recheck limits govern the
Manager-driven path; automatic review uses the repository hourly budget so a
new head after a FAIL is not stranded at a manual cap. A preexisting failed
head is not bought again on the loop's first run. A temporary review-launch
failure leaves the head waiting and retries with a bound; repeated failure or
a reviewer that finishes without a verdict wakes the Manager once with the
reason and the manual `review_pr` action. A base
config read failure pauses automatic scheduling and rechecks until the next
read succeeds; explicit manual `review_pr`
remains available. The exact-head commit status remains pending until a PASS,
FAIL or human waiver is recorded.

The board keeps a waiting or started review label across ticks. A repository
concurrency cap or the hourly automatic budget also shows a waiting reason and
wakes the Manager once; scheduling resumes when that limit clears. A review
marker without a local reviewer or verdict record wakes the Manager to inspect
the record, without starting another paid review. Slow automatic launches do
not delay verdict wakes or an owner's waiver; a slow default-branch policy read
also does not delay waiver status reconciliation. For draft reviews enabled by
`skipDrafts: false`, verdicts reach the Manager while the PR is still a draft.

### Review flow

1. The repository must belong to a project in the task's workspace, as a local
   checkout on this server whose configured `origin` is that repository.
2. The control plane reads the PR through `gh api` with the workspace's GitHub
   login. If that login already posted a review comment for the head commit, it
   returns the comment's URL instead of starting another review. Marker comments
   from anyone else don't count. A review already running for that commit is not
   started twice.
3. The server fetches the PR head and its base into that checkout with its own
   Git login, so the reviewer needs no credentials. It then starts a **fresh**
   reviewer task in the project, on the **agent opposite to the author's**: a
   Codex reviewer for a Claude Code PR, a Claude Code reviewer for a Codex PR
   (for a PR no task tracks, Codex). When that agent can't run here (Codex not
   installed or its sandbox not confirmed; Claude Code not installed), the
   reviewer is a fresh read-only session of the author's own agent, and the PR
   comment, the `review_pr` result (`independence: "same-agent"`, `note`) and
   the verdict say so and why. The reviewer is never the task that wrote the PR,
   nor the lead that asked. Its checkout is its own clone of the local checkout
   (not a shared worktree, so the owner's `.git/config` stays out of reach), at
   the PR head merged with its base branch, with git hooks off. When the two conflict, it
   reviews the head alone and logs a warning. The project's setup script and
   setup variables never run for a reviewer, since they would run the PR's code
   outside the sandbox.
4. **A Codex reviewer** runs Codex's built-in review (`review/start`) in Codex's
   read-only sandbox. It can read the code and run commands that only read, such
   as the typecheck or tests when `focus` asks for them. Any request for more
   access, file change, MCP tool call or question is declined without asking
   anyone. The reviewer gets:
   - its own Codex home holding only a link to the Codex login and a permission
     profile that lets commands read only its checkout, the Node and npm it
     runs by exact path, and the system's minimum, so not the host's files or
     credentials. None of the owner's `config.toml`, MCP servers, hooks or
     trusted projects apply, and git ignores the host's global and system Git
     settings;
   - no uuBright Console tools (artifacts, rooms, leads);
   - no Git, GitHub or gateway credentials in its runner or agent environment,
     an empty `gh` config so `gh` can't fall back to the host login, and a
     `pushurl` that goes nowhere.

   The read boundary is that profile, and it fails closed. Before starting a
   reviewer, the server checks that this host's Codex reports the profile as in
   force; the reviewer checks again when it starts. Where Codex can't enforce it
   (for example, a host without `bwrap`, or with unprivileged user namespaces
   restricted on Linux; a Codex that doesn't confirm its Seatbelt profile on a
   Mac), Codex doesn't review, and a Claude Code reviewer does instead. No
   reviewer runs unconfined.

   **A Claude Code reviewer** can read the checkout and nothing else, and can't
   change anything. The boundary is Claude Code's own, checked on Claude Code
   2.1.312, and needs no OS sandbox, so it works the same on Linux and macOS.
   It is started as `claude --restricted --safe-mode --strict-mcp-config --tools
   Read,Grep,Glob`:
   - `--tools Read,Grep,Glob`: those are its only tools. Write, Edit, Bash and
     WebFetch don't exist in the session, so it can't change files, run
     commands, push or reach the network. It reviews by reading, so it can't
     run the typecheck or tests: ask for a Codex reviewer when that matters.
   - `--restricted`: the file tools are confined to the checkout, with
     symlinks resolved (a link pointing out of the checkout is refused), and
     user, project and local settings files are ignored, so a PR's
     `.claude/settings.json` hooks never run.
   - `--safe-mode`: no CLAUDE.md, skills, plugins or hooks.
   - `--strict-mcp-config` with no MCP config: no MCP servers and no uuBright Console tools.

   The runner denies every permission request without asking anyone. It stops
   the reviewer if Claude Code's start-up message lists any other tool or an MCP
   server, and the server checks the same message again before posting. A Claude
   Code too old for these flags fails to start, so the review fails instead of
   running. Like a Codex reviewer, it has no Git, GitHub or gateway
   credentials, an empty `gh` config, git without the host's settings or hooks,
   and a `pushurl` that goes nowhere. Its model access is the CCR client key, a
   Bedrock profile or this server's own Claude Code setup, never a raw saved key. A Claude reviewer must end its answer
   with `VERDICT: PASS` or `VERDICT: FAIL`. Without that line it posts nothing.

   When neither can run, `review_pr` refuses (`409`) with what this host lacks.
   On Linux: "No reviewer can run on this server: Codex needs an enforced
   sandbox (bubblewrap installed and unprivileged user namespaces allowed), and
   Claude Code isn't installed. Install Claude Code for a read-only Claude
   reviewer that needs no sandbox." On a Mac it names macOS Seatbelt and Codex
   0.163 instead of bubblewrap. A server in Docker mode always refuses:
   reviewers need host mode.

   The reviewer's own text never leaves the server before that check: chat
   channels and Web Push don't send a reviewer's turn results, and lead tools
   see only its status.
5. The review instructions include the PR title, description and earlier
   review comments, marked as untrusted, so findings already answered aren't
   repeated.
6. When the reviewer's turn completes, the control plane decides the
   **verdict**: **PASS** when there is no P0 or P1 finding, **FAIL** otherwise
   (or when a Claude reviewer's own verdict line says FAIL). It posts the
   verdict, the reviewer and its findings (P0–P3, file:line, scenario) as **one
   PR comment** headed "Independent review: PASS · round N" and starting with
   `<!-- ccr-review sha=<head> -->`, with `@` mentions neutralised. It records
   the verdict on the author task's PR, for that head (see [Reviewer verdict on
   every Worker PR](#reviewer-verdict-on-every-worker-pr)). It counts
   rounds from its own earlier markers. A failed or interrupted turn posts
   nothing and leaves the commit unreviewed, so it can be asked again.
   As a backstop (not the boundary), the server looks for credential-shaped
   text before posting: GitHub, OpenAI and Slack tokens, OAuth refresh tokens
   (`rt.…`), AWS keys, private keys, JWTs, any unbroken token-like run of 100+
   characters, the values in the Codex logins, the server's own tokens and keys,
   and the reviewer's runner token. It also checks the text with spaces
   removed, and decodes base64 runs of 40+ characters and checks those. If it finds any, it posts only a short
   "review withheld" notice (which doesn't mark the commit reviewed), sends the
   author nothing, marks the reviewer failed, and alerts the owner by push. The
   review text stays in the reviewer's log for the owner.
7. A FAIL queues one server-written repair brief for the author task at the
   reviewed head, regardless of Ask routing. The brief contains only validated
   file locations, server-written scenarios, counts and a comment link; raw
   reviewer text and prompts stay in the private reviewer task. It is sent
   after the live PR head is confirmed and before a potentially slow
   commit-status write, within the 10 messages per worker per hour cap. If
   capped, it stays queued and retries on later polls, even under Ask. Every
   actual repair send, including a designated Worker's recovered FAIL, uses
   one final GitHub head check after any earlier poll reads. If GitHub cannot
   confirm that head, the brief stays pending; manual Send cannot bypass the
   check. A newer PR head retires the old queued brief. A Manager can
   inspect the reviewer with `task_status` or `task_wait`: `handoff.state` is
   `queued`, `awaiting_author`, or `new_head`, with safe timestamps for verdict,
   delivery and the next head. A PASS with findings keeps normal PR routing;
   a clean PASS sends nothing. The posted comment is not routed again as new
   feedback.
8. The reviewer stops, and its checkout (and, for a local repository, its merge
   branch) is removed. Its record and log stay; it can't be resumed.

At most two reviewers run at once on a host (`CCR_CLOUD_MAX_REVIEWERS`, 1–16).
Beyond that, `review_pr` fails with a limit error; try again when one finishes.
A reviewer still running after 20 minutes (`CCR_CLOUD_REVIEW_TIMEOUT_MIN`) is
stopped and marked failed, freeing its slot. A lead can `task_wait` on the
returned `reviewerTaskId`. For a reviewer, `task_status` and `task_wait` return
only the review's status (`running`, `posted`, `failed` or `stopped`), the
reviewer's agent and `independence`, the `verdict` (`pass` or `fail`) and comment link once posted, and
the server's own error. They never return the
reviewer's text, which may hold what it read.

The author is asked to fix every confirmed P0 and P1 finding and any security
or data-loss finding. From round four on, it is asked to defer the remaining P2
and P3 findings to a follow-up issue. Reviewers need host mode, and Claude Code
or Codex.


### Efficient review and coordination

Before starting a paid review, inspect the current PR commit, repository policy and any configured GitHub reviewer. A Codex GitHub connector may start when a draft becomes ready. Give one reviewer ownership of that commit and track its status. Accept an external review only through the repository’s trusted reviewer policy and an explicit outcome tied to that commit. A bot acknowledgment, no findings, or findings without a verdict cannot release a review hold. Use a fallback for a failed or stalled external review only under the repository policy, with the reason recorded.

Keep each repair with its existing author Worker. Deliver all findings together and review the repair scope when appropriate. A PASS advances authorized work to the merge gate. Stop after three failed rounds to reassess scope. Use background jobs for checks, and report review time, dispatch wait, author wait and merge wait separately. Record available usage and cost as estimates, preserving unknown values.

Assign separable features to Workers with acceptance criteria, file ownership and the next actor. Keep small decisions and edits inline when delegation would cost as much as the work. Serialize overlapping review-pipeline changes. Every waiting item needs a reason, responsible actor and a scheduled wake or running job.
