Default PR-batch to one canonical issue or PR per user-visible task

[justin808]

Recommendation

Product decision now; if accepted, run a P2 measured pilot after #398 provides replay-safe receipts. Make one canonical issue or existing PR per user-visible Codex task the ordinary implementation mode. Keep multi-target supervision as an explicit exception, not the default shape of a batch.

Evidence

Evidence source: maintainer-observed and reproduced from privacy-safe local Codex metadata.

A paused long-lived PR #9992 task provides a concrete amplification trace:

• target coordinator lifetime: 246.692M locally accounted tokens
• retained child lifetime: 218.297M
• target subtree lifetime: 464.988M
• one short cross-task delegation plus safe pause: 2.665M tokens in the target subtree
• including the concurrently orchestrating source task: 4.291M tokens over 5m16s
• the broader three-task delegation sequence: 11.454M tokens over roughly 14 minutes
• before compaction, target model calls carried roughly 215k-225k input tokens; after compaction, calls were roughly 80k, about 64% lower

The exact relationship to the account meter remains UNKNOWN; these are replay-safe local cumulative deltas, not a billing claim. The causal trace does establish that a small cross-task message can wake a large coordinator, resume a retained child, and cause repeated large-context model turns.

The wider forensic window recorded at least 3.566B delegated-child tokens, roughly 58% of its verified pre-tail total. That does not prove subagents are generally wrong; it proves that unbounded retained supervisors and children need a narrower default.

Official OpenAI documentation says subagents can improve parallel independent work and keep noisy work out of the main thread, but consume more tokens than comparable single-agent runs. It recommends summaries back to the main thread and greater caution for parallel write-heavy work because coordination overhead and conflicts increase: https://developers.openai.com/codex/agent-configuration/subagents

Official compaction guidance says compaction is intended to balance quality, cost, and latency as conversations grow: https://developers.openai.com/api/docs/guides/compaction

Proposed default topology

For ordinary implementation work:

1. one user-visible Codex task
2. one canonical repository-qualified issue, or one existing PR when no issue exists
3. one pr-batch execution lane
4. one implementation PR
5. one active maker at a time by default
6. bounded checker/reviewer/QA subagents that receive task-scoped packets and return compact durable receipts

The coordinator remains useful, but as a compact control plane for one issue/PR: requirements, ownership, current head, gates, budget, decisions, and final synthesis. It should not retain raw worker transcripts, test logs, polling history, or unrelated issue histories.

This strengthens #397's canonical-target requirement. It does not require every existing PR to gain a retroactive issue.

Explicit multi-target exception

Allow a portfolio-style multi-target batch only when the plan records a reason that one-target tasks cannot provide the needed result, such as:

• independent read-heavy triage or audit where parallelism has measured value
• an explicitly atomic cross-issue migration or release gate
• a tightly coupled dependency wave whose shared coordinator reduces rather than increases work

The exception must record target count, concurrency, aggregate and per-lane budgets, shared-context justification, expected savings, rollback, and human approval. Each issue/PR still keeps a separate canonical lane identity and durable receipt. An issue count greater than one must never by itself justify a strongest-model supervisor or parallel writers.

Compact coordinator contract

Add structured checkpoints so the supervisor carries only current state:

• compact after plan settlement and before worker dispatch
• compact after each worker report/review wave
• compact before monitor scheduling, cross-task handoff, or resuming an idle task
• compact when estimated rendered context crosses a configured threshold
• close completed child threads after their compact receipt is accepted
• resume an old worker only when its decision continuity has measured value; otherwise use the task brief, durable report, exact diff package, and open findings from Add task-scoped review packets and bounded fix/re-review loops to PR-batch #392

Thresholds must be configurable and calibrated from #398 receipts. Do not invent a universal absolute threshold before the pilot.

Cross-task delegation admission control

Before waking another task, the source coordinator must:

1. identify source and target batch/issue/PR identities
2. verify whether the target is active, idle, paused, stale, or terminal
3. estimate the target's current context and descendant fan-out from available metadata
4. reserve headroom under Enforce hierarchical token budgets with human checkpoints for PR batches #399 without double-counting the physical delta
5. coalesce queued messages when the target is already active
6. require compact checkpoint or human approval when the estimate exceeds policy
7. record predicted versus actual source, target-self, and target-descendant usage

Do not wake another task merely to acknowledge status, repeat unchanged evidence, or ask it to prepare a handoff that can be assembled deterministically.

Mechanism target

• Mechanism: schema + dispatcher preflight + compact checkpoint helper + replay experiment
• Motivating miss: a short delegation woke a 465M-token retained target subtree and triggered several large-context turns
• Replay evidence: the sanitized #9992 timing/usage trace plus deterministic fixtures for idle target, active target, retained child, coalesced messages, compaction, and human denial
• Non-goal: banning subagents, removing independent review, or claiming that one issue always requires only one model

Acceptance criteria

• The docs and planner state that one canonical issue or existing PR per user-visible task is the default implementation topology.
• Multi-target batches require an explicit reason and versioned exception receipt.
• A supervisor retains a compact structured manifest rather than raw worker/transcript history.
• Coordinator compaction checkpoints exist at dispatch, review-wave, monitor, handoff, and configured context-threshold boundaries.
• Subagents receive task-scoped packets and return durable compact receipts compatible with Add task-scoped review packets and bounded fix/re-review loops to PR-batch #392.
• Completed children are not kept resumable by default solely for convenience.
• Cross-task delegations run an admission preflight and coalesce messages to an already-active target.
• Delegation usage is attributed to source edge, target self, and descendants without double counting aggregate physical tokens.
• Enforce hierarchical token budgets with human checkpoints for PR batches #399 budgets apply before delegation, resume, worker spawn, retry, and review wave.
• One-target and multi-target modes preserve security, ownership, exact-head QA, review, and merge-authority gates.
• A matched pilot covers at least ten representative implementation batches and reports total tokens, credit equivalents, elapsed time, human coordination time, correction turns, first-pass acceptance, and escaped P0/P1 defects.
• Promotion requires materially lower usage with no escaped P0/P1 regression and no weakened gate compliance; otherwise retain the current topology and publish the result.
• Rollback to explicit multi-target mode is documented.

Candidate seams

• skills/plan-pr-batch/SKILL.md
• skills/pr-batch/SKILL.md
• skills/pr-batch/bin/
• workflows/pr-processing.md
• docs/agent-workflows-model-routing.md
• .agents/agent-workflow.yml

Dependencies and related work

• Add replay-safe batch and worker usage telemetry receipts #398 replay-safe usage receipts
• Enforce hierarchical token budgets with human checkpoints for PR batches #399 hierarchical budgets and human checkpoints
• Default routine PR-batch coordinators below Sol/xhigh and require measured escalation #400 phase-aware coordinator routing
• pr-batch: require an issue or existing PR before launch unless explicitly overridden #397 canonical issue/PR identity before launch
• Add task-scoped review packets and bounded fix/re-review loops to PR-batch #392 task-scoped packets and bounded fix/re-review loops
• Stop unchanged Goal monitors from repeatedly reloading full task context #393 unchanged monitor suppression

Non-goals

• Prohibiting multiple bounded subagents inside one issue/PR
• Weakening distinct review or current-head validation
• Treating chat history as the durable source of truth
• Assuming compaction alone fixes over-routing, repeated wakeups, or unbounded retries
• Claiming local accounting exactly equals OpenAI billing or plan-meter consumption

[justin808]

Concrete guardrail split: #403.

The new trace is stronger than the earlier short-delegation example. A long-lived eight-target C-batch task accepted cross-task messages, spawned a #9992 replacement worker, superseded old #9992 ownership, and began coordinating #9992 artifact/queue work even though #9992 was not in its original target set.

Replay-corrected local accounting at the frozen snapshot was approximately 3.085B for the parent plus 16 descendants. The active parent/C6/#9992 turn advanced about 63.38M over 88 minutes, with latest input near 146k/213k/231k per call respectively. Five visible recovery/heartbeat-only C6 turns cost about 3.376M.

#403 makes target membership and typed evidence-only delivery a narrow P1 guard. #402 remains the broader topology/compaction pilot.