Skip to main content

Module lifecycle

ao_core

Module lifecycle 

Source
Expand description

Background polling loop that keeps Session state in sync with reality.

Corresponds to packages/core/src/lifecycle-manager.ts in the reference repo, trimmed to what Slice 1 Phase C actually needs:

  1. Every poll_interval, list all non-terminal sessions from disk.
  2. For each one, probe Runtime::is_alive and Agent::detect_activity.
  3. Apply state transitions and persist the new Session atomically.
  4. Broadcast OrchestratorEvents so subscribers (CLI, reaction engine, notifiers, …) can react without polling themselves.

Design notes:

  • Trait objects, not generics. The manager owns Arc<dyn Runtime> etc. so the same LifecycleManager type can be used in tests (with mocks) and in the real CLI (with tmux/claude-code). Generic parameters would have leaked through every consumer.

  • Disk is the source of truth. The loop re-reads from SessionManager::list each tick rather than holding state in memory. This matches the Slice 1 design principle established in Phase A, and means ao-rs spawn running in a separate process is immediately visible on the next tick. (A future Slice 2+ may add an in-memory cache + file-watcher for efficiency.)

  • Per-session errors don’t stop the loop. If one session’s runtime probe fails, we emit TickError and continue. Only fatal SessionManager::list errors bubble up (and even then we log and keep looping).

  • Event channel lag. We use tokio::sync::broadcast, which drops old events when a slow subscriber can’t keep up. That’s fine for observability — a reaction engine that misses a tick just picks up the next one. Anyone needing lossless delivery should snapshot via SessionManager::list on startup and then subscribe.

Structs§

LifecycleHandle
Handle returned by LifecycleManager::spawn. Dropping it does not stop the loop — the caller must .stop().await explicitly, so a CLI handler that accidentally drops the handle doesn’t silently kill the background worker.
LifecycleManager

Constants§

DEFAULT_POLL_INTERVAL
Default poll interval. Increased from the TS reference’s 5 s to 10 s to further reduce GitHub API pressure now that batch enrichment + ETag guards handle the hot path.