Homeboy core owns durable orchestration and provider-neutral evidence. Runtime providers own backend-specific execution details. The seam is the AgentTaskRequest/AgentTaskOutcome adapter boundary.

Ownership map

Narrow seam

The canonical Sandbox product-facing path is:

Agents API substrate -> Homeboy durable scheduler/fanout plan -> Homeboy Extensions executor adapter -> Managed Sandbox sandbox worker runtime/artifact contracts

Homeboy persists the plan/run ids, deterministic scheduling order, dependency skip state, child run refs, and artifact/evidence refs. Homeboy Extensions maps one normalized task request to the selected runtime provider. Managed Sandbox owns the lower-level sandbox-native fanout request/result/event/artifact contracts inside the isolated worker runtime.

Homeboy submits provider-neutral AgentTaskRequest tasks to an executor provider. The provider may translate the task into any backend-specific single-task or fanout request, but Homeboy core does not depend on provider runtime field names.

The public operator meaning of agent-task fanout is batch cook: many independent cooks, each with its own worktree/branch and its own PR finalization. Generic provider-neutral fanout scheduling remains an internal implementation seam for adapters and schedulers that need it; it is not the public CLI contract.

Public batch-cook fanout lowers each cook into the normal cook-loop path, so Homeboy owns dispatch, promotion, deterministic gates, commit/push, and PR finalization per cook. Provider adapters still receive one normalized AgentTaskRequest at a time and return one normalized AgentTaskOutcome at a time.

Durable batch fanout (agent-task fanout submit-batch) is the generic queue and reconcile surface for independent agent-task plans. It persists one child run per task and exposes stable read-side reports:

• homeboy/agent-task-batch-status/v1 reports the batch record, child run states, per-state totals, and follow-up commands.
• homeboy/agent-task-batch-artifacts/v1 collates child run artifacts into a provider-neutral summary and manifest keyed by task_id, run_id, and child run state while preserving each child run’s normal AgentTaskRunArtifacts payload under child_runs[].

The artifact manifest contains Homeboy AgentTaskArtifact and AgentTaskEvidenceRef records only. Providers keep backend-native worker, session, and artifact namespace details in evidence refs or opaque metadata.

The provider returns a normalized AgentTaskOutcome:

• status, summary, and failure_classification use Homeboy outcome values.
• artifacts[] contains only Homeboy AgentTaskArtifact records.
• evidence_refs[] points at provider sessions, event streams, manifests, or worker results through URI-style refs.
• workflow.steps[] can describe planner, worker, validator, repair, or aggregation phases in Homeboy’s generic workflow evidence shape.
• metadata may include opaque provider refs such as fanout id, parent session id, worker ids, schema name, or version.

Rules

• Homeboy core treats fanout payloads as opaque provider payloads until the owning adapter normalizes them.
• Homeboy schemas do not duplicate provider session, worker, artifact namespace, runtime event, or conflict payload fields.
• Provider schemas keep caller metadata opaque; they do not encode Homeboy issue, PR, worktree, queue, retry, or promotion semantics.
• Provider refs are durable enough for Homeboy to persist and reconcile, but Homeboy does not parse them beyond generic kind, uri, label, and opaque metadata.
• Promotion and apply decisions remain Homeboy policy even when the patch or evidence came from a runtime provider.

Representative normalization

Provider adapters normalize backend-specific fanout results into Homeboy’s generic AgentTaskOutcome shape before returning them to core. Provider session, worker, and aggregation details stay as evidence refs or opaque metadata instead of becoming Homeboy core schema fields.

Provider-specific fixture coverage belongs in the provider layer that owns that backend integration.

Related trackers

• Homeboy fanout epic: https://github.com/Extra-Chill/homeboy/issues/3206
• Homeboy async lifecycle: https://github.com/Extra-Chill/homeboy/issues/3278
• Homeboy provider-native handles: https://github.com/Extra-Chill/homeboy/issues/3286
• Homeboy fleet cooking migration: https://github.com/Extra-Chill/homeboy/issues/3357
• Boundary tracker: https://github.com/Extra-Chill/homeboy/issues/3578