# `Pixir.SessionSupervisor`
[🔗](https://github.com/Ranvier-Technologies/pixir/blob/main/lib/pixir/session_supervisor.ex#L1)

`DynamicSupervisor` of `Pixir.Session` processes (ADR 0001). A Session is started
on demand — for a new conversation or to `resume` a persisted one — and is
`:transient`, so it stays down once it finishes cleanly. The CLI may also ask this
supervisor to stop all currently running Sessions during process shutdown so
filesystem writer leases are released before the OS process exits.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `start_link`

# `start_session`

```elixir
@spec start_session(keyword()) :: {:ok, String.t(), pid()} | {:error, term()}
```

Start a Session. Accepts `:id` (generated if absent), `:workspace`, `:role`,
`:force_release_writer_lease?`, and `:force_release_reason`. Forced lease release is
a break-glass resume path for stale/ambiguous writer evidence; active leases are
refused. Returns `{:ok, session_id, pid}` so the caller always learns the id.

# `stop_all_sessions`

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

Stop every live Session owned by this runtime.

This is a CLI shutdown helper, not a stale-writer recovery path: it only terminates
processes that are currently supervised in this BEAM instance. Stale lease files
left by crashed or killed processes remain fail-closed for explicit resume handling.

# `stop_session`

```elixir
@spec stop_session(String.t()) :: {:ok, :stopped | :not_running} | {:error, map()}
```

Stop one live Session by id.

Presenter/Manager cleanup for fail-closed error paths that started a Session and
then refused it (e.g. a failed resume-posture restore): the process must not
survive its own rejection as an untracked live writer. A Session that is not
running is a no-op success.

---

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