Fan-Out / Join (v1.1)

There is no separate "join task". The parent Task is the join.

1. A Task reaches a Station whose Agent decides the work decomposes (or whose trigger declares a Fan-Out — see Declarative Authoring).
2. The Agent calls the fan-out API on its own Task. The Server creates N Child Tasks at the requested Station and records the child ids on the parent as its blocker list (blockedBy; reference implementation: blockedByTaskIds).
3. The parent's Job concludes as normal and the parent moves on via its Transition Rules — typically to the Join Station.
4. Any dispatch of the parent while it has unsettled blockers is held (the Task enters the held state, a sibling of awaiting_review — see 05-tasks.md). The hold is Station-independent: wherever the parent is dispatched, unsettled blockers hold it. joinStation is where children settle, not a precondition for the hold.
5. Children execute in parallel (real parallelism requires multiple registered Runners — one Runner still runs one Job at a time, see 08-runner.md).
6. When the last blocker settles, the join releases exactly once: child results are aggregated onto the parent and the held dispatch fires.

Because children flow through the line's ordinary Transition Rules, authors write the natural rule childStation → joinStation on success. Rule matching is parentage-blind by design; the arrival-settles rule (below) is what prevents a child from ever running the Join Station.

POST /api/owners/{owner}/projects/{project}/assembly-lines/{assemblyLineId}/tasks/{taskId}/fan-out
Authorization: Bearer {token}

{
  "columnId": "research",
  "tasks": [
    { "title": "Research topic A", "description": "...", "labels": ["claude-code"] },
    { "title": "Research topic B", "description": "..." }
  ],
  "joinColumnId": "synthesize"
}

Naming note: on the wire the fields are columnId / joinColumnId — the reference implementation's internal name for a Station is "column" (see the naming crosswalk in 05-tasks.md). In spec prose these are the Station where children spawn and the Join Station. Earlier documents in this spec also write the legacy /stages/{assemblyLineId} path segment; the reference implementation serves /assembly-lines/{assemblyLineId}.

Response: { "childTaskIds": string[], "joinColumnId"?: string, "reused": boolean, "warnings": string[] }

Auth: the same bearer chain as Task submission (see 07-server.md) — a user token, a GitHub Actions OIDC token trusted by the project/line, or the Runner's own token. The reference pattern is the Agent calling the endpoint from inside its sandbox using the token the Operator environment already carries.

Settled is the predicate the join waits on. A Task settles when:

Settle is idempotent per Job — a re-delivered completion report cannot settle the same Task twice.

A Task does not settle when:

Every dispatch clears Settled. This is what makes retries coherent: retrying a settled child before the join releases re-arms its slot (the join waits for it again); retrying after the release is a detached re-run that cannot re-trigger the released join.

A child that settles with failure does not deadlock the join — the join waits for all children to settle, not to succeed. The Join Station's Agent sees each child's conclusion and decides what a partial result means.

The release is at-most-once and atomic. When a settle event finds every blocker settled, in a single critical section the Server:

1. Aggregates childResults on the parent — for each child: { title, conclusion, result }, where result is the child's final Station output (its completion summary). A child that was deleted appears as a tombstone with conclusion missing.
2. Stamps the release marker (joinReleasedAt). The stamp is the consume: concurrent settle events observing the marker back off, so two children settling simultaneously cannot double-release.
3. If a dispatch was actually held, clears the hold and fires the parent's dispatch at its current Station — exactly once.

If the children all settled before the parent ever arrived at a dispatching Station (fast children), no hold exists; the aggregation instead happens inline at the parent's next dispatch, in the same critical section that would otherwise have held it. Either way the Join Station's prompt never sees empty results.

POST /api/owners/{owner}/projects/{project}/assembly-lines/{assemblyLineId}/tasks/{taskId}/release-join
Authorization: Bearer {token}

{ "reason": "child stuck on dead runner" }

Decision Q12 stands: the Assembly Line Repository is the only sanctioned channel for passing work between Stations. Fan-Out amends it minimally:

A Child Task shares its parent's Assembly Line Repository.

At spawn, each child inherits the parent's repository reference — same URL, same credentials scope. Children write their outputs under:

reports/children/<child-task-title-slug>/

so the Join Station's Agent clones the one repository and reads every child's artifacts. childResults / {{children.results}} carry only the per-child completion summaries — the artifacts themselves travel through the shared repository, exactly as Q12 requires.

If the parent has no Assembly Line Repository, children run repo-less and only their completion summaries flow into the join. That is acceptable for light lines; lines that fan out real work should provision the repository before the fan-out Station.

A Station can declare its Fan-Out up front, so the Server injects the protocol into the Agent's prompt instead of relying on the line author to hand-write the API call:

{
  "id": "scope",
  "name": "SCOPE",
  "trigger": {
    "type": "dispatch_worker",
    "labels": ["claude-code"],
    "promptTemplate": "Break the task into research topics...",
    "fanOut": {
      "childColumnId": "research",
      "joinColumnId": "synthesize",
      "maxChildren": 5,
      "instructions": "One child per research topic. Keep titles short."
    }
  }
}

When set, the Server appends a fan-out protocol section to the rendered prompt containing the exact API call for this Task — the Agent only decides how many children and what each Task Card says.

These are different features and must not be conflated:

orchestration.fanOut is a prompt hint telling a single Station Operator's Agent to parallelize within its session. Task-level Fan-Out creates real Tasks with real Jobs, real sandboxes, and real Runner scheduling.

• Transition Rules (06-transition-rules.md): unchanged. Children match rules like any Task; the arrival-settles rule is evaluated by the dispatch path, not the rule matcher.
• Gates: a Gate on the parent's path behaves normally; a gated parent is awaiting_review, not settled and not held. Gates on child paths pause that child — the join waits.
• Task lifecycle (05-tasks.md): adds the held state and the Settled predicate.
• Runner protocol (08-runner.md): completely unchanged. Runners cannot tell a Child Task's Job from any other Job.
• Nesting: a Child Task may itself fan out (depth cap 2). Its own held state keeps it unsettled, so the outer join waits for the entire subtree.

See examples/fan-out-join.md — a four-Station research line: SCOPE (fan-out) → RESEARCH (children) → SYNTHESIZE (join) → DELIVER.