# `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. Before
either attached or start-only execution creates a parent Session, shared limit
resolution and pure critical-path estimation enforce the caller horizon unless an
explicit short-horizon override was requested. Workflow admission retains the
normalized declared workflow timeout, whether that timeout was explicitly present in
the normalized workflow spec before default injection, the caller wait horizon, and
`wait_horizon_explicit` binding evidence as separate fields while runtime still
receives their same effective minimum. The wait-horizon evidence is true only when
the request or `limits.wait_horizon_ms` supplied it, and false when the horizon
defaulted from the delegate timeout. The runner 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.

# `admit_horizon_details`

```elixir
@spec admit_horizon_details(map(), term()) :: {:ok, map() | nil} | {:error, map()}
```

Apply the fail-closed Delegate horizon verdict to precomputed evidence.

# `critical_path`

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

Estimate the spec critical path using the same limits consumed by runtime.

# `known_task_entry_keys`

```elixir
@spec known_task_entry_keys() :: [String.t()]
```

Accepted keys inside one `tasks[]` object entry.

# `resolve_limits`

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

Resolve Delegate caller and child limits from the shared runtime precedence rules.

# `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.

# `validate_horizon_evidence`

```elixir
@spec validate_horizon_evidence(term()) :: :ok | {:error, map()}
```

Validate the facts used by Delegate horizon admission.

---

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