Skip to main content

session_core/
wake.rs

1//! Which lanes the host wakes when their work ends, and what follows from it. One rule for every mode: the root lane
2//! (`main`) is woken only when its composer says so (the native session's event dispatcher with completion events
3//! on, `ultron claude`'s wait-events hook); every other lane (subagents, other root conversations) and every root
4//! nothing wakes (`ULTRON_ASYNC_EVENTS=off`, an `ultron mcp` root without `--wake`, a Claude child) waits in its cell.
5//!
6//! - A woken lane's `rlm.collect` never waits ([`CollectMode::Host`]): the host waits between turns and each end
7//!   continues the run as a `child_done` event.
8//! - Any other lane's `rlm.collect` (and `rlm.merge`'s wait) blocks the cell until the children end
9//!   ([`CollectMode::InCell`]), cancelled with the cell and never parked: a parked cell is detached and its
10//!   `cell_done` would reach nobody.
11//!
12//! The cell hints, the detached-cell note and the runtime guide word each lane's waits to match.
13
14use delegation::host::CollectMode;
15use std::sync::Arc;
16use std::sync::atomic::{AtomicBool, Ordering};
17
18/// Whether the session's root lane is woken by the ends of its work; clones share it. Off until the composer turns it
19/// on.
20#[derive(Clone, Default)]
21pub struct RootWake(Arc<AtomicBool>);
22
23impl RootWake {
24    pub fn set(&self, woken: bool) {
25        self.0.store(woken, Ordering::SeqCst);
26    }
27
28    pub fn root_woken(&self) -> bool {
29        self.0.load(Ordering::SeqCst)
30    }
31
32    /// Whether the host wakes `lane` when its work ends: only the root lane, and only while the root is woken.
33    pub fn woken(&self, lane: &str) -> bool {
34        lane == session_journal::run::MAIN_LANE && self.root_woken()
35    }
36
37    /// How `lane`'s `rlm.collect` treats running children.
38    pub fn collect_mode(&self, lane: &str) -> CollectMode {
39        if self.woken(lane) {
40            CollectMode::Host
41        } else {
42            CollectMode::InCell
43        }
44    }
45}