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

Async/liveness helpers for `pixir delegate` service commands.

This module is intentionally not a second scheduler. It projects delegate state from
the durable Session Log for `status`, and uses the existing Subagent Manager
only for bounded lifecycle actions such as `cancel`. The Log remains the source of
truth; Manager access is live-handle evidence that may be unavailable after a process
restart.

## TODO(delegate-service-v1)

Grow this into richer daemon/IPC-backed `attach` progress once Delegate needs
cross-invocation streaming observation. Current owner-backed `start`, `status`,
`attach`, and `cancel` can report daemon residency when routed through a manual
workspace daemon, but `attach` remains a bounded snapshot rather than a stream.

The next slice should preserve the current split:

  * `status` stays a durable Log projection and must remain useful after restart;
  * `cancel` should route through a live Delegate owner when one exists, and report an
    explicit `owner_unavailable`/`stale_handle` shape when it cannot affect running
    children;
  * `attach` should stream or snapshot progress without polling through shell loops;
  * response metadata should separate "request accepted" from "work complete" so
    long-running service clients do not treat `ok: false` running snapshots as errors.

# `attach`

```elixir
@spec attach(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, map()}
```

Attach to Delegate evidence by returning a bounded durable snapshot.

# `cancel`

```elixir
@spec cancel(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, map()}
```

Cancel live Subagent children for a Delegate handle when the Manager has handles.

# `start`

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

Start a Delegate run with a current-runtime owner.

# `status`

```elixir
@spec status(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, map()}
```

Return a durable Delegate status snapshot for a Delegate handle or parent Session.

---

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