brindle 0.1.0__tar.gz → 0.2.1__tar.gz

{brindle-0.1.0 → brindle-0.2.1}/.gitignore

@@ -9,3 +9,4 @@ graphify-out/
 # private, kept local for now
 docs/
 .brindle/config.local.json
+.brindle/bench.json

{brindle-0.1.0 → brindle-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brindle
-Version: 0.1.0
+Version: 0.2.1
 Summary: Run coding agents in parallel, each on its own git branch, with a supervisor that delegates, reviews, and merges
 Project-URL: Homepage, https://pawdelta.com/brindle/
 Project-URL: Documentation, https://pawdelta.com/brindle/docs/recommended-use
@@ -89,7 +89,7 @@ uv tool install --editable ~/Projects/brindle   # or from a local checkout
 brindle drives Claude Code, so you need that too (`npm install -g @anthropic-ai/claude-code`).
 
 `brindle --version` prints the installed version; the tmux status bar of every brindle
-session shows it too (`brindle 0.1.0`). A session started before an upgrade keeps
+session shows it too (`brindle 0.2.1`). A session started before an upgrade keeps
 running the old code, and shows the old number, until you restart it.
 
 ## Quick start
@@ -360,6 +360,7 @@ your own status line prints, so what you see doesn't change.
 | `brindle cost requests` | Enterprise: your approval requests and their status; checks pending ones with the server (the cull pass also does, every few minutes). With cost centers, spend events also carry the repo (`owner/name`) so the org can total spend per center |
 | `brindle cost estimate [--tasks N] [--weight W] [--profile P] [--reviewer R]` | what the current goal (or N tasks) is likely to cost, as a range from this repo's history (median to p80 of past worker and review runs), plus a cheaper alternative with a different reviewer; says "low confidence" when there's too little history. Also added to `set_goal` and `assign` replies (brindle Pro) |
 | `brindle learning` | whether brindle Pro's hosted learning is on for this repo, and if not, why (nothing is learned on your machine) |
+| `brindle learning seed` | Pro: sends this repo's finished routing history to the hosted learner once, so it starts with what this machine has seen. Only the usual coarse record fields leave (kind/size one-hots, counters, HMAC keys), never task text or paths. A second run sends nothing new; decisions already sent live are skipped |
 | `brindle account [login\|logout\|status\|upgrade\|portal\|org]` | paid features: bare `brindle account` shows what your plan has and how to get the rest (see "brindle Pro and Team" below) |
 | `brindle audit verify\|export\|pubkey\|ship\|prune` | the local tamper-evident audit log, and shipping it to your SIEM (brindle Enterprise; see "Audit log" below) |
 | `brindle watch [--all] [--once]` | the dashboard on its own (the same view as the sidebar): enter attaches, `p` peeks, `x` closes |
@@ -389,12 +390,13 @@ knowing them helps when you tell the supervisor how to work.
 
 | Tool | Used by | |
 |---|---|---|
-| `assign` / `handoff` / `wait_for_worker` | supervisor | start a worker (return now / wait for its result / keep waiting) |
+| `assign` / `handoff` / `wait_for_worker` | supervisor | start a worker (return now / wait for its result / keep waiting); `dry_run=true` on `assign`/`handoff` starts nothing and reports the profile, what each `files` glob matches, overlaps and whether it would queue |
 | `send_message` | any agent | message another agent; delivered when it's idle |
 | `read_messages` | supervisor | read the messages agents and brindle sent you and mark them read; with `message_delivery` `"pull"` (the default) you get a one-line "N new messages" notice instead of each message |
-| `list_agents` / `list_tasks` / `list_agent_profiles` | supervisor | who's running, what's queued, which profiles exist |
+| `list_agents` / `list_tasks` / `list_agent_profiles` | supervisor | who's running, what's queued, which profiles exist; `list_tasks(full=true)` also shows each task's brief and `done_when` |
 | `list_repos` | supervisor | the repos attached to the session (brindle Pro); `repo=<alias>` on `assign`/`handoff` puts a worker there |
 | `cancel_task` | supervisor | cancel a queued task (and its dependents) to re-plan |
+| `requeue` | supervisor | queue a cancelled task again with the same brief, files and profile; `depends_on` replaces its dependencies |
 | `workspace_diff` | supervisor | a worker branch's changes against its base |
 | `request_review` / `submit_review` | supervisor / reviewer | start a reviewer on a branch / record its verdict |
 | `merge_workspace` / `remove_workspace` | supervisor | merge through the gates / delete the worktree |
@@ -437,8 +439,10 @@ count as unknown.
 `brindle cost` prices the last 30 days of history at each model's list price
 (per million tokens: input, output, cache write, cache read), copied from
 Anthropic's and OpenAI's pricing pages and dated; brindle warns when they're
-more than 90 days old. Local models cost $0. A model brindle has no price
-for is shown as unpriced tokens, never guessed. Add or correct prices under
+more than 90 days old. Local models cost $0, and usage on a model known to be
+free reads "Free" (its tokens still count; a mix reads "$1.20 (+40k tokens
+free)"). A model brindle has no price for is shown as unpriced tokens, never
+guessed. Add or correct prices under
 `pricing` in `~/.brindle/config.json` or `.brindle/config.json`:
 
 ```json
@@ -538,7 +542,7 @@ Autopilot, merge gates and cleanup:
 | `protected_paths` | `[]` | paths or globs (`"migrations/"`, `"*.lock"`) whose merge conflicts brindle never hands to a worker to resolve: the branch waits for you instead (see "Conflict-aware merging") |
 | `pool_size` | `1` if `setup` is set, else `0` | pre-built worktrees (checked out, files copied, setup run) kept ready so a new worker doesn't wait on `setup`; `0` disables it |
 | `add_dirs` | `[]` | directories outside the worktree that Claude Code agents may use (`--add-dir`; full tool access, see "Directories outside the workspace") |
-| `local_models` | `false` | `true`: when a native profile points at Ollama on this machine and it isn't running, `brindle` starts `ollama serve` in the background (with the context length the profiles need) and loads their models. Off, brindle uses a server that's already running and never starts or preloads one |
+| `local_models` | `true` | When a native profile points at Ollama on this machine and it isn't running, `brindle` starts `ollama serve` in the background (with the context length the profiles need) and loads their models, then stops it when the last session closes. `false`: brindle uses a server that's already running and never starts or preloads one |
 | `sidebar` | `"left"` | where the dashboard sits in each window: `"left"` of the chat, or `"bottom"` (full-width rows under it) |
 | `delegation` | `"balanced"` | how readily the supervisor hands work to workers. `"conservative"` does most work in its own chat (fewest tokens), `"fast"` splits any multi-part request across parallel workers straight away (quickest, most tokens). `brindle delegation fast` saves it for every repo and session (in `~/.brindle/config.json`; `--repo` for this repo only) and tells a running supervisor |
 | `delete_merged_branches` | `true` | removing a worktree (after a merge, `brindle rm`, `brindle prune`, session cleanup) also deletes its branch once every commit is in its base, so finished branches don't pile up. An unmerged branch is always kept; `false` keeps them all. If GitHub keeps merged PR branches, the first `brindle pr` in a repo offers to turn on its automatic deletion with your `gh` login (repo admins only) |
@@ -742,10 +746,11 @@ how to use them, and the next step to get the rest:
 | Brindle-CI (fixes builds, issues into verified pull requests, validation) | Team | `brindle ci init` |
 | org profile and rule-pack library, pinned so a repo can't loosen it | Team | `brindle account org profiles` |
 | org budgets and protected paths | Team | `budget`, `protected_paths` in your org policy (`brindle account org policy`) |
+| per-member budgets, pause, and admin messages (sidebar "Messages", the bottom bar, `brindle org messages`) | Team | `brindle org messages [--keep]` lists and marks read the notices your admins sent you; a pause refuses new workers and stops running ones |
 | audit log, air-gap | Enterprise | `brindle audit verify`, `"airgap": true` |
 | audit export | Enterprise | `"audit_export"` in `~/.brindle/config.json`, `brindle audit ship` |
 | managed models | Enterprise | `provider_config`, `deny_personal_keys` in your org policy (see "Managed models" below) |
-| wider CI, cost centers, managed rollout | Enterprise | `brindle ci init --host gitlab`, `brindle cost request`, and `min_version`, required packs and the kill switch in your org policy |
+| wider CI, cost centers, managed rollout | Enterprise | `brindle ci init --host gitlab`, `brindle cost request`, and `min_version`, required packs and the kill switch in your org policy; admins can also shut down or throttle a member, role or org remotely (it arrives within about a minute) |
 
 `brindle ci init` checks your plan before it changes anything: it refuses
 without Brindle-CI on the org you're using, and on Pro it sets up only the fix
@@ -1548,9 +1553,9 @@ ollama pull qwen3-coder:30b
 brindle doctor                   # "model qwen3-coder:30b ... is available"
 ```
 
-Run `ollama serve` yourself, or let brindle do it: a 30B model holds about 20 GB
-of GPU memory, so brindle doesn't start or preload one unless you set
-`"local_models": true`. Then, when `brindle` (or `brindle continue`)
+Run `ollama serve` yourself, or let brindle do it, with no setup. A 30B model holds
+about 20 GB of GPU memory, so set `"local_models": false` if you don't want brindle
+to start or preload one. When `brindle` (or `brindle continue`)
 starts and a native profile points at Ollama on this machine that isn't answering,
 brindle starts it in the background with `OLLAMA_CONTEXT_LENGTH` set to the largest
 `context_tokens` any profile asks of it plus room for the reply (40960 for the

{brindle-0.1.0 → brindle-0.2.1}/README.md

@@ -59,7 +59,7 @@ uv tool install --editable ~/Projects/brindle   # or from a local checkout
 brindle drives Claude Code, so you need that too (`npm install -g @anthropic-ai/claude-code`).
 
 `brindle --version` prints the installed version; the tmux status bar of every brindle
-session shows it too (`brindle 0.1.0`). A session started before an upgrade keeps
+session shows it too (`brindle 0.2.1`). A session started before an upgrade keeps
 running the old code, and shows the old number, until you restart it.
 
 ## Quick start
@@ -330,6 +330,7 @@ your own status line prints, so what you see doesn't change.
 | `brindle cost requests` | Enterprise: your approval requests and their status; checks pending ones with the server (the cull pass also does, every few minutes). With cost centers, spend events also carry the repo (`owner/name`) so the org can total spend per center |
 | `brindle cost estimate [--tasks N] [--weight W] [--profile P] [--reviewer R]` | what the current goal (or N tasks) is likely to cost, as a range from this repo's history (median to p80 of past worker and review runs), plus a cheaper alternative with a different reviewer; says "low confidence" when there's too little history. Also added to `set_goal` and `assign` replies (brindle Pro) |
 | `brindle learning` | whether brindle Pro's hosted learning is on for this repo, and if not, why (nothing is learned on your machine) |
+| `brindle learning seed` | Pro: sends this repo's finished routing history to the hosted learner once, so it starts with what this machine has seen. Only the usual coarse record fields leave (kind/size one-hots, counters, HMAC keys), never task text or paths. A second run sends nothing new; decisions already sent live are skipped |
 | `brindle account [login\|logout\|status\|upgrade\|portal\|org]` | paid features: bare `brindle account` shows what your plan has and how to get the rest (see "brindle Pro and Team" below) |
 | `brindle audit verify\|export\|pubkey\|ship\|prune` | the local tamper-evident audit log, and shipping it to your SIEM (brindle Enterprise; see "Audit log" below) |
 | `brindle watch [--all] [--once]` | the dashboard on its own (the same view as the sidebar): enter attaches, `p` peeks, `x` closes |
@@ -359,12 +360,13 @@ knowing them helps when you tell the supervisor how to work.
 
 | Tool | Used by | |
 |---|---|---|
-| `assign` / `handoff` / `wait_for_worker` | supervisor | start a worker (return now / wait for its result / keep waiting) |
+| `assign` / `handoff` / `wait_for_worker` | supervisor | start a worker (return now / wait for its result / keep waiting); `dry_run=true` on `assign`/`handoff` starts nothing and reports the profile, what each `files` glob matches, overlaps and whether it would queue |
 | `send_message` | any agent | message another agent; delivered when it's idle |
 | `read_messages` | supervisor | read the messages agents and brindle sent you and mark them read; with `message_delivery` `"pull"` (the default) you get a one-line "N new messages" notice instead of each message |
-| `list_agents` / `list_tasks` / `list_agent_profiles` | supervisor | who's running, what's queued, which profiles exist |
+| `list_agents` / `list_tasks` / `list_agent_profiles` | supervisor | who's running, what's queued, which profiles exist; `list_tasks(full=true)` also shows each task's brief and `done_when` |
 | `list_repos` | supervisor | the repos attached to the session (brindle Pro); `repo=<alias>` on `assign`/`handoff` puts a worker there |
 | `cancel_task` | supervisor | cancel a queued task (and its dependents) to re-plan |
+| `requeue` | supervisor | queue a cancelled task again with the same brief, files and profile; `depends_on` replaces its dependencies |
 | `workspace_diff` | supervisor | a worker branch's changes against its base |
 | `request_review` / `submit_review` | supervisor / reviewer | start a reviewer on a branch / record its verdict |
 | `merge_workspace` / `remove_workspace` | supervisor | merge through the gates / delete the worktree |
@@ -407,8 +409,10 @@ count as unknown.
 `brindle cost` prices the last 30 days of history at each model's list price
 (per million tokens: input, output, cache write, cache read), copied from
 Anthropic's and OpenAI's pricing pages and dated; brindle warns when they're
-more than 90 days old. Local models cost $0. A model brindle has no price
-for is shown as unpriced tokens, never guessed. Add or correct prices under
+more than 90 days old. Local models cost $0, and usage on a model known to be
+free reads "Free" (its tokens still count; a mix reads "$1.20 (+40k tokens
+free)"). A model brindle has no price for is shown as unpriced tokens, never
+guessed. Add or correct prices under
 `pricing` in `~/.brindle/config.json` or `.brindle/config.json`:
 
 ```json
@@ -508,7 +512,7 @@ Autopilot, merge gates and cleanup:
 | `protected_paths` | `[]` | paths or globs (`"migrations/"`, `"*.lock"`) whose merge conflicts brindle never hands to a worker to resolve: the branch waits for you instead (see "Conflict-aware merging") |
 | `pool_size` | `1` if `setup` is set, else `0` | pre-built worktrees (checked out, files copied, setup run) kept ready so a new worker doesn't wait on `setup`; `0` disables it |
 | `add_dirs` | `[]` | directories outside the worktree that Claude Code agents may use (`--add-dir`; full tool access, see "Directories outside the workspace") |
-| `local_models` | `false` | `true`: when a native profile points at Ollama on this machine and it isn't running, `brindle` starts `ollama serve` in the background (with the context length the profiles need) and loads their models. Off, brindle uses a server that's already running and never starts or preloads one |
+| `local_models` | `true` | When a native profile points at Ollama on this machine and it isn't running, `brindle` starts `ollama serve` in the background (with the context length the profiles need) and loads their models, then stops it when the last session closes. `false`: brindle uses a server that's already running and never starts or preloads one |
 | `sidebar` | `"left"` | where the dashboard sits in each window: `"left"` of the chat, or `"bottom"` (full-width rows under it) |
 | `delegation` | `"balanced"` | how readily the supervisor hands work to workers. `"conservative"` does most work in its own chat (fewest tokens), `"fast"` splits any multi-part request across parallel workers straight away (quickest, most tokens). `brindle delegation fast` saves it for every repo and session (in `~/.brindle/config.json`; `--repo` for this repo only) and tells a running supervisor |
 | `delete_merged_branches` | `true` | removing a worktree (after a merge, `brindle rm`, `brindle prune`, session cleanup) also deletes its branch once every commit is in its base, so finished branches don't pile up. An unmerged branch is always kept; `false` keeps them all. If GitHub keeps merged PR branches, the first `brindle pr` in a repo offers to turn on its automatic deletion with your `gh` login (repo admins only) |
@@ -712,10 +716,11 @@ how to use them, and the next step to get the rest:
 | Brindle-CI (fixes builds, issues into verified pull requests, validation) | Team | `brindle ci init` |
 | org profile and rule-pack library, pinned so a repo can't loosen it | Team | `brindle account org profiles` |
 | org budgets and protected paths | Team | `budget`, `protected_paths` in your org policy (`brindle account org policy`) |
+| per-member budgets, pause, and admin messages (sidebar "Messages", the bottom bar, `brindle org messages`) | Team | `brindle org messages [--keep]` lists and marks read the notices your admins sent you; a pause refuses new workers and stops running ones |
 | audit log, air-gap | Enterprise | `brindle audit verify`, `"airgap": true` |
 | audit export | Enterprise | `"audit_export"` in `~/.brindle/config.json`, `brindle audit ship` |
 | managed models | Enterprise | `provider_config`, `deny_personal_keys` in your org policy (see "Managed models" below) |
-| wider CI, cost centers, managed rollout | Enterprise | `brindle ci init --host gitlab`, `brindle cost request`, and `min_version`, required packs and the kill switch in your org policy |
+| wider CI, cost centers, managed rollout | Enterprise | `brindle ci init --host gitlab`, `brindle cost request`, and `min_version`, required packs and the kill switch in your org policy; admins can also shut down or throttle a member, role or org remotely (it arrives within about a minute) |
 
 `brindle ci init` checks your plan before it changes anything: it refuses
 without Brindle-CI on the org you're using, and on Pro it sets up only the fix
@@ -1518,9 +1523,9 @@ ollama pull qwen3-coder:30b
 brindle doctor                   # "model qwen3-coder:30b ... is available"
 ```
 
-Run `ollama serve` yourself, or let brindle do it: a 30B model holds about 20 GB
-of GPU memory, so brindle doesn't start or preload one unless you set
-`"local_models": true`. Then, when `brindle` (or `brindle continue`)
+Run `ollama serve` yourself, or let brindle do it, with no setup. A 30B model holds
+about 20 GB of GPU memory, so set `"local_models": false` if you don't want brindle
+to start or preload one. When `brindle` (or `brindle continue`)
 starts and a native profile points at Ollama on this machine that isn't answering,
 brindle starts it in the background with `OLLAMA_CONTEXT_LENGTH` set to the largest
 `context_tokens` any profile asks of it plus room for the reply (40960 for the

{brindle-0.1.0 → brindle-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brindle"
-version = "0.1.0"
+version = "0.2.1"
 description = "Run coding agents in parallel, each on its own git branch, with a supervisor that delegates, reviews, and merges"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -49,7 +49,10 @@ audit = "brindle.pro.audit_chain:make"
 audit_export = "brindle.pro.audit_export:make"
 
 [dependency-groups]
-dev = ["pytest>=8"]
+dev = [
+    "pytest>=8",
+    "pytest-xdist>=3.8.0",
+]
 
 [build-system]
 requires = ["hatchling>=1.27"]
@@ -69,3 +72,4 @@ only-include = ["src", "README.md", "LICENSE", "SCHEDULE-A", "pyproject.toml"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["tests"]
+markers = ["serial: run outside xdist (`pytest -m serial`); the parallel pass skips these"]

{brindle-0.1.0 → brindle-0.2.1}/src/brindle/agents.py

@@ -47,6 +47,12 @@ WORKER_FOOTER = """
 ---
 You are running as a brindle worker (agent id {agent_id}) on branch `{branch}`.
 {guidance}
+Before you finish, check your work against the task and its finish line, item
+by item: each behaviour it asks for needs a test that would fail without your
+change, and a requirement with no such test isn't done yet. If the task turns
+out too big for one branch, finish a coherent part and say exactly what's left
+(and how you'd split it) rather than leaving every part half done.
+
 When you have finished:
 1. Commit your work to this branch with a clear message (do not push or merge).
 2. Call the `report_result` tool from the `brindle` MCP server with a concise
@@ -72,6 +78,12 @@ Your shell may start in another directory, so begin every Bash command with
 `cd {path} && ` (or use `git -C {path}`), and give file tools absolute paths
 under that directory. Don't change files anywhere else, and don't switch branches.
 {guidance}
+Before you finish, check your work against the task and its finish line, item
+by item: each behaviour it asks for needs a test that would fail without your
+change, and a requirement with no such test isn't done yet. If the task turns
+out too big for one branch, finish a coherent part and say exactly what's left
+(and how you'd split it) rather than leaving every part half done.
+
 When you have finished:
 1. Commit your work there on `{branch}` with a clear message (do not push or merge).
 2. Don't call any brindle tools. End with a concise summary: what you changed,
@@ -1358,11 +1370,16 @@ def report_result(db: DB, agent_id: str, result: str, forward: bool = True,
             agent=agent, usage=u, branch=ws.branch, task=agent.task, result=result,
         )
     if u and u.total:
+        free = False
         try:
-            dollars = usage_mod.usage_cost(u, pricing.repo_overrides(ws.repo_root if ws else None))
+            root = ws.repo_root if ws else None
+            extra = pricing.repo_overrides(root)
+            price = pricing.price_for(u.model, extra) or pricing.profile_price(agent.profile, root, extra)
+            dollars = usage_mod.usage_cost(u, extra, fallback=price)
+            free = price == pricing.FREE
         except Exception:  # noqa: BLE001 - a price is an extra too
             dollars = None
-        forwarded = f"{result}\n\n{usage_mod.summary_line(u, dollars)}"
+        forwarded = f"{result}\n\n{usage_mod.summary_line(u, dollars, free)}"
     else:
         forwarded = result
     if ws and agent.mode in ("handoff", "handoff_detached", "assign"):
@@ -1609,6 +1626,7 @@ def delegate(
         start = base if git.branch_exists(caller_ws.repo_root, base) else "HEAD"
         created = workspaces.create(
             db, caller_ws.path, branch, base, fetch=False, start=start,
+            reuse_registered=True,
         )
         if created.setup and not created.setup.ok:
             raise AgentError(f"workspace setup failed:\n{created.setup.log}")
@@ -1691,38 +1709,19 @@ def _local_reviewer_available() -> bool:
     return bool(ok) and "is available" in detail
 
 
-def request_review(db: DB, caller: Agent | None, ws: Workspace, profile: str | None = None,
-                   focus: str | None = None, cfg: RepoConfig | None = None) -> Agent:
-    """Start a reviewer in a worker's workspace right away. Its verdict is
-    recorded for the merge gate and forwarded to ``caller`` as a message.
-    ``profile`` picks the reviewer profile; None uses
-    ``default_review_profile``.
-
-    Raises ``AgentError`` if the chosen profile (explicit or picked) doesn't
-    exist, or if it uses the codex provider but codex isn't on PATH -- rather
-    than spawning a reviewer doomed to fail in a dead pane.
-
-    ``cfg.checks`` are NOT run here (that would block the caller on the full
-    suite): the caller runs them in the background and delivers a pass/fail
-    summary to the reviewer as a message once they finish, via
-    ``deliver_check_summary``. If the workspace already has a review at an
-    earlier commit, the reviewer is pointed at just what changed since then,
-    when that's a plain diff (see ``is_linear_since``)."""
-    from brindle import gates
-    from brindle.config import load_repo_config
+def _review_kill_switch(ws: Workspace) -> None:
     from brindle.pro import rollout
 
     why_not = rollout.kill_switch_reason(ws.repo_root)   # Enterprise managed rollout
     if why_not:
         raise AgentError(f"No reviewer started: {why_not}")
-    cfg = cfg or load_repo_config(ws.repo_root)
-    sha = gates.head(ws)
-    for old in db.list_agents(ws.id):
-        if old.mode != "review" or old.result is not None or not is_alive(old):
-            continue
-        if old.review_sha == sha:
-            return old   # one reviewer per workspace and commit
-        close(db, old.id)   # a new commit replaces the reviewer of the old one
+
+
+def _review_profile(db: DB, ws: Workspace, profile: str | None, cfg: RepoConfig) -> str:
+    """The reviewer profile to use, checked to be one that can run: raises
+    ``AgentError`` if it (explicit or picked) doesn't exist, or uses the codex
+    provider but codex isn't on PATH -- rather than spawning a reviewer doomed
+    to fail in a dead pane."""
     worker = workspace_worker(db, ws)
     profile = profile or default_review_profile(cfg, worker, db, ws.repo_root,
                                                 worker.task if worker else None)
@@ -1737,6 +1736,125 @@ def request_review(db: DB, caller: Agent | None, ws: Workspace, profile: str | N
             f"reviewer profile {profile!r} can't run: {why}. "
             "Fix that, or set review_profile (or pass profile) to a different reviewer"
         )
+    return profile
+
+
+def _live_reviewer(db: DB, ws: Workspace, sha: str, profile: str | None = None) -> Agent | None:
+    """The reviewer still at work on ``ws`` at ``sha``, if any. With
+    ``profile``, only one running that profile (a second review by another
+    profile is not a duplicate)."""
+    for a in db.list_agents(ws.id):
+        if a.mode == "review" and a.result is None and is_alive(a) and a.review_sha == sha \
+                and (profile is None or a.profile == profile):
+            return a
+    return None
+
+
+def start_review(db: DB, caller: Agent | None, ws: Workspace, profile: str | None = None,
+                 focus: str | None = None, cfg: RepoConfig | None = None) -> Agent | None:
+    """Have ``ws`` reviewed. Without checks configured the reviewer starts
+    right away and is returned. With checks, nothing starts yet: a detached
+    ``_review-after-checks`` process runs them and starts the reviewer with
+    their results in its prompt (see ``review_after_checks``), so this returns
+    at once with None, however long the suite takes. Raises ``AgentError``
+    for a reviewer that couldn't start whatever the checks say (the kill
+    switch, an unusable profile); a failure after that reaches ``caller``
+    as a message."""
+    from brindle import gates
+    from brindle.config import load_repo_config
+    from brindle.providers import brindle_invocation
+
+    cfg = cfg or load_repo_config(ws.repo_root)
+    if not cfg.checks:
+        return request_review(db, caller, ws, profile, focus, cfg)
+    _review_kill_switch(ws)
+    _review_profile(db, ws, profile, cfg)
+    existing = _live_reviewer(db, ws, gates.head(ws), profile)
+    if existing:
+        return existing   # one reviewer per workspace and commit
+    argv = [*brindle_invocation(), "_review-after-checks", ws.id]
+    if caller:
+        argv += ["--caller", caller.id]
+    if profile:
+        argv += ["--profile", profile]
+    if focus:
+        argv += ["--focus", focus]
+    _detach(argv)
+    return None
+
+
+def expected_check_wait(db: DB, ws: Workspace, cfg: RepoConfig) -> float | None:
+    """Seconds the repo's checks usually take (the sum of each one's last
+    passing duration), or None when any of them has never passed."""
+    total = 0.0
+    for cmd in cfg.checks:
+        took = db.check_duration(ws.repo_root, cmd)
+        if took is None:
+            return None
+        total += took
+    return total if cfg.checks else None
+
+
+def review_after_checks(db: DB, caller_id: str | None, ws: Workspace, profile: str | None = None,
+                        focus: str | None = None, cfg: RepoConfig | None = None) -> Agent | None:
+    """Run ``cfg.checks`` for ``ws`` (through ``gates.check_summary``: its
+    lock and the by-sha cache, so a result a worker's report already warmed
+    is instant), then start the reviewer with the results in its prompt.
+    Meant to run from a detached process, which outlives the call that
+    started it. Gives up quietly when the branch moves on (the new commit
+    gets its own review), the workspace is gone, or a reviewer is already at
+    work on this commit. Raises ``AgentError`` when the reviewer can't
+    start."""
+    from brindle import gates
+    from brindle.config import load_repo_config
+
+    cfg = cfg or load_repo_config(ws.repo_root)
+    sha = gates.head(ws)
+    if _live_reviewer(db, ws, sha, profile):
+        return None
+    try:
+        summary = gates.check_summary(db, ws, cfg, cancel=lambda: gates.head(ws) != sha)
+    except gates.Abandoned:
+        return None
+    except Exception as e:  # noqa: BLE001 - the review goes ahead, saying so
+        summary = f"(running the checks crashed: {e})"
+    if db.get_workspace(ws.id) is None or gates.head(ws) != sha:
+        return None
+    caller = db.get_agent(caller_id) if caller_id else None
+    text = f"Checks for {ws.branch} at {sha[:8]}:\n\n{summary}" if summary else None
+    return request_review(db, caller, ws, profile, focus, cfg, check_summary=text)
+
+
+def request_review(db: DB, caller: Agent | None, ws: Workspace, profile: str | None = None,
+                   focus: str | None = None, cfg: RepoConfig | None = None,
+                   check_summary: str | None = None) -> Agent:
+    """Start a reviewer in a worker's workspace right away. Its verdict is
+    recorded for the merge gate and forwarded to ``caller`` as a message.
+    ``profile`` picks the reviewer profile; None uses
+    ``default_review_profile`` (``AgentError`` if it can't run).
+
+    ``cfg.checks`` are NOT run here (that would block the caller on the full
+    suite): ``start_review`` runs them first, in the background, and passes
+    their results as ``check_summary`` for the reviewer's prompt. If the
+    workspace already has a review at an earlier commit, the reviewer is
+    pointed at just what changed since then, when that's a plain diff (see
+    ``is_linear_since``)."""
+    from brindle import gates
+    from brindle.config import load_repo_config
+
+    _review_kill_switch(ws)
+    cfg = cfg or load_repo_config(ws.repo_root)
+    sha = gates.head(ws)
+    for old in db.list_agents(ws.id):
+        if old.mode != "review" or old.result is not None or not is_alive(old):
+            continue
+        if old.review_sha == sha:
+            if profile and old.profile != profile:
+                continue   # another profile's review of this commit (a second review): keep both
+            return old   # one reviewer per workspace and commit
+        close(db, old.id)   # a new commit replaces the reviewer of the old one
+    worker = workspace_worker(db, ws)
+    profile = _review_profile(db, ws, profile, cfg)
 
     base = ws.base_branch or "the base branch"
     task = (f"Review the changes on branch `{ws.branch}` (workspace {ws.id}) against `{base}`: "
@@ -1749,16 +1867,9 @@ def request_review(db: DB, caller: Agent | None, ws: Workspace, profile: str | N
     if worker and worker.done_when:
         task += f"\n\nIts finish line: {worker.done_when.strip()}"
 
-    if cfg and cfg.checks:
-        task += ("\n\nThe repo's checks are still running (or queued behind other branches' "
-                 "runs): you don't have their results yet. A pass/fail summary will arrive as a "
-                 "message. Review the diff meanwhile, and don't call submit_review until you've "
-                 "received it. If about 10 minutes pass after you've finished reviewing with no "
-                 "such message, submit anyway and say plainly in your summary that the checks "
-                 "were still running when you submitted, so your verdict rests on the diff "
-                 "alone: the merge gate runs them before anything merges, and a failure that "
-                 "arrives after your verdict goes to the supervisor. Don't run the whole suite "
-                 "yourself to compensate.")
+    if check_summary:
+        task += (f"\n\nThe repo's checks have already run on this commit:\n\n{check_summary}\n\n"
+                 "Take these results into account; don't run the whole suite yourself.")
 
     prev = db.last_review(ws.id)
     if prev and prev.sha != sha:
@@ -1778,87 +1889,6 @@ def request_review(db: DB, caller: Agent | None, ws: Workspace, profile: str | N
                  mode="review", background_setup=True, review_sha=sha)
 
 
-def deliver_check_summary(db: DB, reviewer_id: str, ws: Workspace, cfg: RepoConfig) -> None:
-    """Run ``cfg.checks`` for ``ws`` and deliver a pass/fail summary to the
-    reviewer's inbox: delivered right away if it's idle, or handed over at its
-    next Stop, exactly like any other queued message (see ``send_message``).
-    Meant to run from a detached process started by request_review, so it
-    outlives the MCP server call that kicked it off. Always delivers
-    something, even if a check crashes, since the reviewer was told to wait
-    for this before approving. If the reviewer is no longer there to receive
-    it by the time the checks finish, a failing summary isn't dropped: see
-    ``_late_check_summary``."""
-    from brindle import gates
-
-    reviewer = db.get_agent(reviewer_id)
-    if reviewer is None:
-        return
-    supervisor_id = reviewer.parent_id
-    sha = gates.head(ws)  # label with the commit the checks ran on
-    try:
-        summary = gates.check_summary(db, ws, cfg)
-        failed = gates.summary_failed(summary)
-    except Exception as e:
-        summary, failed = f"(running the checks crashed: {e})", True
-
-    reviewer = db.get_agent(reviewer_id)
-    if reviewer is None or reviewer.result is not None or reviewer.status == "done":
-        # It submitted its review, was closed, or was removed while the checks ran.
-        if failed:
-            _late_check_summary(db, ws, sha, summary, reviewer_id, supervisor_id)
-        return
-
-    text = (f"Checks for {ws.branch} at {sha[:8]}:\n\n{summary}" if summary
-            else "No checks are configured for this repo.")
-    db.enqueue(reviewer_id, text, None)
-    flush(db, reviewer_id)
-
-
-def _late_check_summary(db: DB, ws: Workspace, sha: str, summary: str, reviewer_id: str,
-                        supervisor_id: str | None) -> None:
-    """The checks for ``ws`` at ``sha`` finished after its reviewer was done,
-    and failed (or crashed), so the verdict was given without them (a late
-    pass changes nothing). The failure must reach someone who can act on it:
-    the supervisor when the branch was approved (or has no verdict at this
-    commit), the worker when changes were requested anyway (the supervisor
-    if it's gone). Dropped
-    only when there's nothing left to act on: the workspace was removed, the
-    branch merged at this commit (its worktree may be going away under the
-    run), or the branch has new commits, which get their own run."""
-    from brindle import gates
-
-    try:
-        if db.get_workspace(ws.id) is None or db.merged_sha(ws.id) == sha or gates.head(ws) != sha:
-            return
-    except git.GitError:
-        return
-    worker = workspace_worker(db, ws)
-    supervisor_id = supervisor_id or (worker.parent_id if worker else None)
-    review = db.latest_review(ws.id, sha)
-    checks = f"Checks for {ws.branch} at {sha[:8]}:\n\n{summary}"
-    if review is not None and not review.approved and worker and is_alive(worker):
-        try:
-            send_message(db, worker.id,
-                         "The repo's checks finished after the review of your branch, and "
-                         f"failed. Fix this along with the review's findings.\n\n{checks}")
-            return
-        except (AgentError, tmux.TmuxError):
-            pass   # the supervisor hears instead
-    if supervisor_id is None or db.get_agent(supervisor_id) is None:
-        return
-    if review is not None and review.approved:
-        lead = (f"[brindle] The checks on `{ws.branch}` (workspace {ws.id}) FAILED, and the result "
-                f"arrived after reviewer {reviewer_id} had approved it: the approval rests on "
-                "the diff alone. The merge gate runs the checks again, so the branch won't "
-                "merge while they fail. Send this to the worker to fix, then have it reviewed "
-                "again.")
-    else:
-        lead = (f"[brindle] The checks on `{ws.branch}` (workspace {ws.id}) FAILED, and the result "
-                f"arrived after reviewer {reviewer_id} had finished, so the review didn't "
-                "take it into account. Send this to the worker to fix.")
-    gates.tell(db, supervisor_id, f"{lead}\n\n{checks}")
-
-
 # -- hook entry point --------------------------------------------------------