# `PgFlow.WorkerSupervisor`
[🔗](https://github.com/agoodway/pgflow/blob/v0.4.0/lib/pgflow/worker_supervisor.ex#L1)

Supervisor for PgFlow workers.

This module manages worker processes that poll for and execute flow tasks.
Sequential starts for the same flow reuse the registered worker on this node.

Workers are GenServer processes that:
- Compile or verify their flow definition via `PgFlow.Worker.Bootstrap` on startup
- Poll pgmq for pending messages
- Execute step handlers concurrently via Task.Supervisor
- Report task completion/failure back to pgflow
- Handle graceful shutdown

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `find_worker`

```elixir
@spec find_worker(module()) :: pid() | nil
```

Returns the pid registered for a flow module, if any.

# `list_workers`

```elixir
@spec list_workers() :: [%{pid: pid(), status: :running}]
```

Lists all running workers.

Returns a list of maps with worker information.

# `start_link`

```elixir
@spec start_link(keyword()) :: Supervisor.on_start()
```

Starts the WorkerSupervisor.

# `start_worker`

```elixir
@spec start_worker(module(), keyword()) :: {:ok, pid()} | {:error, term()}
```

Starts a worker for the given flow.

## Options

  * `:repo` - The Ecto repository (optional, defaults to configured repo)

Returns `{:ok, pid}` on success or `{:error, reason}` on failure.

# `stop_worker`

```elixir
@spec stop_worker(module()) :: :ok | {:error, :not_found}
```

Stops a worker for the given flow.

Gracefully stops the worker, waiting for active tasks to complete, then
terminates the supervised child and unregisters it. Normal stops are final
under the transient restart policy; crashes and deprecation exits restart.

---

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