twitchyliquid64 · Jun 29, 2026 · Jun 29, 2026
@@ -0,0 +1,57 @@
+//! Scoped progress rendering onto an SSH channel.
+//!
+//! [`ChannelProgress`] is the `russh`-concrete wrapper around
+//! [`ot::render_operations_while`]: it consumes an SSH [`Channel`], an
+//! [`OpTracker`], and a future, paints the tracker's live operation tree onto
+//! the channel as indicatif progress bars while the future runs, and hands the
+//! channel back (with the future's output) once it resolves.
+//!
+//! The renderer takes **exclusive** use of the channel for the future's
+//! duration — the wrapped operation must not also write to it. This is the
+//! "compute under a progress bar, then print the result" model; live output
+//! interleaved with progress is out of scope (see
+//! `docs/specs/04-spec-ot-render-decoupling`).
+
+use std::future::Future;
+
+use ot::OpTracker;
+use russh::Channel;
+use russh::server::Msg;
+
+/// Renders an [`OpTracker`] onto an SSH channel for the lifetime of a future.
+///
+/// Construct with [`ChannelProgress::new`], then drive a future with
+/// [`run`](ChannelProgress::run); the channel is returned alongside the
+/// future's output so the caller can resume writing to it.
+pub struct ChannelProgress {
+    channel: Channel<Msg>,
+    tracker: OpTracker,
+    /// Terminal dimensions `(cols, rows)` indicatif lays bars out against —
+    /// from the session's PTY size.
+    size: (u16, u16),
+}
+
+impl ChannelProgress {
+    /// Creates a renderer that will paint `tracker` onto `channel`, sized for a
+    /// `(cols, rows)` terminal.
+    #[must_use]
+    pub fn new(channel: Channel<Msg>, tracker: OpTracker, size: (u16, u16)) -> Self {
+        Self {
+            channel,
+            tracker,
+            size,
+        }
+    }
+
+    /// Renders progress onto the channel while `fut` runs, returning the channel
+    /// and the future's output once it resolves.
+    ///
+    /// The channel is borrowed (via an independent writer) during rendering and
+    /// returned intact — the writer only ever writes data frames, never an EOF,
+    /// so the caller can keep using the channel afterwards.
+    pub async fn run<F: Future>(self, fut: F) -> (Channel<Msg>, F::Output) {
+        let writer = self.channel.make_writer();
+        let out = ot::render_operations_while(&self.tracker, writer, self.size, fut).await;
+        (self.channel, out)
+    }
+}
@@ -1,5 +1,6 @@
 use std::collections::BTreeMap;
 
+pub mod channel_progress;
 pub mod connection;
 pub mod env;
 mod exec;

@@ -1,8 +1,10 @@
+use crate::channel_progress::ChannelProgress;
 use crate::{
     ChannelConfig,
     session_host::{self, HostAttrs, WinSize},
 };
 use mctx::ConfigBuilder;
+use ot::OpTracker;
 use paths::DaemonAbsPath;
 use russh::{Channel, server::Msg};
 use sessions::{Record, store::SessionObject};
@@ -92,6 +94,12 @@ pub struct Session<S: SessionObject> {
         session_host::HostHandle,
         JoinHandle<Result<i32, std::io::Error>>,
     )>,
+
+    /// The root of this session's operation tree. Created once for the session
+    /// and wired into the context each launch builds against, so package
+    /// fetches/builds report into it; the channel renderer paints it onto the
+    /// SSH channel while a host is being minted.
+    tracker: OpTracker,
 }
 
 impl<S: SessionObject> Session<S> {
@@ -114,6 +122,7 @@ impl<S: SessionObject> Session<S> {
             minimal_state_dir,
             minimal_cache_dir,
             net_switch,
+            tracker: OpTracker::new_root(),
         };
 
         tokio::spawn(mngr.mainloop());
@@ -231,17 +240,34 @@ impl<S: SessionObject> Session<S> {
             }
         };
 
+        // The launcher's context reports into this session's operation tree (see
+        // `context`). Render that tree onto the channel for the duration of the
+        // launch (graph build + package builds + sandbox assembly), then take
+        // the channel back. The host is spawned without a channel so the
+        // renderer has exclusive use of it while building; once the bars are
+        // cleared we attach the channel to the now-running host.
         let launcher = self.session_launcher(session_hnd)?;
-        let h = Box::pin(session_host::Host::spawn(
-            launcher,
-            name,
-            conn_username,
-            self.paths(),
-            sz,
-            Some(channel),
-        ))
-        .await
-        .map_err(AttachError::SpawnFailed)?;
+        let progress = ChannelProgress::new(channel, self.tracker.clone(), (sz.cols, sz.rows));
+        let (channel, spawned) = progress
+            .run(Box::pin(session_host::Host::spawn(
+                launcher,
+                name,
+                conn_username,
+                self.paths(),
+                sz,
+                None,
+            )))
+            .await;
+        let h = spawned.map_err(AttachError::SpawnFailed)?;
+
+        // Wire the channel to the freshly launched host. A failure here means
+        // the host died in the window between launch and attach; surface it as
+        // a spawn failure rather than leaving a dead, channel-less host.
+        h.0.attach(channel, sz).await.map_err(|_| {
+            AttachError::SpawnFailed(std::io::Error::other(
+                "session host exited before its channel could attach",
+            ))
+        })?;
         self.host = Some(h);
         Ok(())
     }
@@ -296,6 +322,11 @@ impl<S: SessionObject> Session<S> {
             .with_repo_dir(wsp.as_utf8_path())
             .with_cache_dir(self.minimal_cache_dir.as_utf8_path())
             .with_state_dir(self.minimal_state_dir.as_utf8_path())
+            // Every context this session builds reports into its operation tree.
+            // The host-mint path renders that tree onto the SSH channel; the
+            // task-exec path (via `MakeContext`) also feeds it, so task builds
+            // surface on the same tracker even though only a mint renders it.
+            .with_operation_tracker(self.tracker.clone())
             .build()
         {
             Err(e) => Err(mctx::Error::from(e).to_string()),

@@ -8,13 +8,18 @@ publish.workspace = true
 
 [features]
 default = ["indicatif"]
-# The indicatif renderer (legacy single-terminal CLI path). Disable to build the
-# pure operation-tracking core with no rendering dependency.
-indicatif = ["dep:indicatif", "tokio/rt"]
+# The indicatif renderer (legacy single-terminal CLI path) and the scoped
+# per-sink renderer. Disable to build the pure operation-tracking core with no
+# rendering dependency.
+indicatif = ["dep:indicatif", "tokio/rt", "tokio/macros", "tokio/io-util"]
 
 [dependencies]
 indicatif = { workspace = true, optional = true }
 tokio = { workspace = true, features = ["sync"] }
 
+# `rt-multi-thread` is test-only: `render_operations_while`'s integration test
+# runs on a `#[tokio::test(flavor = "multi_thread")]` runtime so its pump task
+# drains concurrently with the driven future. Production code needs only `rt`
+# (see the `indicatif` feature), so this stays out of the production deps.
 [dev-dependencies]
-tokio = { workspace = true, features = ["macros", "rt", "time"] }
+tokio = { workspace = true, features = ["macros", "rt", "rt-multi-thread", "time"] }