cat-mode: many PR stacks run as one parallel unit per stack, never serially

[EdbertChan]

Summary

Sometimes there are several stacks of pull requests to land or repair at once. Our working mode decides where each stack runs.

The problem: when many stacks were waiting, the table that picks a place still answered "right here, in this thread". So chewing through them one at a time looked allowed.

The fix: more than one stack now means they all start at the same time. Invoker gets the work first.

When Invoker is missing, or you ask for helper agents, every stack gets its own helper in its own checkout of the repo.

One stack behaves exactly as before.

Review Claim

When more than one stack of pull requests is waiting, the table that picks a place hands the work to Invoker, or to one helper agent per stack. It no longer answers "stay in this thread".

Review Lane

behavior

Review Unit

corpus-lesson

Safety Invariant

With one unit (the default), every existing route is unchanged. Read-only work never enters the per-unit branch.

Slice Rationale

The table, its tests, and the three prose files that describe it change together, so the prose never describes a route the table cannot return.

Non-goals

• Changing invoker-route-delegation (Invoker-owned). It still decides first when installed.
• Auto-detecting the unit count. The caller passes units.

Test Plan

Test Plan

Repro then fix, same checkout, new tests held constant while only the routing
table was swapped back to its base version:

• fail before — base routing table + new tests:
  python3 -m unittest tests.test_execution_routing → Ran 25 tests in 0.673s / FAILED (errors=12)
• pass after — this branch:
  python3 -m unittest tests.test_execution_routing → Ran 25 tests in 0.822s / OK
• python3 engine/skills/make-pr/scripts/preflight.py --base origin/main --body-file <this body> → ok preflight passed, exit 0 (declares Review Unit corpus-lesson, 4 unit files + 1 neutral test file)
• node engine/skills/draft-pr/scripts/validate-pr-body.mjs --body-file <this body> --changed-files-file <changed files> → PR body validation passed., exit 0
• ruff check --select E9,F corpus/skills/cat-mode/scripts/route_execution.py tests/test_execution_routing.py → All checks passed!

Not fully run locally: bash scripts/test/run_all_tests.sh exceeded a 10 minute
local timeout. python3 -m unittest tests.test_cat_mode tests.test_execution_routing
has one failure in this sandbox — test_an_install_the_ssh_path_reaches_is_ok
reads the sandbox's own installed Invoker version (0.1.13) instead of none.
That failure reproduces unchanged on origin/main, so it is environmental and
not from this slice. CI's test job is the authority for the full sweep.

Revert Plan

Revert Plan

• Safe to revert? Yes
• Revert command: git revert <sha> (single commit)
• Post-revert steps: None. With units gone, callers fall back to the old routes.
• Data migration? No

🤖 Generated with Claude Code

---

Note

Low Risk
Behavioral routing guidance and a defaulted units=1 API in cat-mode skill scripts; no auth or production paths, with regression tests covering the new branches.

Overview
Multiple independent PR stacks or publishing workflows must no longer be routed to serial work in the parent chat. Cat-mode docs and route_execution.py now treat units > 1 as a first-class case: prefer Invoker (one workflow per unit), otherwise subagent_worktree_per_unit with parallel worktree-isolated subagents; user-directed subagents can force the per-unit path even when Invoker is available.

route_execution / route_delegation gain optional units and user_directed_subagents; the CLI JSON payload accepts the same. A new handoff route and steps (one_worktree_per_unit, parallel spawn, transcript greps) document the fallback. Single-unit and read-only behavior stay unchanged (units=1 default).

Tests lock in that many publishing units never return local and that delegation for PR-producing work reaches the per-unit route when Invoker is absent.

^{Reviewed by Cursor Bugbot for commit 8ae48c3. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_2c635fec-a324-40c0-b5c4-30f32beb5a9d)

[mergify]

Queued — the merge queue status continues in this comment ↓.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_d209b757-8e0f-40c5-b185-071df8b88b85)

[EdbertChan]

@Mergifyio queue

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-09-24 03:57 UTC · Rule: admin-bypass · triggered by @EdbertChan with the @mergifyio queue command
• ✅ Checks passed · on draft merge queue: checking #890 on main (5b4a082), stacked on #818, #822 and #875 #903
• ✅ Merged — 2026-09-24 04:26 UTC · at 675956d76b899e7e9d02f9a235bba96f10ce4207 · squash

This pull request spent 28 minutes 38 seconds in the queue, including 27 minutes 56 seconds running CI.

Required conditions to merge

• check-success = lint
• check-success = test
• check-success = validate