Struct SessionHandle 

pub struct SessionHandle {
    pub events: Receiver<EngineEvent>,
    /* private fields */
}

Fields

events: Receiver<EngineEvent>

Implementations

impl SessionHandle

pub fn head(&self) -> Receiver<Arc<ProjectionHead>>

A read-only view of the actor’s published projection head (commit-protocol.md §Read invariant). Only a watch::Receiver is ever handed out: the Sender never leaves the actor, so this grants a reader, never a second publisher. Used by fork, which seeds a child session from this one’s history.

pub async fn prompt(&self, text: String)

pub async fn prompt_tagged(&self, text: String, synthetic: SyntheticReason)

A prompt whose committed user item carries a provenance tag (T2).

pub async fn steer(&self, text: String)

pub async fn rename(&self, name: String)

Name the session durably (a rename log entry; last one wins).

pub async fn set_mode(&self, mode: PermissionMode)

Set the session’s effective permission mode durably (a mode_set log entry; last one wins). Takes effect immediately: the running actor flips an atomic, it never reallocates Rules.

pub async fn set_todos(&self, items: Vec<Todo>)

Full-state replace of the todo checklist (a durable todos log entry). Exposed mainly for tests that pre-seed a list; the real entry point is the todo_write tool’s sink.

pub async fn continue_turn(&self)

Continue an interrupted turn on resume (M4/#8).

pub fn interrupt(&self)

Out-of-band interrupt of the in-flight turn (never queued behind data).

pub async fn drain_notifications(&self, grace: Duration)

Bounded wait for every detached Notification hook task still in flight (Finding 1’s notify fix): the one-shot CLI’s block_on drops its current_thread runtime the instant its driving future resolves, which would otherwise silently kill a hook task mid-subprocess. A one-shot exit path should call this (or, more commonly, SessionHandle::finish) before returning; the long-lived TUI/interactive path never needs to — its runtime stays alive on its own, so an in-flight notification finishes naturally.

pub async fn finish(self, grace: Duration)

The one-shot CLI’s exit-time helper (Finding 1, both halves): consumes the handle, first draining in-flight Notification hook tasks (bounded by grace), then dropping this handle’s strong command-channel sender and waiting — again bounded by grace — for the actor to fully shut down, which now runs its SessionEnd hook synchronously rather than as a detached task racing this same exit. Total worst case is 2 * grace, never unbounded: a hung hook can delay the process’s exit, but never wedge it.

Call this (not a bare drop(handle)) right before a one-shot CLI function returns. The long-lived TUI/interactive/hotl serve paths must NOT call this — their runtime stays alive on its own, so both the notification and session-end hooks get to run naturally without this explicit wait.