Module task_supervisor 

Supervised lifecycle task manager for long-running named services.

TaskSupervisor manages named, long-lived background tasks (config watcher, scheduler loop, gateway, MCP connections, etc.) with restart policies, health snapshots, and graceful shutdown. Unlike [crate::agent::agent_supervisor::BackgroundSupervisor] (which is &mut self-only, lossy, and turn-scoped), TaskSupervisor is Clone + Send + Sync and designed for the full agent session lifetime.

Design rationale

• Shared handle: Arc<Inner> interior allows passing the supervisor to bootstrap code, TUI status display, and shutdown orchestration without lifetime coupling.
• Event-driven reap: An internal mpsc channel delivers completion events to a reap driver task; no polling interval required.
• No JoinSet: Individual JoinHandles per task enable per-name abort, status tracking, and restart policies — JoinSet is better for homogeneous work.
• Mutex held briefly: parking_lot::Mutex guards only bookkeeping operations (insert/remove from HashMap). The lock is never held across .await.

Examples

use std::time::Duration;
use tokio_util::sync::CancellationToken;
use zeph_core::task_supervisor::{RestartPolicy, TaskDescriptor, TaskSupervisor};

let cancel = CancellationToken::new();
let supervisor = TaskSupervisor::new(cancel.clone());

supervisor.spawn(TaskDescriptor {
    name: "my-service",
    restart: RestartPolicy::Restart { max: 3, base_delay: Duration::from_secs(1) },
    factory: || async { /* service loop */ },
});

// Graceful shutdown — waits up to 5 s for all tasks to stop.
supervisor.shutdown_all(Duration::from_secs(5)).await;

Structs

BlockingHandle

Handle returned by TaskSupervisor::spawn_blocking.

TaskDescriptor

Configuration passed to TaskSupervisor::spawn to describe a supervised task.

TaskHandle

Opaque handle to a single supervised task.

TaskSnapshot

Point-in-time snapshot of a supervised task, returned by TaskSupervisor::snapshot. Observability surface per field:

TaskSupervisor

Shared, cloneable handle to the supervised lifecycle task registry.

Enums

BlockingError

Error returned by BlockingHandle::join.

RestartPolicy

Policy governing what happens when a supervised task completes or panics.

TaskStatus

Point-in-time state of a supervised task.

Constants

MAX_RESTART_DELAY

Maximum delay between restart attempts (caps exponential backoff).