# `Pixir.Delegate.Runner`
[🔗](https://github.com/Ranvier-Technologies/pixir/blob/main/lib/pixir/delegate/runner.ex#L1)

Attached runtime runner for `pixir delegate`.

This module is the first real implementation behind the Delegate CLI I/O Contract.
It keeps `Pixir.Delegate.CLIContract` focused on parsing/rendering and uses existing
Pixir runtime surfaces for work:

  * parent Session creation goes through `Pixir.Conversation`;
  * Subagent fanout goes through `Pixir.Subagents`;
  * read-only and bounded-write Workflow fanout goes through `Pixir.Workflows`;
  * terminal status comes from `wait_outcome/4` or the Workflow result envelope;
  * durable truth remains the parent and child Session Logs plus Workflow Events.

It also exposes a start-only primitive for the current-runtime Delegate owner. It
deliberately does not implement streaming attach, cross-invocation daemon residency,
merge-back/apply, or any process-per-child shell fanout. Bounded-write Workflow support
is attached-only, requires explicit per-step write sets, and reports where writes land.

Delegate task attachments are operator-supplied Session Resource links under ADR 0021;
they are consumed by each child Session's first user message and are not echoed in
the delegate envelope.

## TODO(delegate-service-v1)

Keep the attached runner as the synchronous compatibility path. The service owner
reuses the same normalization and start vocabulary, but owns current-runtime lifetime
and active cancellation in OTP. Avoid adding caller-side loops here that would make
`pixir delegate --spec` pretend to be a detached daemon.

# `run`

```elixir
@spec run(map(), map(), map(), keyword()) :: {:ok, map()} | {:error, map()}
```

Run a validated Delegate spec through the attached runtime path.

# `start`

```elixir
@spec start(map(), map(), map(), keyword()) :: {:ok, map()} | {:error, map()}
```

Start a validated subagents Delegate spec without waiting for terminal completion.

This is the runtime primitive used by the current-BEAM Delegate owner. It creates the
durable parent Session, spawns child Subagents through the normal Manager, and returns
start evidence plus owner context. It does not start a daemon or a nested Pixir
process.

---

*Consult [api-reference.md](api-reference.md) for complete listing*