docs(maestro): bare maestro opens the TUI

Turns each sidebar row into a card: name plus actions on line 1, an
adaptive meta line below carrying a colour-coded activity dot, the time
held in that state, any agent-reported detail, and the blocked-work or
exited markers that used to crowd the name row.

Renders the activity dimension the daemon already inferred and adds an
Error state fed by a Claude Code hook, which maestro installs globally
and addresses per session through MAESTRO_SESSION_ID / MAESTRO_URL.
Both clients implement one contract, docs/SIDEBAR.md.

Closes #101, #102, #103, #104, #105, #106, #107, #108, #110, #111, #112,
#113, #114, #115.

crates/maestro-daemon/src/session.rs

@@ -62,6 +62,11 @@ pub struct SessionRecord {
     /// resumes and [`Session::activity_detail`] is cleared with it. This
     /// field is daemon-local bookkeeping only — it never rides the wire.
     pub reported_activity: Option<crate::activity::ReportedActivity>,
+    /// Flipped once the natural-exit settle step (#82) has been applied or
+    /// refused for this session. `Dead` is observable before settling ends
+    /// (#115), so this is the observable that says its outcomes are safe to
+    /// assert on. Daemon-local bookkeeping; never rides the wire.
+    pub settled: bool,
 }
 
 #[derive(Debug, thiserror::Error)]
@@ -294,6 +299,17 @@ impl SessionManager {
         sessions.get(&id).map(|r| r.session.status)
     }
 
+    /// Whether the natural-exit settle step (#82) has finished for this
+    /// session: `Some(true)` once applied or refused, `Some(false)` while
+    /// still pending, `None` if the session is unknown. `Dead` is observable
+    /// before settling ends (#115), so anything asserting on a dead
+    /// session's worktree waits on this rather than inferring settle
+    /// completion from its side effects.
+    pub async fn is_settled(&self, id: Uuid) -> Option<bool> {
+        let sessions = self.inner.sessions.lock().await;
+        sessions.get(&id).map(|r| r.settled)
+    }
+
     /// Spawn a new session. On success returns the freshly-created `Session`.
     pub async fn create(&self, req: CreateSessionRequest) -> Result<Session, SessionError> {
         let (effective_cwd, worktree_path, worktree_base_repo) = match &req.worktree {
@@ -429,6 +445,7 @@ impl SessionManager {
                     worktree_branch: req.worktree.as_ref().map(|w| w.branch.clone()),
                     bridge,
                     reported_activity: None,
+                    settled: false,
                 },
             );
         }
@@ -657,6 +674,7 @@ impl SessionManager {
                     worktree_branch: None,
                     bridge,
                     reported_activity: None,
+                    settled: false,
                 },
             );
             let _ = self
@@ -1069,6 +1087,14 @@ async fn mark_session_dead(inner: &Arc<Inner>, id: Uuid) {
             }
         }
     }
+    // Settle has now been applied or refused either way (#115): from here on
+    // its outcomes are safe to observe.
+    {
+        let mut sessions = inner.sessions.lock().await;
+        if let Some(record) = sessions.get_mut(&id) {
+            record.settled = true;
+        }
+    }
 
     let _ = inner.sidecar.write(&session);
     let _ = inner.events.send(CatalogEvent::SessionUpdated { session });

crates/maestro-daemon/tests/activity.rs

@@ -189,8 +189,23 @@ fn a_foreground_pipeline_whose_leader_exited_is_still_awaiting_input() {
         "never observed a foreground group whose leader had exited"
     );
 
-    assert!(
-        awaiting_input(pane.pane_pid, &pane.tty, &ProcGroups::snapshot()),
-        "a surviving pipeline member still holds the tty"
-    );
+    // The leader can be gone while the surviving stage is still setting up:
+    // `true` exits as soon as both stages are forked, before the reader has
+    // opened the tty and parked. Poll for the answer, but only accept it
+    // while the state this test exists for still holds — otherwise a shell
+    // that regained the terminal would satisfy it vacuously.
+    let deadline = std::time::Instant::now() + Duration::from_secs(5);
+    let mut holds = false;
+    while std::time::Instant::now() < deadline {
+        let groups = ProcGroups::snapshot();
+        let still_leaderless = pgrp_and_tpgid(pane.pane_pid).is_some_and(|(pgrp, tpgid)| {
+            tpgid > 0 && tpgid != pgrp && pgrp_and_tpgid(tpgid).is_none()
+        });
+        if still_leaderless && awaiting_input(pane.pane_pid, &pane.tty, &groups) {
+            holds = true;
+            break;
+        }
+        std::thread::sleep(Duration::from_millis(20));
+    }
+    assert!(holds, "a surviving pipeline member still holds the tty");
 }

crates/maestro-daemon/tests/session_manager.rs

@@ -397,6 +397,12 @@ async fn watcher_refreshes_the_blocked_work_indicator() {
     init_bare_repo(origin.path());
     push_all_to_origin(repo.path(), origin.path());
 
+    // Subscribe before the watcher starts so every pass's emission is
+    // captured — otherwise the breakdown event can land between the
+    // snapshot observation below and the drain, and the quiet window
+    // would see it as an illegitimate re-emit.
+    let mut events = fx.manager.events();
+
     fx.manager.start_liveness_watcher_with_blocked_work(
         Duration::from_millis(50),
         Duration::from_millis(100),
@@ -418,14 +424,38 @@ async fn watcher_refreshes_the_blocked_work_indicator() {
     })
     .await;
 
-    // A steady state must not re-emit every tick (#83 change-detection).
-    let mut events = fx.manager.events();
+    // Consume through the emission that carried the breakdown (#83
+    // change-detection): the quiet window below must start after the last
+    // legitimate change, not race it into the channel.
+    loop {
+        match tokio::time::timeout(Duration::from_secs(5), events.recv()).await {
+            Ok(Ok(CatalogEvent::SessionUpdated { session }))
+                if matches!(
+                    &session.blocked_work,
+                    Some(b) if b.uncommitted_files >= 1 && b.untracked_files >= 1
+                ) =>
+            {
+                break;
+            }
+            Ok(Ok(_)) => continue,
+            _ => panic!("never saw the SessionUpdated carrying the breakdown"),
+        }
+    }
     while events.try_recv().is_ok() {}
     tokio::time::sleep(Duration::from_millis(400)).await;
-    assert!(
-        !matches!(events.try_recv(), Ok(CatalogEvent::SessionUpdated { .. })),
-        "an unchanged worktree must not re-emit SessionUpdated"
-    );
+    // Only a *changed* indicator counts as a re-emit (#83 change-detection).
+    // The activity pass may still legitimately announce e.g. Active→Idle
+    // (its debounce is time-based, not worktree-based), and its payload
+    // carries today's blocked_work unchanged.
+    while let Ok(CatalogEvent::SessionUpdated { session }) = events.try_recv() {
+        assert!(
+            matches!(
+                &session.blocked_work,
+                Some(b) if b.uncommitted_files >= 1 && b.untracked_files >= 1
+            ),
+            "an unchanged worktree must not re-emit a changed indicator"
+        );
+    }
 }
 
 /// Cleanup on kill is unconditional once the guard passes (#79): even a spec
@@ -848,6 +878,17 @@ async fn natural_exit_of_a_pristine_worktree_removes_it() {
     })
     .await;
 
+    // (`Dead` is observable a moment before the settle step removes the tree.)
+    wait_for_async(Duration::from_secs(3), || async {
+        !wt_path.exists()
+            && fx
+                .retained_store()
+                .load_all()
+                .map(|all| all.is_empty())
+                .unwrap_or(false)
+    })
+    .await;
+
     assert!(
         !wt_path.exists(),
         "a pristine worktree leaves nothing behind"
@@ -905,6 +946,14 @@ async fn natural_exit_without_a_retained_store_destroys_nothing() {
     })
     .await;
 
+    // The settle step has been applied or refused either way — here refused,
+    // since there is no store to record the tree into. Only from this point
+    // is "the tree survived" a settled fact rather than a race (#115).
+    wait_for_async(Duration::from_secs(3), || async {
+        manager.is_settled(s.id).await == Some(true)
+    })
+    .await;
+
     assert!(
         wt_path.exists(),
         "nothing may be destroyed when it cannot be recorded"

crates/maestro/src/main.rs

@@ -19,8 +19,7 @@ use tracing_subscriber::EnvFilter;
 #[command(
     name = "maestro",
     version,
-    about = "Unified CLI / daemon / TUI for the Maestro terminal-session orchestrator",
-    arg_required_else_help = true
+    about = "Unified CLI / daemon / TUI for the Maestro terminal-session orchestrator"
 )]
 struct Cli {
     /// Override the daemon HTTP base clients talk to (e.g.
@@ -37,8 +36,11 @@ struct Cli {
     #[arg(short, long, global = true, action = clap::ArgAction::Count)]
     verbose: u8,
 
+    /// A missing subcommand defaults to the TUI (#119): a bare `maestro` opens
+    /// the terminal UI. Builds without the `tui` feature have no UI surface,
+    /// so they print help and exit 0 instead.
     #[command(subcommand)]
-    command: Command,
+    command: Option<Command>,
 }
 
 #[derive(Debug, Subcommand)]
@@ -89,7 +91,22 @@ fn main() -> ExitCode {
 }
 
 async fn dispatch(cli: Cli) -> Result<(), Box<dyn std::error::Error>> {
-    match cli.command {
+    let command = match cli.command {
+        Some(command) => command,
+        None => {
+            #[cfg(feature = "tui")]
+            {
+                Command::Tui(maestro_tui::cli::TuiArgs { daemon_url: None })
+            }
+            #[cfg(not(feature = "tui"))]
+            {
+                use clap::CommandFactory;
+                let _ = <Cli as CommandFactory>::command().print_help();
+                return Ok(());
+            }
+        }
+    };
+    match command {
         #[cfg(feature = "cli")]
         Command::List(args) => {
             maestro_cli::dispatch(
@@ -166,19 +183,19 @@ fn init_tracing(cli: &Cli) {
 }
 
 #[cfg(feature = "cli")]
-fn is_cli_subcommand(command: &Command) -> bool {
+fn is_cli_subcommand(command: &Option<Command>) -> bool {
     matches!(
         command,
-        Command::List(_)
-            | Command::Spawn(_)
-            | Command::Attach(_)
-            | Command::Kill(_)
-            | Command::Hooks(_)
+        Some(Command::List(_))
+            | Some(Command::Spawn(_))
+            | Some(Command::Attach(_))
+            | Some(Command::Kill(_))
+            | Some(Command::Hooks(_))
     )
 }
 
 #[cfg(not(feature = "cli"))]
-fn is_cli_subcommand(_command: &Command) -> bool {
+fn is_cli_subcommand(_command: &Option<Command>) -> bool {
     false
 }
 
@@ -216,12 +233,20 @@ mod tests {
     }
 
     /// Parse argv the way `main` does, returning just the dispatched subcommand.
-    fn command_of(argv: &[&str]) -> Command {
+    fn command_of(argv: &[&str]) -> Option<Command> {
         Cli::try_parse_from(argv)
             .unwrap_or_else(|e| panic!("parse {argv:?}: {e}"))
             .command
     }
 
+    #[test]
+    fn bare_invocation_parses_to_no_subcommand() {
+        // The TUI-vs-help default is applied in `dispatch`; parsing must not
+        // reject an empty argv.
+        assert!(command_of(&["maestro"]).is_none());
+        assert!(command_of(&["maestro", "--verbose"]).is_none());
+    }
+
     #[cfg(feature = "cli")]
     #[test]
     fn cli_subcommands_are_classified_as_cli() {

crates/maestro/tests/cli.rs

@@ -54,11 +54,35 @@ fn version_flag_succeeds() {
     assert!(text.contains("maestro"), "--version output: {text}");
 }
 
+/// A bare `maestro` must never fall back to help on a build that has a TUI:
+/// the missing subcommand defaults to `tui` (#119). Point at a port with
+/// nothing listening so the TUI's health probe fails fast instead of blocking
+/// on a terminal.
+#[cfg(feature = "tui")]
 #[test]
-fn no_args_prints_help_and_fails() {
-    // `arg_required_else_help = true` => exit non-zero but show usage.
+fn bare_invocation_dispatches_to_the_tui() {
+    let (ok, text) = run(&["--daemon-url", "http://127.0.0.1:9"]);
+    assert!(
+        !ok,
+        "TUI against a dead daemon should exit non-zero:\n{text}"
+    );
+    assert!(
+        text.contains("daemon unreachable"),
+        "bare invocation should have run the TUI's daemon probe:\n{text}"
+    );
+    assert!(
+        !text.contains("Usage"),
+        "bare invocation must not print help when a TUI exists:\n{text}"
+    );
+}
+
+/// Builds without the `tui` feature keep the historical behaviour: no args =>
+/// help, exit 0 (#119).
+#[cfg(not(feature = "tui"))]
+#[test]
+fn bare_invocation_prints_help_and_exits_zero() {
     let (ok, text) = run(&[]);
-    assert!(!ok, "bare invocation should fail:\n{text}");
+    assert!(ok, "bare invocation should exit 0:\n{text}");
     assert!(text.contains("Usage"), "expected usage text:\n{text}");
 }
 

docs/INSTALL.md

@@ -119,6 +119,9 @@ The wizard always installs the default-feature build.
 
 `maestro tui` is the keyboard-and-mouse driven terminal UI client. It ships
 in the default feature set, so a vanilla `cargo install maestro` builds it.
+A bare `maestro` opens the TUI too — the missing subcommand defaults to `tui`
+(#119), so `maestro --daemon-url http://host:7070` works as well. Builds
+without the `tui` feature have no UI to open and print help instead (exit 0).
 Drop the `tui` feature to skip it on hosts that don't need the UI surface
 (`--no-default-features --features cli,daemon`).