vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/services/ensemble/prompts/planner_turn.md

@@ -0,0 +1,6 @@
+<task>
+{{task}}
+</task>
+
+Inspect the workspace as needed, then return the roster of exactly {{roles}} roles as the
+single JSON object described in your instructions.

vidbyte_cli/services/ensemble/prompts/role_system.md

@@ -0,0 +1,104 @@
+<identity>
+{{identity}}
+</identity>
+
+<personality>
+{{personality}}
+</personality>
+
+<expertise>
+{{expertise}}
+</expertise>
+
+<knowledge>
+{{knowledge}}
+</knowledge>
+
+<skills>
+{{skills}}
+</skills>
+
+<goal>
+{{goal}}
+</goal>
+
+<mandate>
+Use this role to generate between {{minimum}} and {{maximum}} genuinely distinct approaches
+to the task in this session. You are producing a slate, not a recommendation, so do not stop
+when you find the first workable answer. Every approach must be complete enough for another
+agent to act on without asking you a follow-up question and different in substance from the
+others. Explain the assumptions that make it viable, the tradeoffs it accepts, and concrete
+checks that could validate or falsify it. Weigh it honestly rather than weakening the cons of
+the approach you personally prefer. A selector will compare your work with many other roles,
+so missing context can eliminate an otherwise strong idea.
+</mandate>
+
+<constraints>
+You are running in a read-only sandbox. You cannot write, move, or delete any file, and any
+attempt to do so will fail. Read whatever you need from the workspace, then describe work that
+could be performed; never claim that you already performed it.
+</constraints>
+
+<instructions-and-output>
+Here are the instructions to follow. Use the expertise, knowledge, and skills in your assigned
+profile to interpret the task through the particular perspective you were created to supply.
+Your purpose is not to echo the other roles or guess what a generic answer would look like; it
+is to produce a high-quality set of alternatives that this role is unusually qualified to see.
+Inspect evidence before relying on it, separate facts from assumptions, and make uncertainty
+visible. Deliberately create more possibilities than you return so the final slate reflects
+selection rather than the order in which ideas occurred to you. Keep the approaches different
+in mechanism, scope, sequencing, or governing principle. Then encode the result exactly in the
+structured form below.
+
+1. Understand the task from this role's perspective. Read the complete task and the planner
+   context, identify the outcome being sought, and name the constraints that matter most to
+   your role. Write a concise `task_analysis` that makes your interpretation explicit. Do not
+   begin proposing until you can distinguish the requested outcome from a merely familiar
+   version of the problem.
+2. Inspect the available evidence. Open the relevant workspace files, documentation, data, or
+   other artifacts that can confirm how the current system actually works. Record important
+   unknowns as assumptions instead of silently filling them in. Use your assigned expertise to
+   notice evidence another role might overlook.
+3. Diverge before choosing. Brainstorm at least three times as many candidate approaches as
+   the maximum you may return, varying the mechanism and the tradeoff profile rather than just
+   the wording. Include conservative, ambitious, incremental, and structurally different
+   options when they are genuinely applicable. Describe in `role_strategy` how your role
+   created useful variance.
+4. Evaluate and narrow. Test each candidate against the task, workspace facts, likely failure
+   modes, cost, reversibility, and the role's own standards. Remove duplicates, dominated
+   variants, and ideas that depend on assumptions you can already disprove. Keep between
+   {{minimum}} and {{maximum}} approaches that remain defensible for different reasons.
+5. Write actionable structured proposals. For every survivor, explain what to do, real pros
+   and cons, risks, affected files, assumptions, tradeoffs, and validation steps. Use
+   `confidence` to reflect the quality of evidence, not enthusiasm. Re-read the whole slate as
+   an implementer and fill any context gap that would otherwise require a follow-up.
+
+Return one JSON object and nothing else. It has exactly four top-level keys:
+`role` is "{{role_name}}"; `task_analysis` explains how this role interprets the task;
+`role_strategy` explains how this role created and narrowed its alternatives; and `approaches`
+is an array of {{minimum}} to {{maximum}} objects. Every approach has exactly ten keys:
+`title`, `approach`, `pros`, `cons`, `risks`, `files`, `confidence`, `assumptions`,
+`tradeoffs`, and `validation_steps`. The plural context fields are arrays of strings;
+`pros`, `cons`, `assumptions`, `tradeoffs`, and `validation_steps` each contain at least one
+item, while `risks` and `files` may be empty. `confidence` is exactly `low`, `medium`, or
+`high`. No prose, code fence, missing key, extra key, or out-of-band text is permitted.
+</instructions-and-output>
+
+<checklist>
+Before returning, verify every one of these:
+1. The slate contains between {{minimum}} and {{maximum}} approaches.
+2. Every approach differs materially from every other approach.
+3. Every approach is relevant to the actual task and consistent with inspected evidence.
+4. Every assumption is explicit and every validation step could produce evidence.
+5. Pros and cons are concrete, balanced, and specific to their approach.
+6. An implementer could act on each approach without asking what it means.
+7. The object uses exactly the keys and value types required above.
+</checklist>
+
+<things-not-to-do>
+- Do not edit the workspace or describe an edit as already completed.
+- Do not pad the slate with cosmetic variants to reach the minimum count.
+- Do not let a favorite approach receive vague cons while alternatives receive detailed ones.
+- Do not treat an unverified premise as a workspace fact.
+- Do not write a hybrid entry that asks the selector to choose among several hidden variants.
+</things-not-to-do>

vidbyte_cli/services/ensemble/prompts/role_turn.md

@@ -0,0 +1,19 @@
+<task>
+{{task}}
+</task>
+
+<planner-context>
+Task analysis:
+{{task_analysis}}
+
+Why this roster was assembled:
+{{roster_strategy}}
+
+Coverage the roster is intended to provide:
+{{coverage_summary}}
+</planner-context>
+
+Investigate the workspace from your assigned perspective, then return your slate of
+{{minimum}} to {{maximum}} approaches as the single JSON object described in your
+instructions. Name every file an approach would change in its `files` array, so the agent that
+compares approaches can see where yours and another member's touch the same place.

vidbyte_cli/services/ensemble/prompts/selector_final_turn.md

@@ -0,0 +1,19 @@
+<task>
+{{task}}
+</task>
+
+<round number="{{round}}" surviving="{{surviving}}" keep="1">
+This is the final round. {{surviving}} candidates are still alive and exactly one may survive.
+The candidate you keep is the approach that will actually be implemented. Your `round_summary`,
+`comparison_basis`, `rationale`, `evidence`, `uncertainties`, `implementation_guidance`, and
+`cons` are the brief the implementing agent receives — it cannot see this conversation or the
+other candidates. Say what is to be done and what it must be careful of, concretely enough to
+act on.
+</round>
+
+<candidates>
+{{candidates}}
+</candidates>
+
+Return the round as the single JSON object described in your instructions, keeping exactly one
+candidate.

vidbyte_cli/services/ensemble/prompts/selector_round_turn.md

@@ -0,0 +1,17 @@
+<task>
+{{task}}
+</task>
+
+<round number="{{round}}" surviving="{{surviving}}" keep="{{target}}">
+This is narrowing round {{round}}. {{surviving}} candidates are still alive and exactly
+{{target}} may survive this round. Weigh the pros and cons of every candidate you keep, and
+list every id you drop. State the common comparison basis, summarize the round, and include
+evidence, uncertainty, and implementation guidance for every survivor.
+</round>
+
+<candidates>
+{{candidates}}
+</candidates>
+
+Return the round as the single JSON object described in your instructions, keeping exactly
+{{target}} candidates.

vidbyte_cli/services/ensemble/prompts/selector_system.md

@@ -0,0 +1,89 @@
+<identity>
+You are an expert decision architect who selects among competing approaches to difficult tasks
+in any domain. You know how to compare technical plans, research strategies, operational
+responses, creative directions, business decisions, and other forms of proposed action without
+pretending they share one universal success metric. Several independent specialists have each
+offered alternatives, none saw the others' work, and none can answer follow-up questions. You
+must end the disagreement transparently and in writing. You distinguish persuasive presentation
+from evidence, confidence from calibration, and popularity from independent confirmation. You
+reason by disciplined elimination and comparative fit rather than enthusiasm. You do not carry
+out the task or invent a new solution; you read, verify, compare, narrow, and choose.
+</identity>
+
+<goal>
+Reduce a slate of candidate approaches to the single best one, in a sequence of narrowing
+rounds you will be walked through one round at a time. Your measure of success is that the
+approach you end on would still be the right choice to someone who read every candidate
+carefully — not the one that was described most fluently and not the one the most people
+happened to suggest. In each round you will be given the candidates that are still alive and
+told exactly how many may survive it, and you must weigh the pros and cons of every candidate
+you keep so that the reason it survived is on the record. Popularity is weak evidence, since
+two colleagues sharing an assumption is one assumption counted twice; verifiable fit with the
+available evidence is strong evidence. When you are down to the final round you will be asked
+for exactly one candidate, and what you write about it becomes the brief the implementer
+works from, so it must be specific enough to act on. You may inspect the workspace and any
+available task artifacts to check a claim a candidate depends on, and you should, because a
+claim you can falsify is the fastest way to eliminate a whole group of candidates at once.
+</goal>
+
+<instructions-and-output>
+Here are the instructions to follow in every narrowing round. Use the task itself to determine
+what success means instead of applying an engineering-only or domain-independent scorecard.
+Compare every candidate on the same explicit basis while allowing the task to decide which
+criteria deserve the most weight. Check claims against available evidence when doing so is
+practical, and identify uncertainty when it is not. Preserve useful diversity in early rounds
+so the process does not converge prematurely on several versions of one idea. Make every
+elimination traceable to a comparative reason. In the final round, write guidance detailed
+enough for another agent to execute without seeing the discarded slate.
+
+1. Frame the decision. Read the task, every surviving candidate, and the context its proposing
+   role supplied before ranking anything. Identify the outcome, constraints, and domain-specific
+   standards that distinguish success from a superficially plausible answer. State those
+   standards in `comparison_basis` and summarize the round's decision in `round_summary`.
+2. Verify premises. Separate observed facts, proposer assumptions, and claims that can be
+   checked against workspace or task artifacts. Perform cheap decisive checks and cite the
+   resulting evidence in each kept verdict. Treat unresolved material questions as
+   `uncertainties`, never as facts that happen to support a preferred candidate.
+3. Remove redundancy and infeasibility. Group candidates that are materially the same despite
+   different wording, and retain at most the strongest representative when capacity is scarce.
+   Eliminate candidates with false critical premises or fatal constraint violations. Do not
+   create a hybrid replacement, because only offered candidates may survive.
+4. Compare tradeoffs and preserve option value. Weigh fit, benefits, costs, risks, assumptions,
+   validation burden, reversibility, and likely quality of execution. In non-final rounds, keep
+   distinct mechanisms when their relative value remains genuinely unresolved. Use scores as a
+   comparative summary of the analysis rather than as a substitute for it.
+5. Narrow exactly and hand off clearly. Keep exactly the required number, name every eliminated
+   id, and ensure every id came from the current slate. For each survivor, write concrete pros,
+   cons, rationale, evidence, uncertainties, and `implementation_guidance`. In the final round,
+   make that guidance a complete execution brief for the selected approach.
+
+Return one JSON object and nothing else. It has exactly four top-level keys:
+`round_summary` is the round's concise comparative conclusion; `comparison_basis` is an array
+of at least one criterion applied across the slate; `kept` contains exactly the required number
+of verdict objects; and `eliminated` contains every dropped id. Each verdict has exactly eight
+keys: `candidate_id`, `pros`, `cons`, `score`, `rationale`, `evidence`, `uncertainties`, and
+`implementation_guidance`. `pros`, `cons`, and `evidence` are non-empty arrays of strings;
+`uncertainties` is an array that may be empty; `score` is an integer from 1 to 100. Every id
+must have been offered in the current round. Missing keys, extra keys, prose, or code fences
+fail the run.
+</instructions-and-output>
+
+<checklist>
+Before returning, verify every one of these:
+1. Every surviving candidate was read before any was eliminated.
+2. The comparison basis comes from the task and was applied consistently.
+3. Duplicates do not occupy multiple survivor slots without a stated material difference.
+4. Every kept verdict has concrete evidence, uncertainty, pros, cons, and execution guidance.
+5. Scores are comparable and rationales explain rather than repeat them.
+6. Exactly the requested number survived and every offered id appears once across the outcome.
+7. The structured object uses exactly the required keys and value types.
+</checklist>
+
+<things-not-to-do>
+- Do not invent a hybrid or rewrite a candidate while evaluating it.
+- Do not treat proposer confidence or repeated popularity as independent evidence.
+- Do not use an engineering convention as a criterion unless the task is engineering work.
+- Do not eliminate a candidate solely because it is unfamiliar or more laborious.
+- Do not defer a decision by carrying redundant candidates into the next round.
+- Do not hide an unresolved material premise behind a confident score.
+</things-not-to-do>

vidbyte_cli/services/ensemble/runner.py

@@ -0,0 +1,30 @@
+"""Launches one verified ensemble run: build the stages, then run the algorithm.
+
+The command admits and verifies before calling here, so this class never touches the
+network: it receives the loaded SDK and the verified grant, builds the run's stages, and
+hands them to the service. The charged admission travels with the grant into the result.
+"""
+
+from __future__ import annotations
+
+from ...types.ensemble import EnsembleInputs, EnsembleResult
+from ...types.runtime import RuntimeAdmissionGrant, RuntimeLaunchPlan
+from .sdk import EnsembleSdk
+from .service import EnsembleService
+from .settings import EnsembleStages
+
+
+class EnsembleRunner:
+    """Builds one run's stages from verified inputs and runs the ensemble algorithm."""
+
+    def run(
+        self,
+        plan: RuntimeLaunchPlan,
+        inputs: EnsembleInputs,
+        sdk: EnsembleSdk,
+        grant: RuntimeAdmissionGrant,
+    ) -> EnsembleResult:
+        # No admission here: the command already bought and verified it, so starting the
+        # service is the only thing left that can fail.
+        stages = EnsembleStages(sdk, inputs, plan.working_directory)
+        return EnsembleService(stages).run(grant.charged_cents)

vidbyte_cli/services/ensemble/sdk.py

@@ -0,0 +1,134 @@
+"""The single lazy binding between this CLI and the Vidbyte SDK's Codex integration.
+
+Every SDK symbol is resolved inside `load()`, never at module scope, so `vidbyte-cli --help`
+stays fast and keeps working even where the SDK's Codex integration is missing or too old.
+Callers see only the local Protocol and this class.
+
+Resolution happens before paid admission, so a missing dependency costs nothing.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol
+
+from ...lib.errors.failures import EnsembleSdkUnavailable
+from ...types.ensemble import EnsembleInputs
+
+# The SDK module path and the exact symbols this service needs from it.
+_CODEX_MODULE = "vidbyte.agents.codex"
+_ERRORS_MODULE = "vidbyte.lib.errors"
+_REQUIRED = (
+    "CodexAgentSettings",
+    "CodexForkSettings",
+    "CodexHarnessAgentSettings",
+    "CodexReasoningEffort",
+    "CodexRunInput",
+    "CodexSandbox",
+    "CodexThreadSettings",
+    "CodexTurnSettings",
+)
+
+
+# The two SDK exception classes the service must tell apart: host fault, schema violation.
+ErrorTypes = tuple[type[Exception], type[Exception]]
+
+
+class EnsembleAgent(Protocol):
+    """The subset of the SDK agent surface this service actually drives."""
+
+    thread_id: str
+
+    async def arun(self, request: Any) -> Any: ...
+
+    async def afork(self, settings: Any) -> EnsembleAgent: ...
+
+
+class EnsembleSdk:
+    """Holds the resolved SDK symbols and builds every provider value from them."""
+
+    def __init__(self, symbols: dict[str, Any], agent: Any, errors: ErrorTypes) -> None:
+        # Storing the resolved symbols is what keeps every SDK name confined to this module.
+        self._symbols = symbols
+        self._agent_type = agent
+        self._error_type, self._schema_error_type = errors
+
+    @classmethod
+    def load(cls) -> EnsembleSdk:
+        # Imports at call time; an SDK predating the Codex integration fails the same way.
+        try:
+            codex = __import__(_CODEX_MODULE, fromlist=["*"])
+            errors = __import__(_ERRORS_MODULE, fromlist=["*"])
+            symbols = {name: getattr(codex, name) for name in _REQUIRED}
+            agent_type = codex.CodexHarnessAgent
+            resolved = (errors.CodexAgentError, errors.OutputSchemaViolationError)
+        except (ImportError, AttributeError) as error:
+            raise EnsembleSdkUnavailable(error) from error
+        return cls(symbols, agent_type, resolved)
+
+    def agent(self, settings: Any) -> EnsembleAgent:
+        # Constructs a root agent; forks are produced by the agent itself, never here.
+        created: EnsembleAgent = self._agent_type(settings)
+        return created
+
+    def run_input(self, prompt: str) -> Any:
+        # One text turn, which is the only input modality this primitive uses.
+        return self._symbols["CodexRunInput"].text(prompt)
+
+    def is_provider_error(self, error: Exception) -> bool:
+        # Lets the service classify a host failure without importing the SDK's error class.
+        return isinstance(error, self._error_type)
+
+    def is_schema_error(self, error: Exception) -> bool:
+        # A schema violation is a sibling of CodexAgentError, not a subclass: the host worked,
+        # the model just produced output that did not validate. The two need different errors.
+        return isinstance(error, self._schema_error_type)
+
+    def root_settings(self, prompt: str, schema: type, codex: Any) -> Any:
+        # The planner reads the workspace to design roles, so it is read-only like the roles.
+        return self._symbols["CodexHarnessAgentSettings"](
+            name="ensemble-planner",
+            system_prompt=prompt,
+            codex=codex,
+            output_schema=schema,
+        )
+
+    def fork_settings(self, name: str, prompt: str, schema: type | None, codex: Any) -> Any:
+        # A fork inherits everything it does not override; the schema decides its output shape.
+        return self._symbols["CodexForkSettings"](
+            name=name,
+            system_prompt=prompt,
+            codex=codex,
+            output_schema=schema,
+            clear_output_schema=schema is None,
+        )
+
+    def codex_settings(self, inputs: EnsembleInputs, cwd: Path, *, write: bool) -> Any:
+        # Sandbox is set on thread and turn because an unset value inherits the user's config.
+        sandbox = self._sandbox(write=write)
+        return self._symbols["CodexAgentSettings"](
+            thread=self._symbols["CodexThreadSettings"](
+                cwd=str(cwd),
+                model=inputs.model or "",
+                sandbox=sandbox,
+                ephemeral=False,
+            ),
+            turn=self._symbols["CodexTurnSettings"](
+                cwd=str(cwd),
+                effort=self._effort(inputs),
+                model=inputs.model or "",
+                sandbox=sandbox,
+            ),
+        )
+
+    def _sandbox(self, *, write: bool) -> Any:
+        # Read-only is never the provider default, so both modes are named explicitly.
+        sandbox = self._symbols["CodexSandbox"]
+        return sandbox.WORKSPACE_WRITE if write else sandbox.READ_ONLY
+
+    def _effort(self, inputs: EnsembleInputs) -> Any:
+        # An unset effort maps to the provider-default sentinel the SDK strips before sending.
+        effort = self._symbols["CodexReasoningEffort"]
+        if inputs.reasoning_effort is None:
+            return effort.PROVIDER_DEFAULT
+        return effort(inputs.reasoning_effort.value)

vidbyte_cli/services/ensemble/service.py

@@ -0,0 +1,233 @@
+"""The four-stage algorithm: plan roles, propose in parallel, select down to one, implement.
+
+Roles branch from the root thread rather than from each other, so their errors stay
+decorrelated — that independence is the whole reason an ensemble beats one agent. The
+selector and the implementer also branch from the root, so neither inherits a single role's
+framing; the selector then runs several turns on its own thread, which is what lets a later
+narrowing round build on the reasoning of the earlier ones.
+
+A role that fails is recorded and stepped over; only an empty slate aborts the run.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from math import ceil
+from typing import Any, Literal
+
+from ...lib.errors.failures import (
+    EnsembleAllRolesFailed,
+    EnsembleHostFailed,
+    EnsembleImplementerFailed,
+    EnsembleProposalUnusable,
+    EnsembleRolePlanInvalid,
+    EnsembleSelectionInvalid,
+)
+from ...types.ensemble import (
+    ApproachCandidate,
+    EnsembleResult,
+    EnsembleRoleFailure,
+    GeneratedRole,
+    RolePlan,
+    RoleProposal,
+    SelectedApproach,
+    SelectionRound,
+)
+from .sdk import EnsembleAgent
+from .settings import EnsembleStages
+
+RoleFailureReason = Literal["timeout", "host_error", "invalid_output"]
+Proposals = tuple[RoleProposal, ...]
+Candidates = tuple[ApproachCandidate, ...]
+
+# Each round keeps a fifth of what it was given, so a thousand candidates reach one in five
+# rounds while fifteen reach one in two. Narrowing this fast is what keeps the selector's
+# context bounded; the ladder is computed here rather than chosen by the agent so a run's
+# shape depends only on how many candidates exist.
+_NARROWING_DIVISOR = 5
+
+
+class EnsembleService:
+    """Runs one same-host ensemble from a validated plan to a normalized result."""
+
+    def __init__(self, stages: EnsembleStages) -> None:
+        # One service instance per run; the stages object carries every shared collaborator.
+        self._stages = stages
+
+    def run(self, cents: int) -> EnsembleResult:
+        # The single synchronous boundary; everything below it shares one event loop.
+        return asyncio.run(self._orchestrate(cents))
+
+    async def _orchestrate(self, cents: int) -> EnsembleResult:
+        # Plan, fan out concurrently, narrow to one, implement; the root is the only ancestor.
+        inputs = self._stages.inputs
+        root = self._stages.sdk.agent(self._stages.root())
+        plan = await self._plan_roles(root)
+        outcomes = await asyncio.gather(
+            *(self._propose(root, role, plan) for role in plan.roles),
+            return_exceptions=True,
+        )
+        proposals, failures = self._partition(plan.roles, list(outcomes))
+        if not proposals:
+            raise EnsembleAllRolesFailed(len(failures))
+        candidates = self._candidates(proposals)
+        rounds, selected, selector_thread = await self._select(root, candidates)
+        implementation, thread_id = await self._implement(root, selected, len(candidates))
+        return EnsembleResult(
+            task=inputs.task,
+            host=inputs.host,
+            roles=plan.roles,
+            proposals=proposals,
+            failures=failures,
+            candidates=len(candidates),
+            rounds=rounds,
+            selected=selected,
+            implementation=implementation,
+            root_thread_id=root.thread_id,
+            selector_thread_id=selector_thread,
+            implementer_thread_id=thread_id,
+            charged_cents=cents,
+        )
+
+    async def _plan_roles(self, root: EnsembleAgent) -> RolePlan:
+        # One turn, which both mints the thread id forking requires and designs the roster.
+        stages = self._stages
+        prompt = stages.prompts.planner_turn_prompt(stages.inputs.task, stages.inputs.roles)
+        try:
+            reply = await root.arun(stages.sdk.run_input(prompt))
+        # CancelledError is a BaseException, so Ctrl-C passes through this handler untouched.
+        except Exception as error:
+            if stages.sdk.is_schema_error(error):
+                raise EnsembleRolePlanInvalid(stages.inputs.roles) from error
+            raise EnsembleHostFailed("planner", error) from error
+        plan = getattr(reply, "structured", None)
+        if not isinstance(plan, RolePlan) or len(plan.roles) != stages.inputs.roles:
+            raise EnsembleRolePlanInvalid(stages.inputs.roles)
+        # Names label every candidate the selector sees, so duplicates would make ids ambiguous.
+        if len({role.name for role in plan.roles}) != len(plan.roles):
+            raise EnsembleRolePlanInvalid(stages.inputs.roles)
+        return plan
+
+    async def _propose(
+        self, root: EnsembleAgent, role: GeneratedRole, plan: RolePlan
+    ) -> RoleProposal:
+        # Bounded so one hung host cannot hold the fan-in open for every other role.
+        stages = self._stages
+        prompt = stages.prompts.role_turn_prompt(stages.inputs.task, plan)
+        async with asyncio.timeout(stages.inputs.role_timeout_seconds):
+            agent = await root.afork(stages.proposal(role))
+            reply = await agent.arun(stages.sdk.run_input(prompt))
+        proposal = getattr(reply, "structured", None)
+        if not isinstance(proposal, RoleProposal):
+            raise EnsembleProposalUnusable(role.name)
+        return proposal
+
+    async def _select(
+        self, root: EnsembleAgent, candidates: Candidates
+    ) -> tuple[tuple[SelectionRound, ...], SelectedApproach, str]:
+        # One selector thread across every round, so a later round sees its own earlier reasoning.
+        stages = self._stages
+        try:
+            agent = await root.afork(stages.selector())
+        except Exception as error:
+            raise EnsembleHostFailed("selector", error) from error
+        rounds: list[SelectionRound] = []
+        alive = candidates
+        while True:
+            number, target = len(rounds) + 1, self._target(len(alive))
+            final = target == 1
+            outcome = await self._round(agent, self._round_prompt(alive, number, target), target)
+            rounds.append(outcome)
+            alive = self._survivors(alive, outcome)
+            if final:
+                # The winner is joined back to its full proposal, which no agent resends.
+                chosen = SelectedApproach(
+                    candidate=alive[0],
+                    verdict=outcome.kept[0],
+                    round_summary=outcome.round_summary,
+                    comparison_basis=outcome.comparison_basis,
+                )
+                return tuple(rounds), chosen, agent.thread_id
+
+    def _round_prompt(self, alive: Candidates, number: int, target: int) -> str:
+        # The last round is authored separately: what it writes becomes the implementer brief.
+        prompts, task = self._stages.prompts, self._stages.inputs.task
+        if target == 1:
+            return prompts.selector_final_prompt(task, alive, number)
+        return prompts.selector_round_prompt(task, alive, number, target)
+
+    async def _round(self, agent: EnsembleAgent, prompt: str, target: int) -> SelectionRound:
+        # A round the host cannot complete ends the run: there is no partial way to narrow.
+        stages = self._stages
+        try:
+            reply = await agent.arun(stages.sdk.run_input(prompt))
+        except Exception as error:
+            if stages.sdk.is_schema_error(error):
+                raise EnsembleSelectionInvalid(target) from error
+            raise EnsembleHostFailed("selector", error) from error
+        outcome = getattr(reply, "structured", None)
+        if not isinstance(outcome, SelectionRound) or len(outcome.kept) != target:
+            raise EnsembleSelectionInvalid(target)
+        return outcome
+
+    def _survivors(self, alive: Candidates, outcome: SelectionRound) -> Candidates:
+        # Kept ids are matched against the slate actually offered, never trusted as given.
+        offered = {candidate.candidate_id: candidate for candidate in alive}
+        kept = tuple(dict.fromkeys(verdict.candidate_id for verdict in outcome.kept))
+        if len(kept) != len(outcome.kept) or any(item not in offered for item in kept):
+            raise EnsembleSelectionInvalid(len(outcome.kept))
+        return tuple(offered[item] for item in kept)
+
+    def _target(self, alive: int) -> int:
+        # Always narrows: a slate of five or fewer goes straight to the final round.
+        return max(ceil(alive / _NARROWING_DIVISOR), 1)
+
+    def _candidates(self, proposals: Proposals) -> Candidates:
+        # Ids are assigned here so they are stable, compact, and checkable on the way back.
+        return tuple(
+            ApproachCandidate(
+                candidate_id=f"{role_index}.{approach_index}",
+                role=proposal.role,
+                task_analysis=proposal.task_analysis,
+                role_strategy=proposal.role_strategy,
+                approach=approach,
+            )
+            for role_index, proposal in enumerate(proposals, 1)
+            for approach_index, approach in enumerate(proposal.approaches, 1)
+        )
+
+    async def _implement(
+        self, root: EnsembleAgent, selected: SelectedApproach, candidates: int
+    ) -> tuple[str, str]:
+        # Forks the root, not the selector, so it inherits the task but not the deliberation.
+        stages = self._stages
+        prompt = stages.prompts.implementer_turn_prompt(
+            stages.inputs.task, selected, candidates, stages.inputs.roles
+        )
+        try:
+            agent = await root.afork(stages.implementer())
+            reply = await agent.arun(stages.sdk.run_input(prompt))
+        except Exception as error:
+            raise EnsembleImplementerFailed(error) from error
+        return str(getattr(reply, "content", "")), agent.thread_id
+
+    def _partition(self, roles: tuple[GeneratedRole, ...], outcomes: list[Any]) -> tuple[Any, Any]:
+        # Survivors carry the run; a failed role becomes a record, never a raised error.
+        proposals: list[RoleProposal] = []
+        failures: list[EnsembleRoleFailure] = []
+        for role, outcome in zip(roles, outcomes, strict=True):
+            if isinstance(outcome, RoleProposal):
+                proposals.append(outcome)
+            elif isinstance(outcome, BaseException):
+                failures.append(EnsembleRoleFailure(role=role.name, reason=self._reason(outcome)))
+        return tuple(proposals), tuple(failures)
+
+    def _reason(self, error: BaseException) -> RoleFailureReason:
+        # Cancellation is re-raised rather than classified, so Ctrl-C still reaches the caller.
+        if isinstance(error, asyncio.CancelledError):
+            raise error
+        if isinstance(error, TimeoutError):
+            return "timeout"
+        if isinstance(error, Exception) and self._stages.sdk.is_provider_error(error):
+            return "host_error"
+        return "invalid_output"