ci(maestro): cancel superseded runs

Pushes queued a new run without stopping the old one. Group by ref and
cancel in-progress, except on main where runs finish.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.gitea/workflows/ci.yml

@@ -7,6 +7,10 @@ on:
       - 'linear/**'
   pull_request:
 
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
 jobs:
   rust:
     runs-on: ubuntu-latest
@@ -52,3 +56,79 @@ jobs:
 
       - name: test
         run: cargo test --all
+
+      # NAP-271: the umbrella `maestro` binary is feature-gated (cli / daemon /
+      # tui). Verify each subset compiles and its tests pass on its own, and
+      # that building with no features at all is rejected.
+      - name: feature-gate matrix
+        run: |
+          set -euo pipefail
+          for f in cli daemon tui; do
+            echo "::group::maestro --no-default-features --features $f"
+            cargo build -p maestro --no-default-features --features "$f"
+            cargo test  -p maestro --no-default-features --features "$f"
+            echo "::endgroup::"
+          done
+          echo "::group::maestro with no features must fail to compile"
+          if cargo build -p maestro --no-default-features 2>/dev/null; then
+            echo "expected build with no features to fail, but it succeeded" >&2
+            exit 1
+          fi
+          echo "::endgroup::"
+
+  web:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Node.js + pnpm
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends curl ca-certificates
+          curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+          apt-get install -y --no-install-recommends nodejs
+          corepack enable
+          corepack prepare pnpm@9.15.4 --activate
+
+      - name: Install deps
+        run: pnpm -C web install --frozen-lockfile
+
+      - name: typecheck
+        run: pnpm -C web typecheck
+
+      - name: test
+        run: pnpm -C web test
+
+      - name: build
+        run: pnpm -C web build
+
+  # The flake pins pnpmDeps.hash against web/pnpm-lock.yaml (#98). A lockfile
+  # change invalidates the pin silently elsewhere, so the packaged build has to
+  # fail here too.
+  flake:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # The runner container is root with no `nixbld` group, but the installer
+      # writes `build-users-group = nixbld` anyway and then fails on it, so the
+      # config goes in first. Flakes are off by default and `nix build .#…`
+      # needs them. Written again afterwards in case the installer replaced it.
+      - name: Install nix
+        run: |
+          mkdir -p /etc/nix
+          printf 'build-users-group =\nexperimental-features = nix-command flakes\n' > /etc/nix/nix.conf
+          curl -fsSL https://nixos.org/nix/install | sh -s -- --no-daemon --yes
+          printf 'build-users-group =\nexperimental-features = nix-command flakes\n' > /etc/nix/nix.conf
+          echo "$HOME/.nix-profile/bin" >> "$GITHUB_PATH"
+
+      # The installer does not enable flakes, so `nix build .#…` needs the
+      # features passed explicitly — a local machine that has them in
+      # nix.conf will build fine while CI fails without this.
+      - name: build flake packages
+        run: |
+          nix --extra-experimental-features "nix-command flakes" build \
+            .#webFrontend \
+            .#maestro \
+            .#maestro-web \
+            --no-link

.gitignore

@@ -9,3 +9,9 @@ worktrees/
 # nix build output symlinks
 /result
 /result-*
+
+# direnv (`use flake`)
+/.direnv/
+
+# `nix run .#dev` scratch state (tmux socket)
+/.dev/

CLAUDE.md

@@ -56,12 +56,27 @@ crates/
 ├── maestro-installer/   # `maestro-install` wizard: cargo install + systemd (NAP-225)
 └── maestro-e2e/         # cross-process integration tests (NAP-217)
 web/                     # browser SPA (NAP-218)
-flake.nix                # Nix flake: `maestro`, `maestro-web`, `webFrontend`
+flake.nix                # Nix flake: packages, checks, dev shell, `nix run .#dev`
 nix/                     # Home Manager module (`services.maestro`)
 ```
 
 See `docs/INSTALL.md` for end-user install instructions.
 
+`docs/WORKTREES.md` is the contract for session worktrees — placement,
+collisions, what blocks a kill, and what `--force` leaves behind. Read it
+before changing anything that creates or removes one.
+
+`docs/SIDEBAR.md` is the contract for session cards in the web and TUI
+sidebars — line layout, activity colours, duration format, state precedence.
+Read it before changing sidebar rendering.
+
+`nix run .#dev` (or `just dev`) brings up the whole local stack under
+process-compose: a debug daemon on 127.0.0.1:7071, then Vite on :5173 once the
+daemon answers `/api/info`. The SPA proxies `/api/*` back to the daemon, so only
+the UI is exposed on the network. The dev port is deliberately not the daemon's
+own default 7070 (`devDaemonPort` in `flake.nix`), so the stack never fights a
+real daemon on the same host.
+
 ## Conventions
 
 - **TDD by default.** Failing test first, then minimal impl. Commit test + impl together.

Cargo.lock

@@ -1065,10 +1065,10 @@ dependencies = [
  "futures-util",
  "libc",
  "maestro-config",
+ "maestro-hooks",
  "maestro-protocol",
+ "maestro-testing",
  "nix",
- "reqwest",
- "serde",
  "serde_json",
  "tempfile",
  "thiserror 1.0.69",
@@ -1085,6 +1085,7 @@ name = "maestro-config"
 version = "0.1.0"
 dependencies = [
  "dirs",
+ "maestro-protocol",
  "serde",
  "tempfile",
  "thiserror 1.0.69",
@@ -1102,6 +1103,8 @@ dependencies = [
  "futures-util",
  "libc",
  "maestro-config",
+ "maestro-hooks",
+ "maestro-names",
  "maestro-protocol",
  "reqwest",
  "serde",
@@ -1123,8 +1126,8 @@ dependencies = [
  "chrono",
  "futures-util",
  "maestro-protocol",
+ "maestro-testing",
  "maestro-tui",
- "reqwest",
  "serde",
  "serde_json",
  "tempfile",
@@ -1136,6 +1139,15 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "maestro-hooks"
+version = "0.1.0"
+dependencies = [
+ "serde_json",
+ "tempfile",
+ "thiserror 1.0.69",
+]
+
 [[package]]
 name = "maestro-installer"
 version = "0.1.0"
@@ -1146,13 +1158,36 @@ dependencies = [
  "thiserror 1.0.69",
 ]
 
+[[package]]
+name = "maestro-names"
+version = "0.1.0"
+dependencies = [
+ "rand 0.8.6",
+]
+
 [[package]]
 name = "maestro-protocol"
 version = "0.1.0"
 dependencies = [
  "chrono",
+ "reqwest",
  "serde",
  "serde_json",
+ "thiserror 1.0.69",
+ "uuid",
+]
+
+[[package]]
+name = "maestro-testing"
+version = "0.1.0"
+dependencies = [
+ "axum",
+ "chrono",
+ "futures-util",
+ "maestro-protocol",
+ "serde",
+ "serde_json",
+ "tokio",
  "uuid",
 ]
 
@@ -1167,6 +1202,7 @@ dependencies = [
  "futures-util",
  "maestro-config",
  "maestro-protocol",
+ "maestro-testing",
  "ratatui",
  "reqwest",
  "serde_json",
@@ -1189,6 +1225,8 @@ dependencies = [
  "futures-util",
  "include_dir",
  "maestro-config",
+ "maestro-protocol",
+ "maestro-testing",
  "mime_guess",
  "reqwest",
  "serde_json",
@@ -1198,6 +1236,7 @@ dependencies = [
  "tokio-tungstenite 0.21.0",
  "tracing",
  "tracing-subscriber",
+ "uuid",
 ]
 
 [[package]]

Cargo.toml

@@ -18,7 +18,10 @@ dirs = "5"
 futures-util = { version = "0.3", default-features = false, features = ["sink", "std"] }
 libc = "0.2"
 maestro-config = { path = "crates/maestro-config" }
+maestro-hooks = { path = "crates/maestro-hooks" }
+maestro-names = { path = "crates/maestro-names" }
 maestro-protocol = { path = "crates/maestro-protocol" }
+maestro-testing = { path = "crates/maestro-testing" }
 maestro-tui = { path = "crates/maestro-tui" }
 nix = { version = "0.29", default-features = false, features = ["term", "signal"] }
 rand = "0.8"

DESIGN.md

@@ -79,16 +79,15 @@ no bounce. Tokens `--dur-fast`/`--dur`/`--dur-slow`.
   `connecting` state pill pulses.
 - Interaction: row hover/focus, button press (1px), input focus ring, chevron
   rotation, theme-toggle sun/moon swap.
-- Modal: bottom-sheet slide-up on mobile, scale-pop on ≥600px.
 - Every animation has a `prefers-reduced-motion: reduce` path (pulses off,
   transitions near-instant).
 
 ## Layout & structure
 
 Mobile-first, structural responsiveness (not fluid type). Single `≤520px`
-breakpoint stacks the header (full-width search, wrapped actions). `≥600px`
-switches the spawn modal from bottom-sheet to centered dialog. A faint slate grid texture sits on `--bg` as
-terminal atmosphere (very low contrast, not decoration).
+breakpoint stacks the header (full-width search, wrapped actions). A faint
+slate grid texture sits on `--bg` as terminal atmosphere (very low contrast,
+not decoration).
 
 ## Components
 
@@ -101,8 +100,10 @@ Three surfaces, all DOM built in TS, styled by class:
   no-sessions, no-search-match.
 - **Attach** — header (back, `session <id>`, live/closed/error state pill) over
   a framed dark xterm with a green cursor.
-- **Spawn modal** — bottom-sheet/dialog form; mono inputs with green focus
-  ring; grouped worktree fieldset.
+- **Draft pane** — the spawn form mounted inline in an empty split pane,
+  focusable like any session pane; mono inputs with green focus ring; grouped
+  worktree fieldset. Spawn opens one (reusing an empty focused pane, else
+  splitting), and "Spawn similar" seeds one from a session's dir + command.
 
 Interactive elements ship default / hover / focus-visible / active / disabled
 states; the accent green is used only for action, selection, focus, and live
@@ -111,5 +112,5 @@ status — never decoration.
 ## Dev review aids (DEV-only, stripped from production)
 
 `web/src/mock.ts` + query params seed a representative catalog without a running
-daemon: `?mock` (seed sessions), `?mock&spawn` (open the spawn modal),
+daemon: `?mock` (seed sessions), `?mock&spawn` (open a draft pane),
 `?theme=light|dark` (pin a theme). Guarded by `import.meta.env.DEV`.

Justfile

@@ -1,5 +1,10 @@
 # Common dev / build entry points. Run `just` with no args to list.
 
+# Run the full local stack — daemon on 127.0.0.1:7071 plus Vite on :5173,
+# ordered and health-gated by process-compose. Ctrl-C stops everything.
+dev:
+    nix run .#dev
+
 # Build the maestro-web binary together with the SPA bundle it embeds.
 web:
     pnpm -C web install --frozen-lockfile

crates/maestro-cli/Cargo.toml

@@ -17,10 +17,9 @@ dirs.workspace = true
 futures-util.workspace = true
 libc.workspace = true
 maestro-config.workspace = true
-maestro-protocol.workspace = true
+maestro-hooks.workspace = true
+maestro-protocol = { workspace = true, features = ["client"] }
 nix.workspace = true
-reqwest.workspace = true
-serde.workspace = true
 serde_json.workspace = true
 thiserror.workspace = true
 tokio = { workspace = true, features = ["macros", "rt", "sync", "time", "io-util", "io-std", "signal"] }
@@ -31,4 +30,7 @@ tracing-subscriber.workspace = true
 uuid.workspace = true
 
 [dev-dependencies]
+maestro-testing.workspace = true
 tempfile.workspace = true
+tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
+uuid.workspace = true

crates/maestro-cli/src/attach.rs

@@ -13,7 +13,6 @@ use maestro_protocol::ClientControl;
 use nix::sys::termios::{cfmakeraw, tcgetattr, tcsetattr, SetArg, Termios};
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
 use tokio_tungstenite::tungstenite::Message;
-use uuid::Uuid;
 
 #[derive(Debug, thiserror::Error)]
 #[allow(clippy::result_large_err)]
@@ -24,8 +23,8 @@ pub enum AttachError {
     Io(#[from] io::Error),
     #[error("termios: {0}")]
     Termios(#[from] nix::Error),
-    #[error("invalid daemon_url: {0}")]
-    InvalidDaemonUrl(String),
+    #[error(transparent)]
+    Url(#[from] maestro_protocol::routes::UrlError),
     #[error("invalid detach key: {0}")]
     InvalidDetachKey(String),
     #[error("stdin must be a TTY for attach")]
@@ -63,26 +62,6 @@ pub fn parse_detach_key(spec: &str) -> Result<u8, AttachError> {
     }
 }
 
-/// Build the attach WS URL from the daemon's HTTP base.
-///
-/// The endpoint (`WS /api/attach/:id`) lives on the daemon's `bind_addr`, so we
-/// take the HTTP base (`http://127.0.0.1:7070`), swap the scheme to its WS
-/// equivalent, and append the route.
-#[allow(clippy::result_large_err)]
-pub fn attach_url(daemon_http_base: &str, session_id: Uuid) -> Result<String, AttachError> {
-    let base = daemon_http_base.trim_end_matches('/');
-    let ws_base = if let Some(rest) = base.strip_prefix("https://") {
-        format!("wss://{rest}")
-    } else if let Some(rest) = base.strip_prefix("http://") {
-        format!("ws://{rest}")
-    } else if base.starts_with("ws://") || base.starts_with("wss://") {
-        base.to_string()
-    } else {
-        return Err(AttachError::InvalidDaemonUrl(daemon_http_base.to_string()));
-    };
-    Ok(format!("{ws_base}/api/attach/{session_id}"))
-}
-
 /// RAII guard that puts the terminal into raw mode and restores on drop.
 #[derive(Debug)]
 struct RawTty {
@@ -234,7 +213,6 @@ pub async fn run_attach_url(url: &str, detach_byte: u8) -> Result<(), AttachErro
 #[cfg(test)]
 mod tests {
     use super::*;
-    use uuid::Uuid;
 
     #[test]
     fn parse_detach_key_handles_caret_form() {
@@ -255,30 +233,4 @@ mod tests {
             Err(AttachError::InvalidDetachKey(_))
         ));
     }
-
-    #[test]
-    fn attach_url_swaps_scheme_and_appends_route() {
-        let id = Uuid::from_u128(0xabcd);
-        assert_eq!(
-            attach_url("http://127.0.0.1:7070", id).unwrap(),
-            format!("ws://127.0.0.1:7070/api/attach/{id}")
-        );
-        assert_eq!(
-            attach_url("https://laptop.lan:7070/", id).unwrap(),
-            format!("wss://laptop.lan:7070/api/attach/{id}")
-        );
-        // already-ws bases pass through
-        assert_eq!(
-            attach_url("ws://10.0.0.1:7070", id).unwrap(),
-            format!("ws://10.0.0.1:7070/api/attach/{id}")
-        );
-    }
-
-    #[test]
-    fn attach_url_rejects_unknown_scheme() {
-        assert!(matches!(
-            attach_url("ftp://x", Uuid::nil()),
-            Err(AttachError::InvalidDaemonUrl(_))
-        ));
-    }
 }

crates/maestro-cli/src/cli.rs

@@ -41,6 +41,23 @@ pub enum Command {
     Attach(AttachArgs),
     /// Kill a session by ID.
     Kill(KillArgs),
+    /// Install or update the agent activity hook (#106).
+    Hooks(HooksArgs),
+}
+
+/// `maestro hooks <install>`
+#[derive(Debug, clap::Args)]
+pub struct HooksArgs {
+    #[command(subcommand)]
+    pub command: HooksCommand,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum HooksCommand {
+    /// Write the Claude Code activity hook into ~/.claude/settings.json.
+    /// Idempotent: an older maestro hook is updated in place, every other
+    /// hook is left untouched.
+    Install,
 }
 
 #[derive(Debug, clap::Args)]
@@ -67,9 +84,11 @@ pub struct SpawnArgs {
     /// Branch name for the worktree (required with --worktree-from).
     #[arg(long)]
     pub branch: Option<String>,
-    /// Remove the worktree when the session is killed.
+    /// Check out an existing branch instead of creating one. Without it the
+    /// daemon runs `worktree add -b`, which fails if the branch is already
+    /// there.
     #[arg(long)]
-    pub cleanup_on_kill: bool,
+    pub existing_branch: bool,
     /// After spawning, attach immediately.
     #[arg(long, short = 'a')]
     pub attach: bool,
@@ -88,6 +107,10 @@ pub struct AttachArgs {
 pub struct KillArgs {
     /// Session ID to kill.
     pub session_id: Uuid,
+    /// End the session even when its worktree holds unsaved work (#81). The
+    /// worktree is left on disk — never removed.
+    #[arg(long)]
+    pub force: bool,
 }
 
 fn parse_kv(s: &str) -> Result<(String, String), String> {
@@ -126,7 +149,6 @@ mod tests {
             "/repos/foo",
             "--branch",
             "feat/x",
-            "--cleanup-on-kill",
             "-e",
             "FOO=bar",
             "-e",
@@ -137,7 +159,6 @@ mod tests {
             Command::Spawn(a) => {
                 assert_eq!(a.command, "bash");
                 assert_eq!(a.branch.as_deref(), Some("feat/x"));
-                assert!(a.cleanup_on_kill);
                 assert_eq!(
                     a.env,
                     vec![("FOO".into(), "bar".into()), ("BAZ".into(), "qux".into()),]
@@ -147,6 +168,31 @@ mod tests {
         }
     }
 
+    /// Review fix: without a flag the CLI always sent `create_branch: true`,
+    /// so the daemon's existing-branch path was unreachable and spawning onto
+    /// a branch that already existed just failed.
+    #[test]
+    fn parses_spawn_onto_an_existing_branch() {
+        let cli = Cli::try_parse_from([
+            "maestro",
+            "spawn",
+            "--cwd",
+            "/tmp",
+            "--command",
+            "bash",
+            "--worktree-from",
+            "/repo",
+            "--branch",
+            "feat/existing",
+            "--existing-branch",
+        ])
+        .unwrap();
+        let Command::Spawn(a) = cli.command else {
+            panic!("expected spawn")
+        };
+        assert!(a.existing_branch);
+    }
+
     #[test]
     fn spawn_worktree_requires_branch() {
         let err = Cli::try_parse_from([
@@ -173,6 +219,32 @@ mod tests {
         }
     }
 
+    #[test]
+    fn parses_kill_with_force() {
+        let id = "01234567-89ab-cdef-0123-456789abcdef";
+        let cli = Cli::try_parse_from(["maestro", "kill", "--force", id]).unwrap();
+        match cli.command {
+            Command::Kill(a) => {
+                assert!(a.force);
+                assert_eq!(a.session_id.to_string(), id);
+            }
+            _ => panic!("wrong subcommand"),
+        }
+    }
+
+    #[test]
+    fn kill_force_defaults_false() {
+        let id = "01234567-89ab-cdef-0123-456789abcdef";
+        let cli = Cli::try_parse_from(["maestro", "kill", id]).unwrap();
+        match cli.command {
+            Command::Kill(a) => {
+                assert!(!a.force);
+                assert_eq!(a.session_id.to_string(), id);
+            }
+            _ => panic!("wrong subcommand"),
+        }
+    }
+
     #[test]
     fn rejects_env_without_equals() {
         let err = Cli::try_parse_from([
@@ -188,4 +260,21 @@ mod tests {
         .unwrap_err();
         assert!(err.to_string().contains("KEY=VALUE"));
     }
+
+    #[test]
+    fn parses_hooks_install() {
+        let cli = Cli::try_parse_from(["maestro", "hooks", "install"]).unwrap();
+        match cli.command {
+            Command::Hooks(h) => {
+                assert!(matches!(h.command, HooksCommand::Install));
+            }
+            _ => panic!("wrong subcommand"),
+        }
+        // No subcommand → help.
+        let err = Cli::try_parse_from(["maestro", "hooks"]).unwrap_err();
+        assert!(matches!(
+            err.kind(),
+            clap::error::ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
+        ));
+    }
 }

crates/maestro-cli/src/config.rs

@@ -1,128 +0,0 @@
-//! CLI view over the unified Maestro config at `~/.config/maestro/config.toml`.
-//!
-//! Reads `[cli].daemon_url` and, as a fallback, `[daemon].bind_addr`.
-
-use std::net::SocketAddr;
-use std::path::{Path, PathBuf};
-
-use maestro_config::MaestroConfigFile;
-
-pub use maestro_config::CONFIG_PATH_ENV;
-
-/// Last-resort daemon HTTP base when neither config nor a local
-/// `[daemon].bind_addr` tells us otherwise. Matches the daemon's default
-/// `bind_addr`.
-pub const DEFAULT_DAEMON_URL: &str = "http://127.0.0.1:7070";
-
-/// `~/.config/maestro/config.toml` (XDG-aware).
-pub fn default_config_path() -> Result<PathBuf, ConfigError> {
-    Ok(maestro_config::default_config_path()?)
-}
-
-/// `$MAESTRO_CONFIG` if set, else [`default_config_path`].
-pub fn resolve_config_path() -> Result<PathBuf, ConfigError> {
-    Ok(maestro_config::resolve_config_path()?)
-}
-
-#[derive(Debug, thiserror::Error)]
-pub enum ConfigError {
-    #[error(transparent)]
-    Inner(#[from] maestro_config::ConfigError),
-}
-
-/// Resolved CLI config — the subset of the unified file that this binary
-/// actually consumes.
-#[derive(Debug, Clone, Default, PartialEq, Eq)]
-pub struct CliConfig {
-    /// `[cli].daemon_url` — explicit daemon HTTP base.
-    pub daemon_url: Option<String>,
-    /// `[daemon].bind_addr` if a daemon is configured on this host. Used to
-    /// derive the default daemon URL when `daemon_url` is unset.
-    pub daemon_bind_addr: Option<SocketAddr>,
-}
-
-impl CliConfig {
-    /// Load the subset of the unified file the CLI consumes. A missing file is
-    /// fine — every field has a default.
-    pub fn load(path: &Path) -> Result<Self, ConfigError> {
-        let file = MaestroConfigFile::load(path)?;
-        Ok(Self {
-            daemon_url: file.cli.daemon_url,
-            daemon_bind_addr: file.daemon.bind_addr,
-        })
-    }
-
-    /// Resolve the daemon HTTP base to talk to.
-    ///
-    /// Precedence: explicit `override_url` (CLI flag / env) → `[cli].daemon_url`
-    /// → `http://<[daemon].bind_addr>` → [`DEFAULT_DAEMON_URL`]. Always returns
-    /// a value; reachability is decided by whether the connection succeeds.
-    pub fn resolve_daemon_url(&self, override_url: Option<String>) -> String {
-        override_url
-            .or_else(|| self.daemon_url.clone())
-            .or_else(|| self.daemon_bind_addr.map(|a| format!("http://{a}")))
-            .unwrap_or_else(|| DEFAULT_DAEMON_URL.to_string())
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn write_file(path: &Path, body: &str) {
-        std::fs::write(path, body).unwrap();
-    }
-
-    #[test]
-    fn missing_file_returns_empty() {
-        let dir = tempfile::tempdir().unwrap();
-        let cfg = CliConfig::load(&dir.path().join("config.toml")).unwrap();
-        assert_eq!(cfg, CliConfig::default());
-    }
-
-    #[test]
-    fn resolve_daemon_url_precedence() {
-        // override wins over everything
-        let cfg = CliConfig {
-            daemon_url: Some("http://from-cli-section:7070".into()),
-            daemon_bind_addr: Some("127.0.0.1:9999".parse().unwrap()),
-        };
-        assert_eq!(
-            cfg.resolve_daemon_url(Some("http://override:1".into())),
-            "http://override:1"
-        );
-        // [cli].daemon_url next
-        assert_eq!(cfg.resolve_daemon_url(None), "http://from-cli-section:7070");
-        // derive from [daemon].bind_addr when no explicit url
-        let cfg = CliConfig {
-            daemon_bind_addr: Some("10.0.0.7:7070".parse().unwrap()),
-            ..Default::default()
-        };
-        assert_eq!(cfg.resolve_daemon_url(None), "http://10.0.0.7:7070");
-        // built-in default when nothing is configured
-        let cfg = CliConfig::default();
-        assert_eq!(cfg.resolve_daemon_url(None), DEFAULT_DAEMON_URL);
-    }
-
-    #[test]
-    fn load_reads_daemon_url_and_daemon_bind_addr() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("config.toml");
-        write_file(
-            &path,
-            r#"
-[cli]
-daemon_url = "http://laptop:7070"
-
-[daemon]
-bind_addr = "127.0.0.1:7071"
-"#,
-        );
-        let cfg = CliConfig::load(&path).unwrap();
-        assert_eq!(cfg.daemon_url.as_deref(), Some("http://laptop:7070"));
-        assert_eq!(
-            cfg.daemon_bind_addr,
-            Some("127.0.0.1:7071".parse().unwrap())
-        );
-    }
-}

crates/maestro-cli/src/dispatch.rs

@@ -6,22 +6,27 @@
 
 use std::path::{Path, PathBuf};
 
-use crate::attach::{attach_url, parse_detach_key, run_attach_url};
-use crate::cli::{AttachArgs, Command, KillArgs, ListArgs, SpawnArgs};
-use crate::config::{default_config_path, CliConfig, ConfigError};
-use crate::http::DaemonClient;
+use maestro_protocol::DaemonClient;
+
+use crate::attach::{parse_detach_key, run_attach_url};
+use crate::cli::Command;
 use crate::sessions::{run_kill, run_list, run_spawn};
+use maestro_config::{default_config_path, MaestroConfigFile};
 
 #[derive(Debug, thiserror::Error)]
 #[allow(clippy::result_large_err)]
 pub enum CliError {
     #[error("config: {0}")]
-    Config(#[from] ConfigError),
+    Config(#[from] maestro_config::ConfigError),
     #[error("{0}")]
-    Http(#[from] crate::http::HttpError),
+    Client(#[from] maestro_protocol::ClientError),
     #[error("{0}")]
     Attach(#[from] crate::attach::AttachError),
     #[error("{0}")]
+    Hooks(#[from] maestro_hooks::HooksError),
+    #[error("could not determine the home directory ($HOME unset?)")]
+    NoHome,
+    #[error("{0}")]
     Io(#[from] std::io::Error),
 }
 
@@ -38,76 +43,95 @@ pub async fn dispatch(
         None => default_config_path()?,
     };
 
+    // `hooks install` is purely local: it must work with the daemon down, so
+    // it never touches the client.
+    if let Command::Hooks(args) = &command {
+        match args.command {
+            crate::cli::HooksCommand::Install => run_hooks_install()?,
+        }
+        return Ok(());
+    }
+
+    let daemon = client(&config_path, daemon_url_override)?;
+
     match command {
-        Command::List(args) => list(&config_path, daemon_url_override, args).await,
-        Command::Spawn(args) => spawn(&config_path, daemon_url_override, args).await,
-        Command::Attach(args) => attach(&config_path, daemon_url_override, args).await,
-        Command::Kill(args) => kill(&config_path, daemon_url_override, args).await,
-    }
-}
-
-#[allow(clippy::result_large_err)]
-async fn list(
-    config_path: &Path,
-    daemon_url_override: Option<String>,
-    args: ListArgs,
-) -> Result<(), CliError> {
-    let daemon = client(config_path, daemon_url_override)?;
-    let mut stdout = std::io::stdout().lock();
-    run_list(&daemon, &args, &mut stdout).await?;
-    Ok(())
-}
-
-#[allow(clippy::result_large_err)]
-async fn spawn(
-    config_path: &Path,
-    daemon_url_override: Option<String>,
-    args: SpawnArgs,
-) -> Result<(), CliError> {
-    let daemon = client(config_path, daemon_url_override)?;
-    let attach_after = args.attach;
-    // `spawn --attach` has no detach-key flag; use the attach default (Ctrl-q).
-    let detach_key = 0x11;
-
-    let session = run_spawn(&daemon, args).await?;
-    println!("spawned {}", session.id);
-
-    if attach_after {
-        let url = attach_url(daemon.base(), session.id)?;
-        run_attach_url(&url, detach_key).await?;
+        Command::List(args) => {
+            let mut stdout = std::io::stdout().lock();
+            run_list(&daemon, &args, &mut stdout).await?;
+        }
+        Command::Spawn(args) => {
+            let attach_after = args.attach;
+            let session = run_spawn(&daemon, args).await?;
+            println!("spawned {}", session.id);
+            if attach_after {
+                // `spawn --attach` has no detach-key flag; use the attach
+                // default (Ctrl-q).
+                run_attach_url(&daemon.attach_url(session.id)?, CTRL_Q).await?;
+            }
+        }
+        Command::Attach(args) => {
+            let detach = parse_detach_key(&args.detach_key)?;
+            run_attach_url(&daemon.attach_url(args.session_id)?, detach).await?;
+        }
+        Command::Kill(args) => {
+            // #83: warn BEFORE the attempt, so the refusal is not a surprise.
+            // Best-effort: an unreachable list must not block the kill.
+            if !args.force {
+                warn_if_blocked(&daemon, args.session_id).await;
+            }
+            run_kill(&daemon, &args).await?;
+            println!("killed {}", args.session_id);
+        }
+        Command::Hooks(_) => unreachable!("hooks handled before the daemon client exists"),
     }
     Ok(())
 }
 
+/// `maestro hooks install` (#106): write the shipped hook script under the
+/// user's data dir and register it in their Claude Code settings. Idempotent
+/// and foreign-hook-preserving — the guarantees live in [`maestro_hooks`].
 #[allow(clippy::result_large_err)]
-async fn attach(
-    config_path: &Path,
-    daemon_url_override: Option<String>,
-    args: AttachArgs,
-) -> Result<(), CliError> {
-    let daemon = client(config_path, daemon_url_override)?;
-    let detach = parse_detach_key(&args.detach_key)?;
-    let url = attach_url(daemon.base(), args.session_id)?;
-    run_attach_url(&url, detach).await?;
+fn run_hooks_install() -> Result<(), CliError> {
+    let home = dirs::home_dir().ok_or(CliError::NoHome)?;
+    let changed = maestro_hooks::install_for_home(&home)?;
+    if changed {
+        println!(
+            "installed claude-code activity hook: {} → {}",
+            maestro_hooks::script_path(&home).display(),
+            maestro_hooks::settings_path(&home).display()
+        );
+    } else {
+        println!("claude-code activity hook already up to date");
+    }
     Ok(())
 }
 
-#[allow(clippy::result_large_err)]
-async fn kill(
-    config_path: &Path,
-    daemon_url_override: Option<String>,
-    args: KillArgs,
-) -> Result<(), CliError> {
-    let daemon = client(config_path, daemon_url_override)?;
-    run_kill(&daemon, &args).await?;
-    println!("killed {}", args.session_id);
-    Ok(())
+/// Default detach byte, matching `maestro attach --detach-key`'s `^q`.
+const CTRL_Q: u8 = 0x11;
+
+/// #83: say "this will be refused" before the operator commits to it, in the
+/// same words [`maestro_protocol::InTheWay`] uses everywhere else.
+async fn warn_if_blocked(daemon: &DaemonClient, id: uuid::Uuid) {
+    let Ok(sessions) = daemon.list_sessions().await else {
+        return;
+    };
+    if let Some(b) = sessions
+        .iter()
+        .find(|s| s.id == id)
+        .and_then(|s| s.blocked_work)
+    {
+        if !b.is_clear() {
+            eprintln!(
+                "warning: this kill will be refused — the session's worktree holds unsaved work ({b}); use --force to end it anyway"
+            );
+        }
+    }
 }
 
 /// HTTP client pointed at the daemon's API. That surface needs no auth —
 /// reaching `bind_addr` is the authorization.
 #[allow(clippy::result_large_err)]
 fn client(config_path: &Path, override_url: Option<String>) -> Result<DaemonClient, CliError> {
-    let cfg = CliConfig::load(config_path)?;
+    let cfg = MaestroConfigFile::load(config_path)?;
     Ok(DaemonClient::new(cfg.resolve_daemon_url(override_url)))
 }

crates/maestro-cli/src/http.rs

@@ -1,161 +0,0 @@
-//! Thin HTTP client wrapper around `reqwest` for the daemon's `/api/*` surface.
-
-use std::time::Duration;
-
-use reqwest::{Method, Response, StatusCode};
-use serde::de::DeserializeOwned;
-use serde::Serialize;
-
-use crate::config::ConfigError;
-
-/// Time budget for establishing a TCP connection to the daemon.
-const CONNECT_TIMEOUT: Duration = Duration::from_secs(5);
-/// Total time budget for a single request (connect + send + receive). Bounds
-/// the case where the peer is TCP-alive but never makes forward progress.
-const REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
-
-/// Build a `reqwest::Client` with the CLI's standard timeouts and user-agent.
-///
-/// Centralizing construction here guarantees every client the CLI uses gets a
-/// connect *and* request timeout, so `maestro` never hangs forever on an
-/// unhealthy daemon (NAP-262).
-pub fn build_client() -> reqwest::Client {
-    build_client_with_timeouts(CONNECT_TIMEOUT, REQUEST_TIMEOUT)
-}
-
-fn build_client_with_timeouts(connect: Duration, request: Duration) -> reqwest::Client {
-    reqwest::Client::builder()
-        .user_agent(concat!("maestro-cli/", env!("CARGO_PKG_VERSION")))
-        .connect_timeout(connect)
-        .timeout(request)
-        .build()
-        .expect("build reqwest client")
-}
-
-#[derive(Debug, thiserror::Error)]
-pub enum HttpError {
-    #[error("http: {0}")]
-    Reqwest(#[from] reqwest::Error),
-    #[error("server returned {status}: {body}")]
-    ServerError { status: StatusCode, body: String },
-    #[error("decode: {0}")]
-    Json(#[from] serde_json::Error),
-    #[error("config: {0}")]
-    Config(#[from] ConfigError),
-}
-
-impl HttpError {
-    /// True when the error is a transport-level failure to reach the host
-    /// (connection refused / connect error) rather than an HTTP-level
-    /// rejection.
-    pub fn is_unreachable(&self) -> bool {
-        matches!(self, HttpError::Reqwest(e) if e.is_connect())
-    }
-}
-
-/// HTTP client bound to one daemon's `/api/*` base URL. The daemon's surface
-/// needs no auth — reaching its bind address is the authorization.
-#[derive(Debug)]
-pub struct DaemonClient {
-    base: String,
-    inner: reqwest::Client,
-}
-
-impl DaemonClient {
-    pub fn new(base: String) -> Self {
-        Self {
-            base: base.trim_end_matches('/').to_string(),
-            inner: build_client(),
-        }
-    }
-
-    pub fn base(&self) -> &str {
-        &self.base
-    }
-
-    async fn send(
-        &self,
-        method: Method,
-        path: &str,
-        body: Option<serde_json::Value>,
-    ) -> Result<Response, HttpError> {
-        let url = format!("{}{}", self.base, path);
-        let mut req = self.inner.request(method, &url);
-        if let Some(b) = body {
-            req = req.json(&b);
-        }
-        Ok(req.send().await?)
-    }
-
-    pub async fn get_json<T: DeserializeOwned>(&self, path: &str) -> Result<T, HttpError> {
-        let resp = self.send(Method::GET, path, None).await?;
-        ok_or_body(resp)
-            .await?
-            .json::<T>()
-            .await
-            .map_err(Into::into)
-    }
-
-    pub async fn post_json<B: Serialize, T: DeserializeOwned>(
-        &self,
-        path: &str,
-        body: &B,
-    ) -> Result<T, HttpError> {
-        let v = serde_json::to_value(body)?;
-        let resp = self.send(Method::POST, path, Some(v)).await?;
-        ok_or_body(resp)
-            .await?
-            .json::<T>()
-            .await
-            .map_err(Into::into)
-    }
-
-    pub async fn delete(&self, path: &str) -> Result<(), HttpError> {
-        let resp = self.send(Method::DELETE, path, None).await?;
-        ok_or_body(resp).await?;
-        Ok(())
-    }
-}
-
-async fn ok_or_body(resp: Response) -> Result<Response, HttpError> {
-    let status = resp.status();
-    if status.is_success() {
-        return Ok(resp);
-    }
-    let body = resp.text().await.unwrap_or_default();
-    Err(HttpError::ServerError { status, body })
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    /// A peer that accepts the TCP connection but never sends a response must
-    /// not hang the client forever: the request timeout has to fire (NAP-262).
-    #[tokio::test]
-    async fn request_timeout_fires_when_peer_never_responds() {
-        use std::io::Read;
-        use std::net::TcpListener;
-
-        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
-        let addr = listener.local_addr().unwrap();
-        // Accept one connection and sit on it without ever writing a response.
-        let handle = std::thread::spawn(move || {
-            if let Ok((mut sock, _)) = listener.accept() {
-                let mut buf = [0u8; 1024];
-                let _ = sock.read(&mut buf);
-                std::thread::sleep(Duration::from_secs(2));
-            }
-        });
-
-        let client = build_client_with_timeouts(Duration::from_secs(5), Duration::from_millis(300));
-        let err = client
-            .get(format!("http://{addr}/"))
-            .send()
-            .await
-            .expect_err("request should time out, not hang");
-        assert!(err.is_timeout(), "expected timeout error, got: {err}");
-
-        let _ = handle.join();
-    }
-}

crates/maestro-cli/src/lib.rs

@@ -4,9 +4,7 @@
 
 pub mod attach;
 pub mod cli;
-pub mod config;
 pub mod dispatch;
-pub mod http;
 pub mod sessions;
 
 pub use dispatch::{dispatch, CliError};

crates/maestro-cli/src/sessions.rs

@@ -3,31 +3,23 @@
 use std::collections::HashMap;
 use std::io::Write;
 
-use maestro_protocol::{ActivityState, CreateSessionRequest, Session, SessionStatus, WorktreeSpec};
-use serde::Deserialize;
+use maestro_protocol::display::abbreviate_dir;
+use maestro_protocol::{
+    ActivityState, ClientError, CreateSessionRequest, DaemonClient, DaemonInfo, Session,
+    SessionStatus, WorktreeSpec,
+};
 use serde_json::Value;
 
 use crate::cli::{KillArgs, ListArgs, SpawnArgs};
-use crate::http::{DaemonClient, HttpError};
-
-/// The bits of `GET /api/info` the CLI renders. Deserialized structurally so
-/// the CLI doesn't depend on the daemon crate.
-#[derive(Debug, Clone, Default, Deserialize)]
-pub struct DaemonInfo {
-    #[serde(default)]
-    pub hostname: String,
-    #[serde(default)]
-    pub home_dir: String,
-}
 
 /// `maestro list`
 pub async fn run_list(
     client: &DaemonClient,
     args: &ListArgs,
     out: &mut impl Write,
-) -> Result<(), HttpError> {
-    let sessions: Vec<Session> = client.get_json("/api/sessions").await?;
-    let info: DaemonInfo = client.get_json("/api/info").await.unwrap_or_default();
+) -> Result<(), ClientError> {
+    let sessions = client.list_sessions().await?;
+    let info = client.daemon_info().await.unwrap_or_default();
 
     if args.json {
         let body = serde_json::json!({ "sessions": sessions });
@@ -40,7 +32,7 @@ pub async fn run_list(
 }
 
 /// `maestro spawn`
-pub async fn run_spawn(client: &DaemonClient, args: SpawnArgs) -> Result<Session, HttpError> {
+pub async fn run_spawn(client: &DaemonClient, args: SpawnArgs) -> Result<Session, ClientError> {
     let mut env: HashMap<String, String> = HashMap::new();
     for (k, v) in args.env.iter() {
         env.insert(k.clone(), v.clone());
@@ -52,7 +44,7 @@ pub async fn run_spawn(client: &DaemonClient, args: SpawnArgs) -> Result<Session
         (Some(repo), Some(branch)) => Some(WorktreeSpec {
             base_repo: repo.clone(),
             branch: branch.clone(),
-            cleanup_on_kill: args.cleanup_on_kill,
+            create_branch: !args.existing_branch,
         }),
         _ => None,
     };
@@ -64,15 +56,14 @@ pub async fn run_spawn(client: &DaemonClient, args: SpawnArgs) -> Result<Session
         metadata,
         worktree,
     };
-    let session: Session = client.post_json("/api/sessions", &body).await?;
-    Ok(session)
+    client.create_session(&body).await
 }
 
-/// `maestro kill`
-pub async fn run_kill(client: &DaemonClient, args: &KillArgs) -> Result<(), HttpError> {
-    client
-        .delete(&format!("/api/sessions/{}", args.session_id))
-        .await
+/// `maestro kill`. A forced kill (#81) retains the guarded worktree instead
+/// of removing it; the outcome names what was kept so dispatch can say where
+/// the work went.
+pub async fn run_kill(client: &DaemonClient, args: &KillArgs) -> Result<(), ClientError> {
+    client.kill_session(args.session_id, args.force).await
 }
 
 #[allow(clippy::write_literal)]
@@ -86,12 +77,22 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
     sorted.sort_by_key(|s| s.created_at);
 
     if !info.hostname.is_empty() {
-        writeln!(out, "\n{}", info.hostname).ok();
+        let warn = if maestro_protocol::is_compatible(&info.version) {
+            ""
+        } else {
+            "  (protocol mismatch)"
+        };
+        let version = if info.version.is_empty() {
+            String::new()
+        } else {
+            format!("  maestro {}{warn}", info.version)
+        };
+        writeln!(out, "\n{}{version}", info.hostname).ok();
     }
     writeln!(
         out,
-        "  {:<36}  {:<8}  {:<9}  {:<28}  {}",
-        "ID", "STATUS", "ACTIVITY", "DIR", "COMMAND"
+        "  {:<36}  {:<8}  {:<9}  {:<28}  {:<40}  {}",
+        "ID", "STATUS", "ACTIVITY", "DIR", "COMMAND", "BLOCKED"
     )
     .ok();
     for s in sorted {
@@ -105,6 +106,7 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
             ActivityState::Active => "active",
             ActivityState::Idle => "idle",
             ActivityState::AwaitingInput => "awaiting",
+            ActivityState::Error => "error",
         };
         // Show the live foreground command alongside the spawn command when
         // the daemon has observed one that differs (NAP-340).
@@ -112,28 +114,26 @@ fn print_session_table(out: &mut impl Write, sessions: &[Session], info: &Daemon
             Some(fg) if fg != &s.command => format!("{} [{}]", s.command, fg),
             _ => s.command.clone(),
         };
+        // #83: what an unforced kill would be refused for, in InTheWay's own
+        // words; blank while nothing blocks (or hasn't been probed yet).
+        let blocked = blocked_label(s);
         writeln!(
             out,
-            "  {:<36}  {:<8}  {:<9}  {:<28}  {command}",
-            s.id, status, activity, dir
+            "  {:<36}  {:<8}  {:<9}  {:<28}  {:<40}  {blocked}",
+            s.id, status, activity, dir, command
         )
         .ok();
     }
 }
 
-/// Render a path with the daemon's home dir collapsed to `~`. Mirrors the web
-/// UI's abbreviation so CLI and browser show the same directory shorthand.
-fn abbreviate_dir(path: &std::path::Path, home: &str) -> String {
-    let p = path.to_string_lossy();
-    if !home.is_empty() {
-        if p == home {
-            return "~".into();
-        }
-        if let Some(rest) = p.strip_prefix(&format!("{home}/")) {
-            return format!("~/{rest}");
-        }
-    }
-    p.into_owned()
+/// The blocked-work indicator (#83), phrased by [`InTheWay`]'s `Display`.
+/// Empty unless something actually blocks — "no unsaved work" would just be
+/// noise on every row.
+pub(crate) fn blocked_label(s: &Session) -> String {
+    s.blocked_work
+        .filter(|b| !b.is_clear())
+        .map(|b| b.to_string())
+        .unwrap_or_default()
 }
 
 #[cfg(test)]
@@ -154,12 +154,16 @@ mod tests {
             command: command.into(),
             env: HashMap::new(),
             metadata: HashMap::new(),
+            worktree: None,
             status: SessionStatus::Running,
             created_at: Utc.with_ymd_and_hms(2026, 5, 25, 12, 0, 0).unwrap(),
             foreground: None,
             activity: Default::default(),
+            activity_detail: None,
             last_activity_at: chrono::Utc::now(),
+            activity_since: chrono::Utc::now(),
             current_cwd: None,
+            blocked_work: None,
         }
     }
 
@@ -167,6 +171,7 @@ mod tests {
         DaemonInfo {
             hostname: "naps-laptop".into(),
             home_dir: home.into(),
+            ..Default::default()
         }
     }
 
@@ -219,4 +224,37 @@ mod tests {
         super::print_session_table(&mut buf, &[], &info(""));
         assert_eq!(String::from_utf8(buf).unwrap(), "no sessions\n");
     }
+
+    /// #83: a blocked session shows what an unforced kill would be refused
+    /// for, in `InTheWay`'s own words; a clear or unprobed one shows nothing.
+    #[test]
+    fn shows_the_blocked_work_summary_only_when_something_blocks() {
+        use maestro_protocol::InTheWay;
+
+        let mut blocked = session("/tmp", "claude", 1);
+        blocked.blocked_work = Some(InTheWay {
+            uncommitted_files: 3,
+            unpushed_commits: 2,
+            ..InTheWay::default()
+        });
+        let mut clear = session("/tmp", "bash", 2);
+        clear.blocked_work = Some(InTheWay::default());
+        let unprobed = session("/tmp", "zsh", 3);
+
+        let mut buf = Vec::new();
+        super::print_session_table(&mut buf, &[blocked, clear, unprobed], &info(""));
+        let out = String::from_utf8(buf).unwrap();
+        assert!(
+            out.contains("3 uncommitted files, 2 unpushed commits"),
+            "{out}"
+        );
+        // Clear and unprobed rows stay blank in the BLOCKED column.
+        let lines: Vec<&str> = out.lines().collect();
+        let header = lines.iter().position(|l| l.contains("BLOCKED")).unwrap();
+        for line in &lines[header + 1..] {
+            if !line.contains("uncommitted files") {
+                assert!(!line.contains("unsaved work"), "{line}");
+            }
+        }
+    }
 }

crates/maestro-cli/tests/against_mock_daemon.rs

@@ -0,0 +1,110 @@
+//! The CLI against a daemon. It had no such tests: `maestro list`'s formatting
+//! was unit-tested, but nothing exercised the client, the error decoding, or
+//! the unreachable-daemon path without compiling and forking a real daemon.
+
+use maestro_protocol::{DaemonClient, DaemonInfo};
+use maestro_testing::{session, MockDaemon};
+use uuid::Uuid;
+
+#[tokio::test]
+async fn list_reads_the_daemon_catalog() {
+    let mock = MockDaemon::start().await;
+    mock.add_session(session(Uuid::from_u128(1), "/home/mock/work", "claude"));
+
+    let sessions = mock.client().list_sessions().await.expect("list");
+
+    assert_eq!(sessions.len(), 1);
+    assert_eq!(sessions[0].command, "claude");
+}
+
+#[tokio::test]
+async fn info_carries_version_and_presets() {
+    let mock = MockDaemon::start().await;
+    mock.set_info(DaemonInfo {
+        hostname: "konishi".into(),
+        version: "9.9.9".into(),
+        home_dir: "/home/naps".into(),
+        presets: vec![maestro_protocol::SpawnPreset {
+            id: "claude".into(),
+            label: "Claude".into(),
+            command: "claude".into(),
+        }],
+    });
+
+    let info = mock.client().daemon_info().await.expect("info");
+
+    // The CLI's own DaemonInfo used to drop both of these fields.
+    assert_eq!(info.version, "9.9.9");
+    assert_eq!(info.presets.len(), 1);
+}
+
+#[tokio::test]
+async fn a_structured_failure_surfaces_the_daemon_message() {
+    let mock = MockDaemon::start().await;
+    mock.force_error(502, "tmux_failed", "no server running");
+
+    let err = mock
+        .client()
+        .list_sessions()
+        .await
+        .expect_err("should fail");
+
+    assert_eq!(
+        err.daemon_message(),
+        Some("no server running"),
+        "the daemon's own message must survive: {err}"
+    );
+    assert!(!err.is_unreachable());
+}
+
+#[tokio::test]
+async fn an_unreachable_daemon_is_distinguishable_from_a_rejection() {
+    // Port 1 has nothing listening on it.
+    let client = DaemonClient::new("http://127.0.0.1:1");
+
+    let err = client.list_sessions().await.expect_err("should fail");
+
+    assert!(
+        err.is_unreachable(),
+        "connection refused must not read as an HTTP rejection: {err}"
+    );
+}
+
+#[tokio::test]
+async fn killing_an_unknown_session_reports_the_daemon_reason() {
+    let mock = MockDaemon::start().await;
+
+    let err = mock
+        .client()
+        .kill_session(Uuid::new_v4(), false)
+        .await
+        .expect_err("should fail");
+
+    assert_eq!(err.daemon_message(), Some("no such session on this daemon"));
+}
+
+#[tokio::test]
+async fn spawn_round_trips_through_the_daemon() {
+    let mock = MockDaemon::start().await;
+
+    let created = mock
+        .client()
+        .create_session(&maestro_protocol::CreateSessionRequest {
+            cwd: "/home/mock".into(),
+            command: "bash".into(),
+            env: Default::default(),
+            metadata: Default::default(),
+            worktree: None,
+        })
+        .await
+        .expect("create");
+
+    assert_eq!(created.command, "bash");
+    assert_eq!(mock.session_count(), 1);
+
+    mock.client()
+        .kill_session(created.id, false)
+        .await
+        .expect("kill");
+    assert_eq!(mock.session_count(), 0);
+}

crates/maestro-config/Cargo.toml

@@ -8,6 +8,7 @@ publish.workspace = true
 
 [dependencies]
 dirs.workspace = true
+maestro-protocol.workspace = true
 serde.workspace = true
 thiserror.workspace = true
 toml.workspace = true

crates/maestro-config/src/lib.rs

@@ -22,14 +22,16 @@ use std::collections::BTreeMap;
 use std::net::SocketAddr;
 use std::path::{Path, PathBuf};
 
-use serde::{Deserialize, Serialize};
+use serde::de::Error as _;
+use serde::{Deserialize, Deserializer};
 
 /// Directory name under `$XDG_CONFIG_HOME` (default `~/.config`).
 pub const DIR_NAME: &str = "maestro";
 /// File name inside [`DIR_NAME`].
 pub const FILE_NAME: &str = "config.toml";
-/// Env var that, when set, overrides the resolved config-file path.
-pub const CONFIG_PATH_ENV: &str = "MAESTRO_CONFIG";
+
+/// Last-resort daemon HTTP base, matching the daemon's own default `bind_addr`.
+pub const DEFAULT_DAEMON_URL: &str = "http://127.0.0.1:7070";
 
 #[derive(Debug, thiserror::Error)]
 pub enum ConfigError {
@@ -51,55 +53,68 @@ pub enum ConfigError {
 
 /// On-disk representation of the unified config. Every section is optional
 /// so a partial file (e.g. just `[daemon]`) is valid.
-#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
 pub struct MaestroConfigFile {
-    #[serde(default, skip_serializing_if = "CliSection::is_empty")]
+    #[serde(default)]
     pub cli: CliSection,
-    #[serde(default, skip_serializing_if = "DaemonSection::is_empty")]
+    #[serde(default)]
     pub daemon: DaemonSection,
-    #[serde(default, skip_serializing_if = "WebSection::is_empty")]
+    #[serde(default)]
     pub web: WebSection,
-    #[serde(default, skip_serializing_if = "TuiSection::is_empty")]
+    #[serde(default)]
     pub tui: TuiSection,
-    #[serde(default, skip_serializing_if = "SpawnSection::is_empty")]
+    #[serde(default)]
     pub spawn: SpawnSection,
+    #[serde(default)]
+    pub hooks: HooksSection,
 }
 
-#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+/// `[hooks]` — agent-hook installation settings (#106).
+#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
+pub struct HooksSection {
+    /// Whether the daemon installs the Claude Code activity hook into
+    /// `~/.claude/settings.json` on first start when no maestro hook is
+    /// there yet. Default `true`; set `auto_install = false` to opt out.
+    #[serde(default)]
+    pub auto_install: Option<bool>,
+}
+
+impl HooksSection {
+    pub fn auto_install(&self) -> bool {
+        self.auto_install.unwrap_or(true)
+    }
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
 pub struct CliSection {
     /// HTTP base URL of the daemon the CLI talks to, e.g.
     /// `http://127.0.0.1:7070`. When unset, the CLI derives it from
     /// `[daemon].bind_addr` if a daemon is configured locally, else falls
     /// back to `http://127.0.0.1:7070`.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[serde(default)]
     pub daemon_url: Option<String>,
 }
 
-impl CliSection {
-    fn is_empty(&self) -> bool {
-        self.daemon_url.is_none()
-    }
-}
-
-#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
 pub struct DaemonSection {
     /// Hostname advertised to clients, purely for display. Defaults to
     /// `gethostname(2)`.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[serde(default)]
     pub hostname: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[serde(default)]
     pub bind_addr: Option<SocketAddr>,
     /// Root for everything daemon-local: sidecars, FIFOs, etc.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[serde(default)]
     pub state_dir: Option<PathBuf>,
-    /// Root for ephemeral worktrees the daemon creates on `CreateSession`
-    /// with a `worktree` spec.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
+    /// Override root for ephemeral worktrees the daemon creates on
+    /// `CreateSession` with a `worktree` spec. Unset by default: worktrees
+    /// then live inside their base repo at `<repo>/worktrees/<branch>` (#56).
+    #[serde(default)]
     pub worktree_root: Option<PathBuf>,
     /// Per-session PTY replay buffer cap in bytes (NAP-229). Each new attach
     /// receives this much of the prior PTY output before the live stream.
     /// `None` ⇒ daemon default (~64 KB); `Some(0)` disables replay.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[serde(default)]
     pub pty_replay_bytes: Option<usize>,
     /// `TMUX_TMPDIR` the daemon exports for every `tmux` invocation (NAP-234).
     /// When unset, the daemon defaults to `$XDG_RUNTIME_DIR` so that bare
@@ -107,104 +122,149 @@ pub struct DaemonSection {
     /// maestro sessions. Set to `/tmp` to opt back into tmux's own default —
     /// useful if the daemon outlives the user's login session and you can't
     /// enable `loginctl enable-linger`.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[serde(default)]
     pub tmux_tmpdir: Option<PathBuf>,
     /// Recency cap in days for the durable spawn history that backs the spawn
     /// form's "recent dirs" picker (#24). `None` ⇒ daemon default (30 days);
     /// `Some(0)` disables history entirely (no log written, no recents read).
-    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[serde(default)]
     pub spawn_history_days: Option<u32>,
 }
 
-impl DaemonSection {
-    fn is_empty(&self) -> bool {
-        self.hostname.is_none()
-            && self.bind_addr.is_none()
-            && self.state_dir.is_none()
-            && self.worktree_root.is_none()
-            && self.pty_replay_bytes.is_none()
-            && self.tmux_tmpdir.is_none()
-            && self.spawn_history_days.is_none()
-    }
-}
-
 /// `[web]` — `maestro-web` binary settings (NAP-241).
-#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
 pub struct WebSection {
     /// Address `maestro-web` binds. Default `127.0.0.1:8080`. Bind a LAN/VPN
     /// address to share with your own devices on a trusted segment; there is no
     /// auth layer, so never bind a public address.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[serde(default)]
     pub bind_addr: Option<SocketAddr>,
     /// HTTP base URL of the co-located daemon `maestro-web` proxies to.
     /// Default `http://127.0.0.1:7070`.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[serde(default)]
     pub daemon_url: Option<String>,
-    /// When set, requests for `/` are proxied to a Vite dev server at this
-    /// URL instead of being served from the embedded bundle. Use it during
-    /// frontend development so live reload works.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub dev_proxy_target: Option<String>,
-}
-
-impl WebSection {
-    fn is_empty(&self) -> bool {
-        self.bind_addr.is_none() && self.daemon_url.is_none() && self.dev_proxy_target.is_none()
-    }
 }
 
 /// `[tui]` — `maestro tui` settings (NAP-275 epic, phase 2 NAP-277).
 ///
-/// Leader key, chord timeout, and per-mode keymap overrides. The TUI ships
-/// with a default keymap; entries in `keymap_normal` / `keymap_insert` are
-/// applied **over** the defaults, so a partial override is enough.
-#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+/// Theme, leader key, chord timeout, and per-mode keymap overrides. The TUI
+/// ships with a default keymap; entries in `keymap_normal` / `keymap_insert`
+/// are applied **over** the defaults, so a partial override is enough.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
 pub struct TuiSection {
+    /// Named palette preset. Defaults to the dark preset.
+    #[serde(default, deserialize_with = "deserialize_theme")]
+    pub theme: Option<TuiTheme>,
     /// Canonical key form, e.g. `"ctrl-a"`. Default `ctrl-a`.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[serde(default)]
     pub leader: Option<String>,
     /// Maximum interval between chord keys before a held prefix is dropped.
     /// Default `1000`.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[serde(default)]
     pub chord_timeout_ms: Option<u64>,
     /// Normal-mode bindings: canonical input → action string. Applied over
     /// the shipped defaults.
-    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    #[serde(default)]
     pub keymap_normal: BTreeMap<String, String>,
     /// Insert-mode bindings, same semantics as `keymap_normal`.
-    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    #[serde(default)]
     pub keymap_insert: BTreeMap<String, String>,
 }
 
-impl TuiSection {
-    pub fn is_empty(&self) -> bool {
-        self.leader.is_none()
-            && self.chord_timeout_ms.is_none()
-            && self.keymap_normal.is_empty()
-            && self.keymap_insert.is_empty()
-    }
+/// Palette presets supported by the TUI's `[tui].theme` setting.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TuiTheme {
+    /// The terminal-native dark palette and the default.
+    Dark,
+    /// A high-contrast light palette.
+    Light,
+    /// Named ANSI colours, allowing the terminal to provide the colour set.
+    Ansi,
+    /// Solarized Dark.
+    SolarizedDark,
+    /// Solarized Light.
+    SolarizedLight,
+    /// Catppuccin Mocha.
+    Catppuccin,
+    /// GitHub Dark.
+    GithubDark,
+    /// GitHub Light.
+    GithubLight,
+    /// Tokyo Night.
+    TokyoNight,
+    /// Gruvbox Dark.
+    Gruvbox,
+    /// Nord.
+    Nord,
+    /// Dracula.
+    Dracula,
+}
+
+/// Every `[tui].theme` name and its variant, in documentation order.
+pub const TUI_THEMES: &[(&str, TuiTheme)] = &[
+    ("dark", TuiTheme::Dark),
+    ("light", TuiTheme::Light),
+    ("ansi", TuiTheme::Ansi),
+    ("solarized-dark", TuiTheme::SolarizedDark),
+    ("solarized-light", TuiTheme::SolarizedLight),
+    ("catppuccin", TuiTheme::Catppuccin),
+    ("github-dark", TuiTheme::GithubDark),
+    ("github-light", TuiTheme::GithubLight),
+    ("tokyo-night", TuiTheme::TokyoNight),
+    ("gruvbox", TuiTheme::Gruvbox),
+    ("nord", TuiTheme::Nord),
+    ("dracula", TuiTheme::Dracula),
+];
+
+fn deserialize_theme<'de, D>(deserializer: D) -> Result<Option<TuiTheme>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let raw = Option::<String>::deserialize(deserializer)?;
+    raw.map(|name| {
+        TUI_THEMES
+            .iter()
+            .find(|(n, _)| *n == name)
+            .map(|(_, theme)| *theme)
+            .ok_or_else(|| {
+                let known = TUI_THEMES
+                    .iter()
+                    .map(|(n, _)| format!("{n:?}"))
+                    .collect::<Vec<_>>()
+                    .join(", ");
+                D::Error::custom(format!(
+                    "invalid [tui].theme {name:?}; expected one of {known}"
+                ))
+            })
+    })
+    .transpose()
 }
 
 /// `[spawn]` — command presets for the spawn form (#22, part of #21).
 ///
 /// Defined in shared config so every binary sees the same list: the web reads
 /// it via the daemon's catalog advertisement (#26), the TUI adopts it later.
-#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
 pub struct SpawnSection {
     /// Command presets offered as one-click tiles. When present, this list
     /// **replaces** the [`builtin_presets`] defaults (the implicit `custom`
     /// escape hatch is still appended by [`SpawnSection::resolve`]); when
     /// absent, the built-ins are used. `presets = []` is "present but empty" —
     /// it resolves to just the `custom` tile.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[serde(default)]
     pub presets: Option<Vec<SpawnPreset>>,
+    /// Root directories the daemon scans for git repositories (#54), `~`
+    /// expanded by the daemon against its own home. When absent the daemon
+    /// scans `["~"]`.
+    #[serde(default)]
+    pub project_roots: Option<Vec<String>>,
+    /// How many directory levels below each [`Self::project_roots`] entry the
+    /// scanner descends (#54). When absent the daemon uses `3`.
+    #[serde(default)]
+    pub project_scan_depth: Option<u32>,
 }
 
 impl SpawnSection {
-    fn is_empty(&self) -> bool {
-        self.presets.is_none()
-    }
-
     /// The presets to show, in order, with the implicit `custom` tile appended.
     ///
     /// Resolution: configured `presets` if present, else [`builtin_presets`];
@@ -226,12 +286,10 @@ impl SpawnSection {
 /// tile, and the `command` to run. The implicit `custom` tile (see
 /// [`custom_preset`]) reuses this shape with an empty `command` the client
 /// fills from free-text input.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct SpawnPreset {
-    pub id: String,
-    pub label: String,
-    pub command: String,
-}
+///
+/// Defined in `maestro-protocol` because it also rides `GET /api/info`; the
+/// on-disk `[spawn].presets` schema and the wire payload are one type.
+pub use maestro_protocol::SpawnPreset;
 
 /// Reserved id for the implicit free-text tile. A user-defined preset may not
 /// claim it (see [`SpawnConfigError::ReservedCustomId`]) since it's always
@@ -319,27 +377,20 @@ impl MaestroConfigFile {
         Ok(toml::from_str(s)?)
     }
 
-    /// Atomic write (tmp + rename). Creates parent dirs on demand.
-    pub fn save(&self, path: &Path) -> Result<(), ConfigError> {
-        if let Some(parent) = path.parent() {
-            std::fs::create_dir_all(parent)?;
-        }
-        let body = toml::to_string_pretty(self)?;
-        let tmp = path.with_extension("toml.tmp");
-        std::fs::write(&tmp, body)?;
-        std::fs::rename(&tmp, path)?;
-        Ok(())
+    /// Daemon HTTP base a client should talk to.
+    ///
+    /// Precedence: explicit `override_url` (flag or env), then
+    /// `[cli].daemon_url`, then `http://<[daemon].bind_addr>`, then
+    /// [`DEFAULT_DAEMON_URL`]. Always yields a value — reachability is decided
+    /// by whether the connection succeeds.
+    pub fn resolve_daemon_url(&self, override_url: Option<String>) -> String {
+        override_url
+            .or_else(|| self.cli.daemon_url.clone())
+            .or_else(|| self.daemon.bind_addr.map(|a| format!("http://{a}")))
+            .unwrap_or_else(|| DEFAULT_DAEMON_URL.to_string())
     }
 }
 
-/// `$MAESTRO_CONFIG` if set, else [`default_config_path`].
-pub fn resolve_config_path() -> Result<PathBuf, ConfigError> {
-    if let Some(p) = std::env::var_os(CONFIG_PATH_ENV) {
-        return Ok(PathBuf::from(p));
-    }
-    default_config_path()
-}
-
 /// `~/.config/maestro/config.toml` (XDG-aware).
 pub fn default_config_path() -> Result<PathBuf, ConfigError> {
     let base = dirs::config_dir().ok_or(ConfigError::NoConfigDir)?;
@@ -368,32 +419,10 @@ pub fn default_state_dir(subdir: &str) -> Result<PathBuf, ConfigError> {
         .ok_or(ConfigError::NoConfigDir)?;
     Ok(base.join(subdir))
 }
-
-/// Capacities for the daemon's broadcast channels (session events and PTY byte
-/// fan-out). These were independent `= 256` constants scattered across the
-/// daemon; centralizing them here makes the coincidence explicit and gives a
-/// single home for per-deployment tuning later (NAP-273).
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct BroadcastTuning {
-    /// Session event channels (`SessionEvent`, `CatalogEvent`).
-    pub events_capacity: usize,
-    /// Per-session PTY byte broadcast channel.
-    pub pty_capacity: usize,
-}
-
-impl BroadcastTuning {
-    /// The historical defaults — every channel was 256 by coincidence.
-    pub const DEFAULT: Self = Self {
-        events_capacity: 256,
-        pty_capacity: 256,
-    };
-}
-
-impl Default for BroadcastTuning {
-    fn default() -> Self {
-        Self::DEFAULT
-    }
-}
+/// Capacity of the session-event broadcast channel (`CatalogEvent`).
+pub const EVENTS_CAPACITY: usize = 256;
+/// Capacity of the per-session PTY byte broadcast channel.
+pub const PTY_CAPACITY: usize = 256;
 
 #[cfg(test)]
 mod tests {
@@ -424,10 +453,9 @@ mod tests {
     }
 
     #[test]
-    fn broadcast_tuning_defaults_to_256() {
-        assert_eq!(BroadcastTuning::default(), BroadcastTuning::DEFAULT);
-        assert_eq!(BroadcastTuning::DEFAULT.events_capacity, 256);
-        assert_eq!(BroadcastTuning::DEFAULT.pty_capacity, 256);
+    fn broadcast_capacities_are_the_historical_defaults() {
+        assert_eq!(EVENTS_CAPACITY, 256);
+        assert_eq!(PTY_CAPACITY, 256);
     }
 
     #[test]
@@ -439,43 +467,23 @@ mod tests {
     }
 
     #[test]
-    fn full_file_round_trips() {
+    fn hooks_auto_install_defaults_true_and_is_opt_out() {
+        // Absent file / absent [hooks] ⇒ auto_install on.
+        assert!(HooksSection::default().auto_install());
         let dir = tempfile::tempdir().unwrap();
         let path = dir.path().join("config.toml");
-        let cfg = MaestroConfigFile {
-            cli: CliSection {
-                daemon_url: Some("http://127.0.0.1:7070".into()),
-            },
-            daemon: DaemonSection {
-                hostname: Some("laptop.lan".into()),
-                bind_addr: Some("127.0.0.1:7070".parse().unwrap()),
-                state_dir: Some(PathBuf::from("/var/lib/maestrod")),
-                worktree_root: Some(PathBuf::from("/var/lib/maestrod/wt")),
-                pty_replay_bytes: Some(131_072),
-                tmux_tmpdir: Some(PathBuf::from("/run/user/1000")),
-                spawn_history_days: Some(14),
-            },
-            web: WebSection {
-                bind_addr: Some("127.0.0.1:8080".parse().unwrap()),
-                daemon_url: Some("http://127.0.0.1:7070".into()),
-                dev_proxy_target: Some("http://127.0.0.1:5173".into()),
-            },
-            tui: TuiSection {
-                leader: Some("ctrl-b".into()),
-                chord_timeout_ms: Some(750),
-                keymap_normal: BTreeMap::from([("i".into(), "ShowHelp".into())]),
-                keymap_insert: BTreeMap::new(),
-            },
-            spawn: SpawnSection {
-                presets: Some(vec![SpawnPreset {
-                    id: "claude".into(),
-                    label: "Claude".into(),
-                    command: "claude --resume".into(),
-                }]),
-            },
-        };
-        cfg.save(&path).unwrap();
-        assert_eq!(MaestroConfigFile::load(&path).unwrap(), cfg);
+        std::fs::write(&path, "").unwrap();
+        assert!(MaestroConfigFile::load(&path).unwrap().hooks.auto_install());
+
+        std::fs::write(
+            &path,
+            r#"
+[hooks]
+auto_install = false
+"#,
+        )
+        .unwrap();
+        assert!(!MaestroConfigFile::load(&path).unwrap().hooks.auto_install());
     }
 
     #[test]
@@ -499,6 +507,7 @@ mod tests {
                 label: "fish".into(),
                 command: "fish".into(),
             }]),
+            ..Default::default()
         };
         let ids: Vec<String> = section
             .resolve()
@@ -515,6 +524,7 @@ mod tests {
         // only the implicit custom tile.
         let section = SpawnSection {
             presets: Some(vec![]),
+            ..Default::default()
         };
         let ids: Vec<String> = section
             .resolve()
@@ -533,6 +543,7 @@ mod tests {
                 label: "x".into(),
                 command: "x".into(),
             }]),
+            ..Default::default()
         };
         assert_eq!(empty_id.resolve().unwrap_err(), SpawnConfigError::EmptyId);
 
@@ -542,6 +553,7 @@ mod tests {
                 label: "x".into(),
                 command: "".into(),
             }]),
+            ..Default::default()
         };
         assert_eq!(
             empty_cmd.resolve().unwrap_err(),
@@ -564,6 +576,7 @@ mod tests {
                     command: "a2".into(),
                 },
             ]),
+            ..Default::default()
         };
         assert_eq!(
             dup.resolve().unwrap_err(),
@@ -576,6 +589,7 @@ mod tests {
                 label: "Custom".into(),
                 command: "whatever".into(),
             }]),
+            ..Default::default()
         };
         assert_eq!(
             reserved.resolve().unwrap_err(),
@@ -610,20 +624,27 @@ presets = [
     }
 
     #[test]
-    fn save_omits_empty_spawn_section() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("config.toml");
-        MaestroConfigFile {
-            daemon: DaemonSection {
-                hostname: Some("laptop".into()),
-                ..Default::default()
-            },
-            ..Default::default()
-        }
-        .save(&path)
-        .unwrap();
-        let body = std::fs::read_to_string(&path).unwrap();
-        assert!(!body.contains("[spawn]"), "body: {body}");
+    fn spawn_project_scan_fields_default_to_none() {
+        // Absent [spawn].project_* → None; the daemon applies its own defaults.
+        assert_eq!(SpawnSection::default().project_roots, None);
+        assert_eq!(SpawnSection::default().project_scan_depth, None);
+    }
+
+    #[test]
+    fn spawn_project_scan_fields_parse_from_toml() {
+        let cfg = toml::from_str::<MaestroConfigFile>(
+            r#"
+[spawn]
+project_roots = ["~/code", "/srv/work"]
+project_scan_depth = 5
+"#,
+        )
+        .expect("parse");
+        assert_eq!(
+            cfg.spawn.project_roots,
+            Some(vec!["~/code".to_string(), "/srv/work".to_string()])
+        );
+        assert_eq!(cfg.spawn.project_scan_depth, Some(5));
     }
 
     #[test]
@@ -649,39 +670,58 @@ bind_addr = "127.0.0.1:9090"
     }
 
     #[test]
-    fn save_omits_empty_sections() {
-        // Avoid littering the file with empty `[cli]` / `[daemon]` tables
-        // when only one component is configured.
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("config.toml");
-        let cfg = MaestroConfigFile {
-            daemon: DaemonSection {
-                hostname: Some("laptop".into()),
-                ..Default::default()
-            },
-            ..Default::default()
-        };
-        cfg.save(&path).unwrap();
-        let body = std::fs::read_to_string(&path).unwrap();
-        assert!(body.contains("[daemon]"), "body: {body}");
-        assert!(!body.contains("[cli]"), "body: {body}");
-        assert!(!body.contains("[web]"), "body: {body}");
+    fn tui_theme_parses_named_presets_and_defaults_when_absent() {
+        assert_eq!(TuiSection::default().theme, None);
+        for (name, theme) in TUI_THEMES {
+            let cfg = file_with(&format!("[tui]\ntheme = \"{name}\"\n"));
+            assert_eq!(cfg.tui.theme, Some(*theme));
+        }
     }
 
     #[test]
-    fn save_atomic_creates_parent_dirs() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("nested/here/config.toml");
-        MaestroConfigFile::default().save(&path).unwrap();
-        assert!(path.exists());
+    fn tui_theme_rejects_unknown_names_with_the_field_name() {
+        let err = toml::from_str::<MaestroConfigFile>("[tui]\ntheme = \"glorb\"\n").unwrap_err();
+        let message = err.to_string();
+        assert!(
+            message.contains("[tui].theme"),
+            "diagnostic should name the field: {message}"
+        );
+        assert!(
+            message.contains("glorb"),
+            "diagnostic should name the invalid value: {message}"
+        );
+    }
+
+    fn file_with(body: &str) -> MaestroConfigFile {
+        toml::from_str(body).expect("parse")
     }
 
     #[test]
-    fn resolve_config_path_respects_env_var() {
-        // We can't safely tweak the process env in a unit test (it races with
-        // other tests). Exercise the default path branch instead and rely on
-        // an integration-level smoke that env-override works.
-        let p = default_config_path().unwrap();
-        assert!(p.ends_with(format!("{DIR_NAME}/{FILE_NAME}")));
+    fn daemon_url_prefers_an_explicit_override() {
+        let cfg = file_with("[cli]\ndaemon_url = \"http://from-file:1\"\n");
+        assert_eq!(
+            cfg.resolve_daemon_url(Some("http://override:2".into())),
+            "http://override:2"
+        );
+    }
+
+    #[test]
+    fn daemon_url_falls_back_through_cli_then_bind_addr_then_default() {
+        let from_cli = file_with("[cli]\ndaemon_url = \"http://from-cli:1\"\n");
+        assert_eq!(from_cli.resolve_daemon_url(None), "http://from-cli:1");
+
+        let from_bind = file_with("[daemon]\nbind_addr = \"10.0.0.1:7070\"\n");
+        assert_eq!(from_bind.resolve_daemon_url(None), "http://10.0.0.1:7070");
+
+        let empty = MaestroConfigFile::default();
+        assert_eq!(empty.resolve_daemon_url(None), DEFAULT_DAEMON_URL);
+    }
+
+    #[test]
+    fn cli_daemon_url_beats_a_locally_configured_bind_addr() {
+        let cfg = file_with(
+            "[cli]\ndaemon_url = \"http://explicit:1\"\n[daemon]\nbind_addr = \"10.0.0.1:7070\"\n",
+        );
+        assert_eq!(cfg.resolve_daemon_url(None), "http://explicit:1");
     }
 }

crates/maestro-daemon/Cargo.toml

@@ -18,6 +18,8 @@ dirs.workspace = true
 futures-util.workspace = true
 libc.workspace = true
 maestro-config.workspace = true
+maestro-hooks.workspace = true
+maestro-names.workspace = true
 maestro-protocol.workspace = true
 serde.workspace = true
 serde_json.workspace = true
@@ -32,5 +34,6 @@ reqwest.workspace = true
 tokio-tungstenite.workspace = true
 urlencoding = "2"
 tempfile.workspace = true
+maestro-names.workspace = true
 # `test-util` enables `start_paused` for instant timeout tests (NAP-270).
 tokio = { workspace = true, features = ["test-util"] }

crates/maestro-daemon/src/activity.rs

@@ -15,6 +15,44 @@ use maestro_protocol::ActivityState;
 /// Active↔Idle. This window *is* the debounce the issue calls for.
 pub const ACTIVE_WINDOW: Duration = Duration::from_secs(3);
 
+/// How long an agent-reported state (#105) stays in force before inference
+/// resumes. Long enough for a working agent's heartbeat to hold between
+/// reports, short enough that an agent dying mid-run cannot pin its session
+/// at `Error` forever.
+pub const REPORT_TTL: Duration = Duration::from_secs(300);
+
+/// Server-side cap (#105) on a reported `detail`, in characters. The meta
+/// line renders it inline, so an unbounded string would own the whole card.
+pub const MAX_REPORT_DETAIL_CHARS: usize = 256;
+
+/// An agent-reported activity state (#105) still within its TTL. While one
+/// is [`Self::in_force`], it outranks [`decide`]'s inference; when it
+/// lapses, inference resumes and any reported detail is cleared with it.
+#[derive(Debug, Clone)]
+pub struct ReportedActivity {
+    pub state: ActivityState,
+    pub expires_at: std::time::Instant,
+}
+
+impl ReportedActivity {
+    pub fn new(state: ActivityState, ttl: Duration) -> Self {
+        Self {
+            state,
+            expires_at: std::time::Instant::now() + ttl,
+        }
+    }
+
+    pub fn in_force(&self, now: std::time::Instant) -> bool {
+        now < self.expires_at
+    }
+}
+
+/// Cap a reported detail to [`MAX_REPORT_DETAIL_CHARS`] characters,
+/// char-boundary safe.
+pub fn truncate_detail(detail: Option<String>) -> Option<String> {
+    detail.map(|d| d.chars().take(MAX_REPORT_DETAIL_CHARS).collect())
+}
+
 /// Combine the observed signals into an [`ActivityState`]:
 /// recent output ⇒ `Active`; else blocked on a terminal read ⇒ `AwaitingInput`;
 /// else `Idle`.
@@ -59,4 +97,25 @@ mod tests {
             ActivityState::Idle
         );
     }
+
+    #[test]
+    fn report_is_in_force_until_exactly_its_expiry() {
+        let ttl = Duration::from_secs(300);
+        let report = ReportedActivity::new(ActivityState::Error, ttl);
+        assert!(report.in_force(report.expires_at - Duration::from_millis(1)));
+        assert!(!report.in_force(report.expires_at));
+    }
+
+    #[test]
+    fn detail_truncates_to_the_cap_without_panic_on_multibyte_input() {
+        let long = "é".repeat(MAX_REPORT_DETAIL_CHARS + 10);
+        let capped = truncate_detail(Some(long)).unwrap();
+        assert_eq!(capped.chars().count(), MAX_REPORT_DETAIL_CHARS);
+
+        assert_eq!(truncate_detail(None), None);
+        assert_eq!(
+            truncate_detail(Some("short".into())).as_deref(),
+            Some("short")
+        );
+    }
 }

crates/maestro-daemon/src/attach.rs

@@ -6,29 +6,26 @@
 use axum::extract::ws::{Message, WebSocket};
 use futures_util::{SinkExt, StreamExt};
 use maestro_protocol::ClientControl;
+use tokio::sync::broadcast;
 use tokio::sync::broadcast::error::RecvError;
 use uuid::Uuid;
 
 use crate::session::SessionManager;
 
 /// Pump a WebSocket against a session's PTY, behind `WS /api/attach/:id`.
+///
+/// The subscription is acquired by the handler *before* the upgrade and handed
+/// in here, so there is no window in which the session can disappear between
+/// the existence check and the subscribe.
 pub(crate) async fn serve(
     socket: WebSocket,
     manager: SessionManager,
     id: Uuid,
+    replay: Vec<u8>,
+    mut rx: broadcast::Receiver<Vec<u8>>,
 ) -> Result<(), axum::Error> {
     let (mut sink, mut stream) = socket.split();
 
-    let (replay, mut rx) = match manager.subscribe_pty_with_replay(id).await {
-        Some(pair) => pair,
-        None => {
-            // session was killed between the existence check and now — let the
-            // client see a clean close instead of a dropped socket.
-            let _ = sink.send(Message::Close(None)).await;
-            return Ok(());
-        }
-    };
-
     // NAP-229: send buffered scrollback up-front so the client sees the last
     // screenful immediately instead of a blank terminal. The replay lock the
     // bridge held during snapshot+subscribe guarantees no byte appears both

crates/maestro-daemon/src/branches.rs

@@ -0,0 +1,167 @@
+//! `GET /api/branches` — local branches of one repository (#55).
+//!
+//! Spawning into a worktree on an *existing* branch needs to know which
+//! branches the repository has and which are taken: git refuses to check the
+//! same branch out in two worktrees at once. Each [`BranchInfo`] answers for
+//! one local branch — its name, whether it is the main checkout's HEAD, and
+//! which linked worktree (if any) holds it.
+//!
+//! Read-only, like [`crate::gitroot`]: two git probes (`for-each-ref`,
+//! `worktree list --porcelain`) with no write path anywhere. A path outside
+//! any repository yields an empty list rather than an error, matching how
+//! `/api/gitroot` reports "not a repository".
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use axum::extract::{Query, State};
+use axum::response::{IntoResponse, Response};
+use axum::Json;
+use maestro_protocol::BranchInfo;
+use serde::Deserialize;
+
+use crate::local_api::LocalApiState;
+
+/// Query string for `GET /api/branches`. Same `path` convention as
+/// `/api/dirs` and `/api/gitroot`: resolved against the daemon's home dir.
+#[derive(Debug, Deserialize)]
+pub struct BranchesQuery {
+    #[serde(default)]
+    pub path: String,
+}
+
+pub async fn handler(State(s): State<LocalApiState>, Query(q): Query<BranchesQuery>) -> Response {
+    let dir = crate::dirlist::resolve(&s.home_dir, &q.path);
+    Json(list(&dir)).into_response()
+}
+
+/// List the enclosing repository's local branches. Empty when `dir` is not
+/// inside a repository.
+pub fn list(dir: &Path) -> Vec<BranchInfo> {
+    let Some(root) = crate::gitroot::find_root(dir) else {
+        return Vec::new();
+    };
+    let worktrees = worktree_branches(&root);
+    // The first porcelain record is always the main checkout; its branch is
+    // the HEAD answer. Linked worktrees are the occupancy map.
+    let head_branch = worktrees.first().and_then(|(branch, _)| branch.clone());
+    let occupied: HashMap<&str, &Path> = worktrees
+        .iter()
+        .skip(1)
+        .filter_map(|(branch, path)| branch.as_deref().map(|b| (b, path.as_path())))
+        .collect();
+
+    branch_names(&root)
+        .into_iter()
+        .map(|name| BranchInfo {
+            is_head: head_branch.as_deref() == Some(name.as_str()),
+            worktree: occupied.get(name.as_str()).copied().map(Path::to_path_buf),
+            name,
+        })
+        .collect()
+}
+
+fn run_git(root: &Path, args: &[&str]) -> Option<String> {
+    let out = Command::new("git")
+        .arg("-C")
+        .arg(root)
+        .args(args)
+        .output()
+        .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    Some(String::from_utf8_lossy(&out.stdout).into_owned())
+}
+
+fn branch_names(root: &Path) -> Vec<String> {
+    run_git(
+        root,
+        &["for-each-ref", "refs/heads", "--format=%(refname:short)"],
+    )
+    .map(|out| {
+        out.lines()
+            .filter(|l| !l.is_empty())
+            .map(str::to_owned)
+            .collect()
+    })
+    .unwrap_or_default()
+}
+
+fn worktree_branches(root: &Path) -> Vec<(Option<String>, PathBuf)> {
+    let out = match run_git(root, &["worktree", "list", "--porcelain"]) {
+        Some(out) => out,
+        None => return Vec::new(),
+    };
+    parse_worktrees(&out)
+}
+
+/// Parse `git worktree list --porcelain` into `(branch, toplevel)` records,
+/// branch-less for detached/bare checkouts. Records are separated by blank
+/// lines; each `worktree` line starts a new one.
+fn parse_worktrees(out: &str) -> Vec<(Option<String>, PathBuf)> {
+    let mut result: Vec<(Option<String>, PathBuf)> = Vec::new();
+    let mut pending: Option<PathBuf> = None;
+    let mut branch: Option<String> = None;
+
+    for line in out.lines() {
+        if let Some(path) = line.strip_prefix("worktree ") {
+            if let Some(prev) = pending.take() {
+                result.push((branch.take(), prev));
+            }
+            pending = Some(PathBuf::from(path));
+        } else if let Some(b) = line.strip_prefix("branch ") {
+            branch = Some(b.trim_start_matches("refs/heads/").to_owned());
+        }
+    }
+    if let Some(path) = pending {
+        result.push((branch.take(), path));
+    }
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_main_and_linked_worktrees() {
+        let out = "\
+worktree /repos/maestro
+HEAD 0123abcd
+branch refs/heads/main
+
+worktree /repos/wt-feature
+HEAD 4567abcd
+branch refs/heads/spawn-v2
+
+";
+        assert_eq!(
+            parse_worktrees(out),
+            vec![
+                (Some("main".into()), PathBuf::from("/repos/maestro")),
+                (Some("spawn-v2".into()), PathBuf::from("/repos/wt-feature")),
+            ]
+        );
+    }
+
+    #[test]
+    fn detached_head_yields_no_branch() {
+        let out = "\
+worktree /repos/detached
+HEAD 0123abcd
+detached
+
+";
+        assert_eq!(
+            parse_worktrees(out),
+            vec![(None, PathBuf::from("/repos/detached"))]
+        );
+    }
+
+    #[test]
+    fn empty_output_yields_no_records() {
+        assert!(parse_worktrees("").is_empty());
+    }
+}

crates/maestro-daemon/src/cli.rs

@@ -12,8 +12,7 @@ use crate::sidecar::SidecarStore;
 use crate::tmux::Tmux;
 use crate::worktree::WorktreeManager;
 use crate::{
-    default_config_path, default_state_dir, load_config, local_api, spawn_session_publisher,
-    EnvOverrides, LocalEventBus, SessionManager,
+    default_config_path, default_state_dir, load_config, local_api, EnvOverrides, SessionManager,
 };
 
 #[derive(Debug, Subcommand)]
@@ -48,7 +47,22 @@ async fn run(config_override: Option<PathBuf>) -> Result<(), Box<dyn Error>> {
     let _ = default_state_dir();
     std::fs::create_dir_all(config.sidecar_dir())?;
     std::fs::create_dir_all(config.fifo_dir())?;
-    std::fs::create_dir_all(&config.worktree_root)?;
+
+    // First-start hook auto-install (#106). Best-effort, before serving: a
+    // session spawned right away should already carry the hook.
+    if config.hooks_auto_install {
+        match crate::hooks::auto_install(&config.home_dir) {
+            crate::hooks::AutoInstallOutcome::Installed => {
+                tracing::info!("installed claude-code activity hook (#106)");
+            }
+            crate::hooks::AutoInstallOutcome::Failed => {
+                tracing::warn!("hooks auto-install failed; run `maestro hooks install` manually");
+            }
+            _ => {}
+        }
+    }
+    // No worktree dir to pre-create: without an override the worktrees live
+    // under their base repos, created on demand (#56).
 
     let sidecar = SidecarStore::new(config.sidecar_dir());
     let worktree_mgr = WorktreeManager::new(config.worktree_root.clone());
@@ -57,7 +71,7 @@ async fn run(config_override: Option<PathBuf>) -> Result<(), Box<dyn Error>> {
         None => Tmux::new(),
     };
     let manager = SessionManager::new_with_replay(
-        tmux,
+        std::sync::Arc::new(tmux),
         sidecar,
         worktree_mgr,
         config.fifo_dir(),
@@ -67,20 +81,27 @@ async fn run(config_override: Option<PathBuf>) -> Result<(), Box<dyn Error>> {
         config.spawn_history_path(),
         config.spawn_history_days,
     ));
+    // Spawned sessions learn where to report back (#103). Derived from the
+    // configured bind address; set before any spawn can happen.
+    manager.set_daemon_url(format!("http://{}", config.bind_addr));
 
     let recovered = manager.recover().await?;
     tracing::info!(recovered, "adopted existing tmux sessions");
     manager.start_liveness_watcher(DEFAULT_LIVENESS_INTERVAL);
 
-    let events = LocalEventBus::new();
-    spawn_session_publisher(manager.clone(), events.clone());
+    let projects = std::sync::Arc::new(crate::projects::ProjectScanner::new(
+        config.project_roots.clone(),
+        config.project_scan_depth,
+        PathBuf::from(&config.home_dir),
+    ));
+    projects.start_background_refresh();
 
     let router = local_api::router(local_api::state_for(
         manager,
         config.hostname.clone(),
         config.home_dir.clone(),
         config.spawn_presets.clone(),
-        events,
+        projects,
     ));
 
     let listener = TcpListener::bind(config.bind_addr).await?;

crates/maestro-daemon/src/config.rs

@@ -14,9 +14,7 @@ use std::path::{Path, PathBuf};
 
 use maestro_config::MaestroConfigFile;
 
-pub use maestro_config::{
-    default_config_path, resolve_config_path, DaemonSection, CONFIG_PATH_ENV,
-};
+pub use maestro_config::default_config_path;
 
 /// Default bind address when neither env nor file specify one.
 pub const DEFAULT_BIND_ADDR: &str = "127.0.0.1:7070";
@@ -25,6 +23,14 @@ pub const DEFAULT_BIND_ADDR: &str = "127.0.0.1:7070";
 /// `[daemon].spawn_history_days` is unset. `0` in config disables history.
 pub const DEFAULT_SPAWN_HISTORY_DAYS: u32 = 30;
 
+/// Default scan roots for project discovery (#54) when `[spawn].project_roots`
+/// is unset: the whole home directory, with the scanner's own ignore list
+/// keeping it cheap.
+pub const DEFAULT_PROJECT_ROOTS: [&str; 1] = ["~"];
+/// Default directory depth for project discovery (#54) when
+/// `[spawn].project_scan_depth` is unset.
+pub const DEFAULT_PROJECT_SCAN_DEPTH: u32 = 3;
+
 /// Env var that overrides `[daemon].bind_addr`.
 pub const ENV_DAEMON_BIND_ADDR: &str = "MAESTRO_DAEMON_BIND_ADDR";
 /// Env var that overrides `[daemon].tmux_tmpdir`.
@@ -55,7 +61,10 @@ pub struct DaemonConfig {
     pub home_dir: String,
     pub bind_addr: SocketAddr,
     pub state_dir: PathBuf,
-    pub worktree_root: PathBuf,
+    /// `[daemon].worktree_root` override (#56). `None` — the default — places
+    /// worktrees inside their base repo at `<repo>/worktrees/<branch>`;
+    /// operators who want them elsewhere set this.
+    pub worktree_root: Option<PathBuf>,
     /// Per-session PTY replay buffer cap in bytes (NAP-229). Each new attach
     /// receives this much of the prior PTY output before the live stream.
     /// Default `pty::DEFAULT_REPLAY_BYTES`; `0` disables.
@@ -73,6 +82,16 @@ pub struct DaemonConfig {
     /// built-ins) with the implicit `custom` tile appended. Advertised to
     /// clients in `GET /api/info`.
     pub spawn_presets: Vec<maestro_config::SpawnPreset>,
+    /// Project-discovery scan roots (#54): `[spawn].project_roots` (default
+    /// [`DEFAULT_PROJECT_ROOTS`]) with `~` expanded against the daemon's home.
+    pub project_roots: Vec<PathBuf>,
+    /// Project-discovery depth (#54): `[spawn].project_scan_depth`, default
+    /// [`DEFAULT_PROJECT_SCAN_DEPTH`].
+    pub project_scan_depth: u32,
+    /// Whether the daemon installs the Claude Code activity hook on first
+    /// start when none is present (#106): `[hooks].auto_install`, default
+    /// `true`.
+    pub hooks_auto_install: bool,
 }
 
 impl DaemonConfig {
@@ -133,9 +152,6 @@ pub fn load_config(path: &Path, env: EnvOverrides) -> Result<DaemonConfig, Confi
         Some(p) => p,
         None => default_state_dir()?,
     };
-    let worktree_root = daemon
-        .worktree_root
-        .unwrap_or_else(|| state_dir.join("worktrees"));
 
     let pty_replay_bytes = daemon
         .pty_replay_bytes
@@ -149,19 +165,54 @@ pub fn load_config(path: &Path, env: EnvOverrides) -> Result<DaemonConfig, Confi
         .spawn_history_days
         .unwrap_or(DEFAULT_SPAWN_HISTORY_DAYS);
 
+    // `~` in scan roots means the daemon's own home; an unresolvable home
+    // leaves the tilde as-is and the scanner treats the root as missing.
+    let project_roots: Vec<PathBuf> = file
+        .spawn
+        .project_roots
+        .unwrap_or_else(|| {
+            DEFAULT_PROJECT_ROOTS
+                .iter()
+                .map(|s| s.to_string())
+                .collect()
+        })
+        .iter()
+        .map(|root| expand_tilde(root, &home_dir))
+        .collect();
+    let project_scan_depth = file
+        .spawn
+        .project_scan_depth
+        .unwrap_or(DEFAULT_PROJECT_SCAN_DEPTH);
+
     Ok(DaemonConfig {
         hostname,
         home_dir,
         bind_addr,
         state_dir,
-        worktree_root,
+        worktree_root: daemon.worktree_root,
         pty_replay_bytes,
         tmux_tmpdir,
         spawn_history_days,
         spawn_presets,
+        project_roots,
+        project_scan_depth,
+        hooks_auto_install: file.hooks.auto_install(),
     })
 }
 
+/// Expand a leading `~` (or `~/…`) against `home`. Other paths pass through.
+fn expand_tilde(path: &str, home: &str) -> PathBuf {
+    match path.strip_prefix("~") {
+        Some(_) if home.is_empty() => PathBuf::from(path),
+        Some(rest) => {
+            let mut p = PathBuf::from(home);
+            p.push(rest.trim_start_matches('/'));
+            p
+        }
+        None => PathBuf::from(path),
+    }
+}
+
 pub fn default_state_dir() -> Result<PathBuf, ConfigError> {
     Ok(maestro_config::default_state_dir("maestro")?)
 }
@@ -182,6 +233,27 @@ pub fn system_hostname() -> String {
 mod tests {
     use super::*;
 
+    #[test]
+    fn hooks_auto_install_defaults_true_and_is_opt_out() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+
+        std::fs::write(&path, "").unwrap();
+        let cfg = load_config(&path, EnvOverrides::default()).unwrap();
+        assert!(cfg.hooks_auto_install);
+
+        std::fs::write(
+            &path,
+            r#"
+[hooks]
+auto_install = false
+"#,
+        )
+        .unwrap();
+        let cfg = load_config(&path, EnvOverrides::default()).unwrap();
+        assert!(!cfg.hooks_auto_install);
+    }
+
     #[test]
     fn empty_file_defaults_everything() {
         let dir = tempfile::tempdir().unwrap();
@@ -190,7 +262,7 @@ mod tests {
         let cfg = load_config(&path, EnvOverrides::default()).unwrap();
         assert_eq!(cfg.bind_addr, default_bind_addr());
         assert!(cfg.state_dir.ends_with("maestro"));
-        assert!(cfg.worktree_root.ends_with("worktrees"));
+        assert!(cfg.worktree_root.is_none());
         assert!(!cfg.hostname.is_empty());
     }
 
@@ -282,6 +354,56 @@ spawn_history_days = 0
         assert_eq!(cfg.spawn_history_days, 0);
     }
 
+    #[test]
+    fn project_scan_defaults_to_home_root_at_depth_3() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(&path, "").unwrap();
+        let cfg = load_config(&path, EnvOverrides::default()).unwrap();
+        assert_eq!(cfg.project_scan_depth, DEFAULT_PROJECT_SCAN_DEPTH);
+        assert_eq!(
+            cfg.project_roots,
+            vec![PathBuf::from(cfg.home_dir.clone())],
+            "bare ~ must expand to the daemon's home"
+        );
+    }
+
+    #[test]
+    fn project_scan_roots_expand_tilde_and_pass_through_absolutes() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(
+            &path,
+            r#"
+[spawn]
+project_roots = ["~/code", "/srv/work"]
+project_scan_depth = 5
+"#,
+        )
+        .unwrap();
+        let cfg = load_config(&path, EnvOverrides::default()).unwrap();
+        assert_eq!(cfg.project_scan_depth, 5);
+        assert_eq!(
+            cfg.project_roots,
+            vec![
+                PathBuf::from(cfg.home_dir.clone()).join("code"),
+                PathBuf::from("/srv/work"),
+            ]
+        );
+    }
+
+    #[test]
+    fn tilde_expansion_handles_bare_and_nested_forms() {
+        assert_eq!(expand_tilde("~", "/home/u"), PathBuf::from("/home/u"));
+        assert_eq!(
+            expand_tilde("~/a/b", "/home/u"),
+            PathBuf::from("/home/u/a/b")
+        );
+        assert_eq!(expand_tilde("/abs", "/home/u"), PathBuf::from("/abs"));
+        // Unresolvable home leaves the tilde as-is rather than mangling it.
+        assert_eq!(expand_tilde("~", ""), PathBuf::from("~"));
+    }
+
     #[test]
     fn system_hostname_is_nonempty() {
         let h = system_hostname();

crates/maestro-daemon/src/dirlist.rs

@@ -111,6 +111,7 @@ fn io_error(dir: &Path, e: &std::io::Error) -> ErrorInfo {
     ErrorInfo {
         code: code.into(),
         message: format!("{message}: {}", dir.display()),
+        unsaved_work: None,
     }
 }
 

crates/maestro-daemon/src/hooks.rs

@@ -0,0 +1,76 @@
+//! First-start hook auto-install (#106).
+//!
+//! The daemon runs [`auto_install`] once at startup: when the user's
+//! `~/.claude/settings.json` carries no maestro hook yet (and
+//! `[hooks].auto_install` hasn't opted out — checked by the caller), the same
+//! installer `maestro hooks install` uses writes it. Best-effort: a failure is
+//! warned about and never blocks startup. The same global hook serves every
+//! Claude Code session on the machine, so nothing here targets repositories
+//! or worktrees.
+
+use std::path::Path;
+
+/// Install the Claude Code activity hook for `home_dir` unless one is already
+/// present or the home dir is unresolvable (`""`). Returns what happened.
+pub fn auto_install(home_dir: &str) -> AutoInstallOutcome {
+    if home_dir.is_empty() {
+        return AutoInstallOutcome::Skipped;
+    }
+    let settings = maestro_hooks::settings_path(Path::new(home_dir));
+    if maestro_hooks::is_installed(&settings) {
+        return AutoInstallOutcome::AlreadyPresent;
+    }
+    match maestro_hooks::install_for_home(Path::new(home_dir)) {
+        Ok(_) => AutoInstallOutcome::Installed,
+        Err(e) => {
+            tracing::warn!(error = %e, "hooks auto-install failed (non-fatal)");
+            AutoInstallOutcome::Failed
+        }
+    }
+}
+
+/// What [`auto_install`] did, so callers can log and tests can assert.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AutoInstallOutcome {
+    Installed,
+    AlreadyPresent,
+    Failed,
+    Skipped,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Everything happens under a temp `$HOME`; the developer's own
+    /// `~/.claude/settings.json` is never read or written.
+    #[test]
+    fn installs_when_settings_carry_no_maestro_hook() {
+        let dir = tempfile::tempdir().unwrap();
+        let outcome = auto_install(dir.path().to_str().unwrap());
+        assert_eq!(outcome, AutoInstallOutcome::Installed);
+        let settings = dir.path().join(".claude/settings.json");
+        assert!(maestro_hooks::is_installed(&settings));
+    }
+
+    #[test]
+    fn second_start_is_a_noop() {
+        let dir = tempfile::tempdir().unwrap();
+        let home = dir.path().to_str().unwrap();
+        auto_install(home);
+        // A foreign edit between starts survives; presence alone skips.
+        let settings = dir.path().join(".claude/settings.json");
+        let before = std::fs::read_to_string(&settings).unwrap();
+        assert_eq!(auto_install(home), AutoInstallOutcome::AlreadyPresent);
+        assert_eq!(
+            before,
+            std::fs::read_to_string(&settings).unwrap(),
+            "already-installed settings must not be rewritten"
+        );
+    }
+
+    #[test]
+    fn unresolvable_home_is_skipped() {
+        assert_eq!(auto_install(""), AutoInstallOutcome::Skipped);
+    }
+}

crates/maestro-daemon/src/lib.rs

@@ -9,20 +9,24 @@
 
 pub mod activity;
 pub mod attach;
+pub mod branches;
 pub mod cli;
 pub mod config;
 pub mod dirlist;
 pub mod gitroot;
+pub mod hooks;
 pub mod local_api;
-pub mod local_events;
+pub mod panes;
 pub mod proc;
+pub mod projects;
 pub mod pty;
 pub mod session;
 pub mod sidecar;
 pub mod spawn_history;
 pub mod tmux;
 pub mod worktree;
+pub mod worktree_probe;
 
+pub use activity::MAX_REPORT_DETAIL_CHARS;
 pub use config::{default_config_path, default_state_dir, load_config, DaemonConfig, EnvOverrides};
-pub use local_events::{spawn_session_publisher, LocalEventBus};
-pub use session::{SessionError, SessionEvent, SessionManager};
+pub use session::{SessionError, SessionManager};

crates/maestro-daemon/src/local_api.rs

@@ -15,35 +15,18 @@ use std::sync::Arc;
 use axum::extract::{Path, Query, State};
 use axum::http::StatusCode;
 use axum::response::{IntoResponse, Response};
-use axum::routing::{any, delete, get};
+use axum::routing::{any, delete, get, post};
 use axum::{Json, Router};
 use maestro_config::SpawnPreset;
 use maestro_protocol::{
-    CatalogEvent, CreateSessionRequest, ErrorInfo, GitRoot, Session, PROTOCOL_VERSION,
+    routes, ApiError, CatalogEvent, CreateSessionRequest, DaemonInfo, GitRoot, NameBatch,
+    RenameSessionRequest, ReportActivityRequest, Session, PROTOCOL_VERSION,
 };
-use serde::{Deserialize, Serialize};
+use serde::Deserialize;
 use uuid::Uuid;
 
-use crate::local_events::LocalEventBus;
 use crate::session::SessionManager;
 
-/// Daemon identity returned by `GET /api/info`. Clients render this in the
-/// header ("you're connected to konishi"), plus the daemon's protocol version
-/// and its spawn presets (#26).
-#[derive(Debug, Clone, Serialize)]
-pub struct DaemonInfo {
-    pub hostname: String,
-    pub version: String,
-    /// Home directory of the OS user this daemon runs as, so clients can
-    /// prefill a spawn form's working directory. Empty if unresolved.
-    pub home_dir: String,
-    /// Spawn-form command presets resolved from `[spawn].presets` (#22), with
-    /// the implicit `custom` tile appended. Clients render these as one-click
-    /// tiles; it rides this existing payload so opening the form needs no extra
-    /// round-trip (#26).
-    pub presets: Vec<SpawnPreset>,
-}
-
 #[derive(Debug, Clone)]
 pub struct LocalApiState {
     pub manager: SessionManager,
@@ -53,21 +36,27 @@ pub struct LocalApiState {
     pub home_dir: Arc<String>,
     /// Resolved spawn presets (#22/#26) advertised in `GET /api/info`.
     pub presets: Arc<Vec<SpawnPreset>>,
-    /// Fan-out of session deltas (NAP-248). The `/api/events` WS subscribes
-    /// here; everything else just reads REST.
-    pub events: LocalEventBus,
+    /// Project discovery (#54) backing `GET /api/projects`.
+    pub projects: Arc<crate::projects::ProjectScanner>,
 }
 
 pub fn router(state: LocalApiState) -> Router {
     Router::new()
-        .route("/api/sessions", get(list_sessions).post(create_session))
-        .route("/api/sessions/:id", delete(kill_session))
-        .route("/api/dirs", get(list_dir))
-        .route("/api/recent-dirs", get(recent_dirs))
-        .route("/api/gitroot", get(git_root))
-        .route("/api/info", get(daemon_info))
-        .route("/api/events", any(events_ws))
-        .route("/api/attach/:id", any(attach_ws))
+        .route(routes::SESSIONS, get(list_sessions).post(create_session))
+        .route(routes::patterns::SESSION_ACTIVITY, post(report_activity))
+        .route(
+            routes::patterns::SESSION,
+            delete(kill_session).patch(rename_session),
+        )
+        .route(routes::DIRS, get(list_dir))
+        .route(routes::RECENT_DIRS, get(recent_dirs))
+        .route(routes::PROJECTS, get(projects))
+        .route(routes::GITROOT, get(git_root))
+        .route(routes::BRANCHES, get(crate::branches::handler))
+        .route(routes::NAMES, get(names))
+        .route(routes::INFO, get(daemon_info))
+        .route(routes::EVENTS, any(events_ws))
+        .route(routes::patterns::ATTACH, any(attach_ws))
         .with_state(state)
 }
 
@@ -103,11 +92,32 @@ fn dir_error_status(code: &str) -> StatusCode {
     }
 }
 
+/// HTTP status for a [`crate::session::SessionError`] code. Everything used to
+/// collapse to 502, which reports a client mistake as a daemon failure.
+fn session_error_status(code: &str) -> StatusCode {
+    match code {
+        "not_found" => StatusCode::NOT_FOUND,
+        "invalid_env" => StatusCode::BAD_REQUEST,
+        // A guard refusal is the daemon doing its job, not a failure (#79).
+        "kill_guarded" => StatusCode::CONFLICT,
+        _ => StatusCode::BAD_GATEWAY,
+    }
+}
+
 /// Recent working dirs for the spawn form's recents picker (#26).
 async fn recent_dirs(State(s): State<LocalApiState>) -> Response {
     Json(crate::spawn_history::to_wire(s.manager.recent_dirs())).into_response()
 }
 
+/// Discovered git repositories and worktrees, newest activity first (#54).
+/// `last_activity` is the later of the repo's git HEAD mtime and the newest
+/// spawn-history use of any directory inside it.
+async fn projects(State(s): State<LocalApiState>) -> Response {
+    let repos = s.projects.repos().await;
+    let history = s.manager.all_recent_dirs();
+    Json(crate::projects::to_projects(&repos, &history)).into_response()
+}
+
 /// Probe the enclosing git repo of `path`, to infer the worktree `base_repo`
 /// for the spawn form (#26). `path` is resolved against the daemon's home dir
 /// (empty/`~`/relative), like [`list_dir`].
@@ -119,6 +129,22 @@ async fn git_root(State(s): State<LocalApiState>, Query(q): Query<DirQuery>) ->
     .into_response()
 }
 
+/// Query string for `GET /api/names`. `count` defaults to 1 and is capped at
+/// [`maestro_names::MAX_BATCH`] (#53).
+#[derive(Debug, Deserialize)]
+struct NamesQuery {
+    count: Option<usize>,
+}
+
+/// Fresh session handles for the spawn form's instant reroll (#53). The web
+/// client fetches one batch per draft pane and rerolls locally from it.
+async fn names(Query(q): Query<NamesQuery>) -> Json<NameBatch> {
+    let count = q.count.unwrap_or(1).clamp(1, maestro_names::MAX_BATCH);
+    Json(NameBatch {
+        names: maestro_names::generate_batch(count),
+    })
+}
+
 async fn daemon_info(State(s): State<LocalApiState>) -> Json<DaemonInfo> {
     Json(DaemonInfo {
         hostname: (*s.hostname).clone(),
@@ -137,7 +163,7 @@ async fn create_session(
         Err(e) => {
             let info = e.to_error_info();
             error_response(
-                StatusCode::BAD_GATEWAY,
+                session_error_status(&info.code),
                 info.code.as_str(),
                 info.message.as_str(),
             )
@@ -145,20 +171,75 @@ async fn create_session(
     }
 }
 
-async fn kill_session(State(s): State<LocalApiState>, Path(id): Path<Uuid>) -> Response {
-    if !s.manager.has(id).await {
-        return error_response(
-            StatusCode::NOT_FOUND,
-            "unknown_session",
-            "no such session on this daemon",
-        );
+/// `kill` already reports a missing session as `SessionError::NotFound`, which
+/// maps to 404. Checking first would only add a window in which the liveness
+/// watcher reaps the session between the two awaits, turning a 404 into a 502.
+///
+/// The full error info is passed through rather than rebuilt from
+/// code + message: a `kill_guarded` refusal (#79) carries the unsaved-work
+/// breakdown clients render as "3 uncommitted files, 2 unpushed commits".
+///
+/// With `force=true` (#81) the refusal is overridden and the worktree is left
+/// on disk rather than removed. Either way the answer is `204`.
+#[derive(Debug, Deserialize)]
+struct KillQuery {
+    #[serde(default)]
+    force: bool,
+}
+
+async fn kill_session(
+    State(s): State<LocalApiState>,
+    Path(id): Path<Uuid>,
+    Query(q): Query<KillQuery>,
+) -> Response {
+    match s.manager.kill(id, q.force).await {
+        Ok(()) => StatusCode::NO_CONTENT.into_response(),
+        Err(e) => {
+            let info = e.to_error_info();
+            let status = session_error_status(&info.code);
+            (status, Json(ApiError { error: info })).into_response()
+        }
     }
-    match s.manager.kill(id).await {
+}
+
+/// `PATCH /api/sessions/:id` (#125): rename a session. The name is trimmed
+/// and capped server-side; a blank one clears `metadata.name` so the session
+/// falls back to its command. Answers with the updated session, which also
+/// goes out as `SessionUpdated` to every events subscriber.
+async fn rename_session(
+    State(s): State<LocalApiState>,
+    Path(id): Path<Uuid>,
+    Json(body): Json<RenameSessionRequest>,
+) -> Response {
+    match s.manager.rename(id, &body.name).await {
+        Ok(session) => (StatusCode::OK, Json(session)).into_response(),
+        Err(e) => {
+            let info = e.to_error_info();
+            error_response(
+                session_error_status(&info.code),
+                info.code.as_str(),
+                info.message.as_str(),
+            )
+        }
+    }
+}
+
+/// `POST /api/sessions/:id/activity` (#105): an agent reports its own state.
+/// The report holds above the daemon's inference for a TTL, then inference
+/// resumes — an agent that dies mid-run cannot pin its session at `Error`
+/// forever. Unknown session is 404; an unknown state value is rejected by the
+/// JSON decoder (422) rather than coerced. Answers `204 No Content`.
+async fn report_activity(
+    State(s): State<LocalApiState>,
+    Path(id): Path<Uuid>,
+    Json(body): Json<ReportActivityRequest>,
+) -> Response {
+    match s.manager.report_activity(id, body.state, body.detail).await {
         Ok(()) => StatusCode::NO_CONTENT.into_response(),
         Err(e) => {
             let info = e.to_error_info();
             error_response(
-                StatusCode::BAD_GATEWAY,
+                session_error_status(&info.code),
                 info.code.as_str(),
                 info.message.as_str(),
             )
@@ -167,33 +248,27 @@ async fn kill_session(State(s): State<LocalApiState>, Path(id): Path<Uuid>) -> R
 }
 
 fn error_response(status: StatusCode, code: &str, message: &str) -> Response {
-    (
-        status,
-        Json(serde_json::json!({
-            "error": ErrorInfo {
-                code: code.into(),
-                message: message.into(),
-            },
-        })),
-    )
-        .into_response()
+    (status, Json(ApiError::new(code, message))).into_response()
 }
 
 /// Convenience constructor — pulls the bits `LocalApiState` needs from
-/// `DaemonConfig` so callers don't have to assemble it by hand.
+/// `DaemonConfig` so callers don't have to assemble it by hand. The project
+/// scanner starts with its cache cold; wire
+/// [`ProjectScanner::start_background_refresh`](crate::projects::ProjectScanner::start_background_refresh)
+/// on the returned handle's scanner to keep it eventually fresh.
 pub fn state_for(
     manager: SessionManager,
     hostname: impl Into<String>,
     home_dir: impl Into<String>,
     presets: Vec<SpawnPreset>,
-    events: LocalEventBus,
+    projects: Arc<crate::projects::ProjectScanner>,
 ) -> LocalApiState {
     LocalApiState {
         manager,
         hostname: Arc::new(hostname.into()),
         home_dir: Arc::new(home_dir.into()),
         presets: Arc::new(presets),
-        events,
+        projects,
     }
 }
 
@@ -202,21 +277,25 @@ pub fn state_for(
 // ---------------------------------------------------------------------------
 
 #[allow(clippy::result_large_err)]
+/// Subscribing *before* the upgrade makes the 404 and the subscription one
+/// atomic step. Checking existence and then subscribing inside the callback
+/// left a window in which the liveness watcher could reap the session, so a
+/// client that passed the check still got a socket that immediately closed.
 async fn attach_ws(
     Path(id): Path<Uuid>,
     State(s): State<LocalApiState>,
     ws: axum::extract::WebSocketUpgrade,
 ) -> Result<Response, Response> {
-    if !s.manager.has(id).await {
+    let Some((replay, rx)) = s.manager.subscribe_pty_with_replay(id).await else {
         return Err(error_response(
             StatusCode::NOT_FOUND,
             "unknown_session",
             "no such session on this daemon",
         ));
-    }
+    };
     let manager = s.manager.clone();
     Ok(ws.on_upgrade(move |socket| async move {
-        let _ = crate::attach::serve(socket, manager, id).await;
+        let _ = crate::attach::serve(socket, manager, id, replay, rx).await;
     }))
 }
 
@@ -246,7 +325,7 @@ async fn pump_events(
     // Subscribe BEFORE building the snapshot so deltas applied while we're
     // marshaling can't slip between the two and disappear. The UI is
     // idempotent for repeated *Added events, so any overlap is harmless.
-    let mut rx = s.events.subscribe();
+    let mut rx = s.manager.events();
 
     let snapshot = CatalogEvent::Snapshot {
         sessions: s.manager.snapshot().await,

crates/maestro-daemon/src/local_events.rs

@@ -1,109 +0,0 @@
-//! Fan-out of session deltas for the `WS /api/events` endpoint (NAP-248).
-//!
-//! [`spawn_session_publisher`] translates the `SessionManager::events()` stream
-//! from `SessionEvent` into the matching [`CatalogEvent`] variant and publishes
-//! it here. The `WS /api/events` handler sends a one-shot `Snapshot` on connect,
-//! then forwards live deltas until the client disconnects. `Lagged` tells
-//! clients to resync via REST.
-
-use std::sync::Arc;
-
-use maestro_protocol::CatalogEvent;
-use tokio::sync::broadcast;
-
-use crate::session::{SessionEvent, SessionManager};
-
-/// Capacity of the per-bus broadcast channel. Sourced from the shared
-/// [`maestro_config::BroadcastTuning`] (NAP-273).
-const BUS_CAPACITY: usize = maestro_config::BroadcastTuning::DEFAULT.events_capacity;
-
-/// Cheap-to-clone handle around a `broadcast::Sender<CatalogEvent>`.
-#[derive(Debug, Clone)]
-pub struct LocalEventBus {
-    sender: Arc<broadcast::Sender<CatalogEvent>>,
-}
-
-impl LocalEventBus {
-    pub fn new() -> Self {
-        let (sender, _) = broadcast::channel(BUS_CAPACITY);
-        Self {
-            sender: Arc::new(sender),
-        }
-    }
-
-    /// Push an event onto the bus. No-op if there are no subscribers.
-    pub fn publish(&self, event: CatalogEvent) {
-        let _ = self.sender.send(event);
-    }
-
-    pub fn subscribe(&self) -> broadcast::Receiver<CatalogEvent> {
-        self.sender.subscribe()
-    }
-}
-
-impl Default for LocalEventBus {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-/// Spawn a task that converts each `SessionEvent` from `manager` into the
-/// matching `CatalogEvent` and publishes it on `bus`. Exits when the
-/// `SessionManager` is dropped (the events channel closes).
-pub fn spawn_session_publisher(manager: SessionManager, bus: LocalEventBus) {
-    tokio::spawn(async move {
-        let mut rx = manager.events();
-        loop {
-            match rx.recv().await {
-                Ok(SessionEvent::Added(session)) => {
-                    bus.publish(CatalogEvent::SessionAdded { session });
-                }
-                Ok(SessionEvent::Updated(session)) => {
-                    bus.publish(CatalogEvent::SessionUpdated { session });
-                }
-                Ok(SessionEvent::Removed(id)) => {
-                    bus.publish(CatalogEvent::SessionRemoved { id });
-                }
-                Err(broadcast::error::RecvError::Lagged(skipped)) => {
-                    bus.publish(CatalogEvent::Lagged { skipped });
-                }
-                Err(broadcast::error::RecvError::Closed) => return,
-            }
-        }
-    });
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[tokio::test]
-    async fn publish_visible_to_subscriber() {
-        let bus = LocalEventBus::new();
-        let mut rx = bus.subscribe();
-        bus.publish(CatalogEvent::Lagged { skipped: 7 });
-        match rx.recv().await {
-            Ok(CatalogEvent::Lagged { skipped }) => assert_eq!(skipped, 7),
-            other => panic!("unexpected: {other:?}"),
-        }
-    }
-
-    #[tokio::test]
-    async fn no_subscribers_swallows_event() {
-        let bus = LocalEventBus::new();
-        // No one's listening — `publish` must not panic and must not block.
-        bus.publish(CatalogEvent::Lagged { skipped: 1 });
-    }
-
-    #[tokio::test]
-    async fn clones_share_state() {
-        let a = LocalEventBus::new();
-        let b = a.clone();
-        let mut rx = a.subscribe();
-        b.publish(CatalogEvent::Lagged { skipped: 3 });
-        match rx.recv().await {
-            Ok(CatalogEvent::Lagged { skipped }) => assert_eq!(skipped, 3),
-            other => panic!("unexpected: {other:?}"),
-        }
-    }
-}

crates/maestro-daemon/src/panes.rs

@@ -0,0 +1,313 @@
+//! The tmux operations [`crate::session::SessionManager`] depends on.
+//!
+//! Behind a trait so the manager's *decisions* — spawn rollback ordering,
+//! liveness diffing, activity change-detection — can be exercised without
+//! forking a tmux server. [`Tmux`] is the production adapter; [`FakePanes`] is
+//! the one tests drive.
+
+use std::collections::{BTreeMap, HashMap, HashSet};
+use std::path::Path;
+use std::sync::Mutex;
+
+use uuid::Uuid;
+
+use crate::tmux::{PaneInfo, Tmux, TmuxError};
+
+/// Every tmux call the session manager makes.
+///
+/// Object-safe on purpose: `Inner` holds an `Arc<dyn Panes>` rather than a type
+/// parameter, which would otherwise spread through `LocalApiState`, `attach`
+/// and `cli`. One vtable hop is free next to a `fork`+`exec`.
+pub trait Panes: std::fmt::Debug + Send + Sync + 'static {
+    fn new_session_piped(
+        &self,
+        id: Uuid,
+        cwd: &Path,
+        command: &str,
+        session_env: &BTreeMap<String, String>,
+        sink_command: &str,
+    ) -> Result<(), TmuxError>;
+
+    fn kill_session(&self, id: Uuid) -> Result<(), TmuxError>;
+
+    fn list_sessions(&self) -> Result<Vec<Uuid>, TmuxError>;
+
+    fn pane_info(&self, id: Uuid) -> Result<Option<PaneInfo>, TmuxError>;
+
+    fn send_keys(&self, id: Uuid, bytes: &[u8]) -> Result<(), TmuxError>;
+
+    fn pipe_pane(&self, id: Uuid, sink_command: &str) -> Result<(), TmuxError>;
+
+    fn resize_window(&self, id: Uuid, cols: u16, rows: u16) -> Result<(), TmuxError>;
+
+    /// Escape-sequence snapshot of the pane's current screen, or `None` when
+    /// there is no pane to capture. See [`Tmux::capture_pane`].
+    fn capture_pane(&self, id: Uuid) -> Result<Option<Vec<u8>>, TmuxError>;
+}
+
+impl Panes for Tmux {
+    fn new_session_piped(
+        &self,
+        id: Uuid,
+        cwd: &Path,
+        command: &str,
+        session_env: &BTreeMap<String, String>,
+        sink_command: &str,
+    ) -> Result<(), TmuxError> {
+        Tmux::new_session_piped(self, id, cwd, command, session_env, sink_command)
+    }
+
+    fn kill_session(&self, id: Uuid) -> Result<(), TmuxError> {
+        Tmux::kill_session(self, id)
+    }
+
+    fn list_sessions(&self) -> Result<Vec<Uuid>, TmuxError> {
+        Tmux::list_sessions(self)
+    }
+
+    fn pane_info(&self, id: Uuid) -> Result<Option<PaneInfo>, TmuxError> {
+        Tmux::pane_info(self, id)
+    }
+
+    fn send_keys(&self, id: Uuid, bytes: &[u8]) -> Result<(), TmuxError> {
+        Tmux::send_keys(self, id, bytes)
+    }
+
+    fn pipe_pane(&self, id: Uuid, sink_command: &str) -> Result<(), TmuxError> {
+        Tmux::pipe_pane(self, id, sink_command)
+    }
+
+    fn resize_window(&self, id: Uuid, cols: u16, rows: u16) -> Result<(), TmuxError> {
+        Tmux::resize_window(self, id, cols, rows)
+    }
+
+    fn capture_pane(&self, id: Uuid) -> Result<Option<Vec<u8>>, TmuxError> {
+        Tmux::capture_pane(self, id)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Test adapter
+// ---------------------------------------------------------------------------
+
+/// Which [`Panes`] call a [`FakePanes`] expectation targets.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Op {
+    NewSessionPiped,
+    KillSession,
+    ListSessions,
+    PaneInfo,
+    SendKeys,
+    PipePane,
+    ResizeWindow,
+    CapturePane,
+}
+
+/// One recorded call, in the order the manager made it. Rollback ordering is a
+/// sequence property, so the tests that matter assert on this.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Call {
+    NewSessionPiped {
+        id: Uuid,
+        command: String,
+        env: BTreeMap<String, String>,
+    },
+    KillSession(Uuid),
+    ListSessions,
+    PaneInfo(Uuid),
+    SendKeys {
+        id: Uuid,
+        bytes: Vec<u8>,
+    },
+    PipePane(Uuid),
+    ResizeWindow {
+        id: Uuid,
+        cols: u16,
+        rows: u16,
+    },
+    CapturePane(Uuid),
+}
+
+/// In-memory [`Panes`] for tests.
+///
+/// Lives in `src/` rather than a test module because the daemon's integration
+/// tests are separate crates, which `#[cfg(test)]` cannot reach and which
+/// cannot enable a feature on their own crate.
+#[derive(Debug, Default)]
+pub struct FakePanes {
+    state: Mutex<FakeState>,
+}
+
+#[derive(Debug, Default)]
+struct FakeState {
+    live: HashSet<Uuid>,
+    panes: HashMap<Uuid, PaneInfo>,
+    calls: Vec<Call>,
+    captures: HashMap<Uuid, Vec<u8>>,
+    fail: HashMap<Op, String>,
+}
+
+impl FakePanes {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Make every call to `op` fail with `stderr`.
+    pub fn fail(&self, op: Op, stderr: impl Into<String>) {
+        self.lock().fail.insert(op, stderr.into());
+    }
+
+    /// Pretend a session exists without the manager having created it — the
+    /// recovery path's starting condition.
+    pub fn add_live(&self, id: Uuid) {
+        self.lock().live.insert(id);
+    }
+
+    /// Drop a session behind the manager's back, the way a command exiting or
+    /// an external `tmux kill-session` would.
+    pub fn remove_live(&self, id: Uuid) {
+        self.lock().live.remove(&id);
+    }
+
+    pub fn is_live(&self, id: Uuid) -> bool {
+        self.lock().live.contains(&id)
+    }
+
+    /// Screen snapshot `capture_pane` hands back for `id`. Unset means "no
+    /// pane", which is what a dead session looks like.
+    pub fn set_capture(&self, id: Uuid, bytes: impl Into<Vec<u8>>) {
+        self.lock().captures.insert(id, bytes.into());
+    }
+
+    pub fn set_pane_info(&self, id: Uuid, info: PaneInfo) {
+        self.lock().panes.insert(id, info);
+    }
+
+    /// Every call so far, in order.
+    pub fn calls(&self) -> Vec<Call> {
+        self.lock().calls.clone()
+    }
+
+    fn lock(&self) -> std::sync::MutexGuard<'_, FakeState> {
+        self.state.lock().expect("FakePanes mutex poisoned")
+    }
+
+    fn record(&self, call: Call, op: Op) -> Result<(), TmuxError> {
+        let mut st = self.lock();
+        st.calls.push(call);
+        match st.fail.get(&op) {
+            Some(stderr) => Err(TmuxError::NonZero {
+                code: 1,
+                stderr: stderr.clone(),
+            }),
+            None => Ok(()),
+        }
+    }
+}
+
+impl Panes for FakePanes {
+    fn new_session_piped(
+        &self,
+        id: Uuid,
+        _cwd: &Path,
+        command: &str,
+        session_env: &BTreeMap<String, String>,
+        _sink_command: &str,
+    ) -> Result<(), TmuxError> {
+        self.record(
+            Call::NewSessionPiped {
+                id,
+                command: command.to_owned(),
+                env: session_env.clone(),
+            },
+            Op::NewSessionPiped,
+        )?;
+        self.lock().live.insert(id);
+        Ok(())
+    }
+
+    fn kill_session(&self, id: Uuid) -> Result<(), TmuxError> {
+        self.record(Call::KillSession(id), Op::KillSession)?;
+        self.lock().live.remove(&id);
+        Ok(())
+    }
+
+    fn list_sessions(&self) -> Result<Vec<Uuid>, TmuxError> {
+        self.record(Call::ListSessions, Op::ListSessions)?;
+        Ok(self.lock().live.iter().copied().collect())
+    }
+
+    fn pane_info(&self, id: Uuid) -> Result<Option<PaneInfo>, TmuxError> {
+        self.record(Call::PaneInfo(id), Op::PaneInfo)?;
+        Ok(self.lock().panes.get(&id).cloned())
+    }
+
+    fn send_keys(&self, id: Uuid, bytes: &[u8]) -> Result<(), TmuxError> {
+        self.record(
+            Call::SendKeys {
+                id,
+                bytes: bytes.to_vec(),
+            },
+            Op::SendKeys,
+        )
+    }
+
+    fn pipe_pane(&self, id: Uuid, _sink_command: &str) -> Result<(), TmuxError> {
+        self.record(Call::PipePane(id), Op::PipePane)
+    }
+
+    fn resize_window(&self, id: Uuid, cols: u16, rows: u16) -> Result<(), TmuxError> {
+        self.record(Call::ResizeWindow { id, cols, rows }, Op::ResizeWindow)
+    }
+
+    fn capture_pane(&self, id: Uuid) -> Result<Option<Vec<u8>>, TmuxError> {
+        self.record(Call::CapturePane(id), Op::CapturePane)?;
+        let st = self.lock();
+        Ok(st.captures.get(&id).cloned())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn records_calls_in_order_and_tracks_liveness() {
+        let fake = FakePanes::new();
+        let id = Uuid::new_v4();
+
+        fake.new_session_piped(id, Path::new("/tmp"), "bash", &BTreeMap::new(), "cat >> /x")
+            .unwrap();
+        assert!(fake.is_live(id));
+        fake.kill_session(id).unwrap();
+        assert!(!fake.is_live(id));
+
+        assert_eq!(
+            fake.calls(),
+            vec![
+                Call::NewSessionPiped {
+                    id,
+                    command: "bash".into(),
+                    env: BTreeMap::new(),
+                },
+                Call::KillSession(id),
+            ]
+        );
+    }
+
+    #[test]
+    fn injected_failure_still_records_the_attempt() {
+        let fake = FakePanes::new();
+        let id = Uuid::new_v4();
+        fake.fail(Op::NewSessionPiped, "boom");
+
+        assert!(fake
+            .new_session_piped(id, Path::new("/tmp"), "bash", &BTreeMap::new(), "cat")
+            .is_err());
+        assert!(
+            !fake.is_live(id),
+            "a failed spawn must not register a session"
+        );
+        assert_eq!(fake.calls().len(), 1);
+    }
+}

crates/maestro-daemon/src/proc.rs

@@ -1,8 +1,8 @@
 //! Best-effort `/proc` inspection for the activity watcher (NAP-340, Linux).
 //!
-//! Decides whether a session is **blocked waiting on the user**: walk from the
-//! pane's process down to the deepest descendant (the agent/shell actually on
-//! the terminal) and check it's parked waiting on terminal input.
+//! Decides whether a session is **blocked waiting on the user**: ask the kernel
+//! which process group owns the terminal, then check whether any live member of
+//! that group is parked on the terminal.
 //!
 //! `/proc/<pid>/syscall` would say so exactly, but it's ptrace-gated and
 //! unreadable for our own sessions on a default kernel, so we combine three
@@ -16,55 +16,120 @@
 //! Every step degrades to `false` on a read failure, so a non-Linux host or a
 //! denied `/proc` read falls back to `Idle`.
 
-/// Whether the process tree under `pane_pid` looks blocked on terminal input
-/// from `tty` (e.g. `/dev/pts/3`) — the signal for `AwaitingInput`.
-pub fn awaiting_input(pane_pid: i32, tty: &str) -> bool {
-    let leaf = deepest_descendant(pane_pid);
+use std::collections::HashMap;
+
+/// One walk of `/proc`, shared by every session in an activity pass.
+///
+/// The foreground process group is the unit that matters, and its members are
+/// not reliably reachable from the pane: the group leader can exit while others
+/// run on, and a stage that forks a terminal-reading child and exits leaves
+/// that child reparented to init. Walking the pane's process tree misses both.
+///
+/// Snapshotting once per pass costs one `/proc` walk however many sessions the
+/// daemon owns — cheaper than the per-session `tmux list-panes` fork that
+/// already runs on the same tick.
+#[derive(Debug, Default)]
+pub struct ProcGroups {
+    stats: HashMap<i32, Stat>,
+    by_pgid: HashMap<i32, Vec<i32>>,
+}
+
+impl ProcGroups {
+    pub fn snapshot() -> Self {
+        let mut stats = HashMap::new();
+        let mut by_pgid: HashMap<i32, Vec<i32>> = HashMap::new();
+        let Ok(entries) = std::fs::read_dir("/proc") else {
+            return Self::default();
+        };
+        for pid in entries
+            .flatten()
+            .filter_map(|e| e.file_name().to_str()?.parse::<i32>().ok())
+        {
+            // A process can exit mid-walk; skipping it is the correct answer.
+            if let Some(stat) = read_stat(pid) {
+                by_pgid.entry(stat.pgrp).or_default().push(pid);
+                stats.insert(pid, stat);
+            }
+        }
+        Self { stats, by_pgid }
+    }
+
+    /// The process group the terminal considers foreground, per `tpgid`.
+    fn foreground_pgid(&self, pane_pid: i32) -> Option<i32> {
+        let tpgid = self.stats.get(&pane_pid)?.tpgid;
+        // -1 when the process has no controlling terminal.
+        (tpgid > 0).then_some(tpgid)
+    }
+
+    fn members(&self, pgid: i32) -> &[i32] {
+        self.by_pgid.get(&pgid).map_or(&[], Vec::as_slice)
+    }
+
+    fn state(&self, pid: i32) -> Option<char> {
+        self.stats.get(&pid).map(|s| s.state)
+    }
+}
+
+/// Whether the session on `tty` (e.g. `/dev/pts/3`) is blocked waiting on the
+/// user — the signal for `AwaitingInput`.
+///
+/// True when *any* member of the terminal's foreground group is parked on it: a
+/// group can hold a busy or timer-sleeping stage alongside the one actually
+/// reading, and either can be the reparented one.
+pub fn awaiting_input(pane_pid: i32, tty: &str, groups: &ProcGroups) -> bool {
+    let Some(pgid) = groups.foreground_pgid(pane_pid) else {
+        return false;
+    };
+    groups
+        .members(pgid)
+        .iter()
+        .any(|pid| parked_on_tty(*pid, tty, groups))
+}
+
+/// Whether `pid` is parked on `tty` rather than busy or sleeping on a timer.
+fn parked_on_tty(pid: i32, tty: &str, groups: &ProcGroups) -> bool {
     // Interruptible sleep is where a blocking read parks; anything else
     // (running, uninterruptible) is busy, not waiting on us.
-    if read_state(leaf) != Some('S') {
+    if groups.state(pid) != Some('S') {
         return false;
     }
     // A pure timer sleep (`sleep`, `usleep`) also sits in 'S' with the terminal
     // inherited — exclude it so it reads as Idle, not AwaitingInput.
-    if is_timer_sleep(leaf) {
+    if is_timer_sleep(pid) {
         return false;
     }
-    fd_points_at_tty(leaf, tty)
+    fd_points_at_tty(pid, tty)
 }
 
-/// Follow the (last) child link down the process tree to the deepest
-/// descendant. Bounded so a pathological/cyclic tree can't loop.
-fn deepest_descendant(pid: i32) -> i32 {
-    let mut cur = pid;
-    for _ in 0..64 {
-        match last_child(cur) {
-            Some(child) if child != cur => cur = child,
-            _ => break,
-        }
-    }
-    cur
+/// The fields of `/proc/<pid>/stat` this module needs.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct Stat {
+    state: char,
+    /// The process group this process belongs to.
+    pgrp: i32,
+    /// Foreground process group of the controlling terminal.
+    tpgid: i32,
 }
 
-/// The most-recently-created child of `pid`, via
-/// `/proc/<pid>/task/<pid>/children` (a space-separated pid list). The last
-/// entry is the newest child — typically the foreground one an agent spawned.
-fn last_child(pid: i32) -> Option<i32> {
-    let contents = std::fs::read_to_string(format!("/proc/{pid}/task/{pid}/children")).ok()?;
-    contents.split_whitespace().last()?.parse().ok()
+fn read_stat(pid: i32) -> Option<Stat> {
+    parse_stat(&std::fs::read_to_string(format!("/proc/{pid}/stat")).ok()?)
 }
 
-/// Read the process state char from `/proc/<pid>/stat`.
-fn read_state(pid: i32) -> Option<char> {
-    parse_stat_state(&std::fs::read_to_string(format!("/proc/{pid}/stat")).ok()?)
-}
-
-/// Extract the state field from a `/proc/<pid>/stat` line. The format is
-/// `pid (comm) STATE ...`; `comm` can itself contain spaces and parens, so the
-/// state is the first non-space char *after the final `)`*.
-fn parse_stat_state(stat: &str) -> Option<char> {
+/// Parse the fields after `comm` from a `/proc/<pid>/stat` line.
+///
+/// The format is `pid (comm) state ppid pgrp session tty_nr tpgid ...`, and
+/// `comm` can itself contain spaces and parens — so everything is indexed from
+/// the *final* `)`, never by splitting the whole line.
+fn parse_stat(stat: &str) -> Option<Stat> {
     let close = stat.rfind(')')?;
-    stat[close + 1..].trim_start().chars().next()
+    let mut rest = stat[close + 1..].split_whitespace();
+    let state = rest.next()?.chars().next()?;
+    let _ppid = rest.next()?;
+    let pgrp = rest.next()?.parse().ok()?;
+    let _session = rest.next()?;
+    let _tty_nr = rest.next()?;
+    let tpgid = rest.next()?.parse().ok()?;
+    Some(Stat { state, pgrp, tpgid })
 }
 
 /// Whether `pid`'s `wchan` (the kernel symbol it's blocked in) is a timer
@@ -94,19 +159,51 @@ fn fd_points_at_tty(pid: i32, tty: &str) -> bool {
 mod tests {
     use super::*;
 
-    #[test]
-    fn parse_stat_state_handles_simple_and_tricky_comm() {
-        assert_eq!(parse_stat_state("1234 (bash) S 1 1234 ..."), Some('S'));
-        assert_eq!(parse_stat_state("1234 (sleep) S 1 ..."), Some('S'));
-        assert_eq!(parse_stat_state("99 (cat) R 1 ..."), Some('R'));
-        // comm with spaces and a paren — only the final ')' delimits it.
-        assert_eq!(parse_stat_state("42 (weird (name)) D 1 42 ..."), Some('D'));
+    /// `pid (comm) state ppid pgrp session tty_nr tpgid …`
+    fn stat_line(comm: &str, state: char, tpgid: i32) -> String {
+        stat_line_pgrp(comm, state, 1234, tpgid)
+    }
+
+    fn stat_line_pgrp(comm: &str, state: char, pgrp: i32, tpgid: i32) -> String {
+        format!("1234 ({comm}) {state} 1000 {pgrp} 1234 34816 {tpgid} 4194304 …")
     }
 
     #[test]
-    fn parse_stat_state_rejects_garbage() {
-        assert_eq!(parse_stat_state("not a stat line"), None);
-        assert_eq!(parse_stat_state("123 (comm)"), None);
+    fn parse_stat_reads_state_pgrp_and_tpgid() {
+        let s = parse_stat(&stat_line_pgrp("bash", 'S', 500, 4321)).unwrap();
+        assert_eq!(s.state, 'S');
+        assert_eq!(s.pgrp, 500);
+        assert_eq!(s.tpgid, 4321);
+
+        let r = parse_stat(&stat_line_pgrp("cat", 'R', 7, 99)).unwrap();
+        assert_eq!(r.state, 'R');
+        assert_eq!(r.pgrp, 7);
+        assert_eq!(r.tpgid, 99);
+    }
+
+    /// `comm` is attacker-adjacent: it is the process name, it can contain
+    /// spaces and parens, and splitting the whole line on whitespace would put
+    /// every later field at the wrong index.
+    #[test]
+    fn parse_stat_indexes_from_the_final_paren() {
+        let s = parse_stat(&stat_line_pgrp("weird (name) with spaces", 'D', 42, 777)).unwrap();
+        assert_eq!(s.state, 'D');
+        assert_eq!(s.pgrp, 42);
+        assert_eq!(s.tpgid, 777);
+    }
+
+    #[test]
+    fn parse_stat_carries_the_no_terminal_sentinel() {
+        // -1 means no controlling terminal; `foreground_pid` rejects it.
+        assert_eq!(parse_stat(&stat_line("daemon", 'S', -1)).unwrap().tpgid, -1);
+    }
+
+    #[test]
+    fn parse_stat_rejects_garbage() {
+        assert!(parse_stat("not a stat line").is_none());
+        assert!(parse_stat("123 (comm)").is_none());
+        // Truncated before tpgid.
+        assert!(parse_stat("123 (comm) S 1 1 1").is_none());
     }
 
     #[test]
@@ -121,9 +218,46 @@ mod tests {
         assert!(!is_timer_wchan("0"));
     }
 
+    /// The snapshot indexes by process group, not by parentage — that is the
+    /// whole point, since a group member need not be under the pane. Checked
+    /// against this process's own group, which certainly has a live member.
+    #[test]
+    fn snapshot_indexes_this_process_under_its_group() {
+        // SAFETY: argument-less query of the caller's own process group.
+        let own = unsafe { libc::getpgid(0) };
+        assert!(own > 0, "expected a real process group, got {own}");
+
+        let groups = ProcGroups::snapshot();
+        let me = std::process::id() as i32;
+        assert!(
+            groups.members(own).contains(&me),
+            "snapshot missed this process ({me}) in group {own}: {:?}",
+            groups.members(own)
+        );
+        assert!(
+            groups.state(me).is_some(),
+            "a process in the snapshot must carry its state"
+        );
+    }
+
+    #[test]
+    fn snapshot_has_no_members_for_a_group_that_cannot_exist() {
+        assert!(ProcGroups::snapshot().members(i32::MAX).is_empty());
+    }
+
+    #[test]
+    fn a_pid_with_no_controlling_terminal_has_no_foreground_group() {
+        let groups = ProcGroups::snapshot();
+        assert_eq!(groups.foreground_pgid(i32::MAX), None);
+    }
+
     #[test]
     fn awaiting_input_is_false_for_nonexistent_pid() {
-        // A pid that can't exist → every read fails → false (fall back to Idle).
-        assert!(!awaiting_input(i32::MAX, "/dev/pts/0"));
+        // A pid that can't exist → not in the snapshot → false (falls back to Idle).
+        assert!(!awaiting_input(
+            i32::MAX,
+            "/dev/pts/0",
+            &ProcGroups::snapshot()
+        ));
     }
 }

crates/maestro-daemon/src/projects.rs

@@ -0,0 +1,574 @@
+//! Project discovery for `GET /api/projects` (#54).
+//!
+//! Scans `[spawn].project_roots` (default the whole home) for `.git` entries —
+//! directory or file, so linked worktrees count too — up to
+//! `[spawn].project_scan_depth` levels. Descent stops at the first repo found:
+//! nested independent repos are not discovered, but worktrees of every hit
+//! still are, via `git worktree list`, which also catches linked worktrees
+//! living outside the roots.
+//!
+//! Hidden directories are skipped everywhere; heavy well-known directories
+//! (`node_modules`, `Downloads`, …) are skipped when they sit directly in the
+//! home directory, so scanning all of home stays cheap.
+//!
+//! Results are cached behind a short TTL and refreshed on a slow background
+//! timer ([`ProjectScanner::start_background_refresh`]) — repositories appear
+//! rarely, and `/api/projects` may be polled.
+
+use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant};
+
+use chrono::{DateTime, Utc};
+
+use crate::spawn_history::RecentDir;
+
+/// Directory names never descended when they sit directly in the home dir, so
+/// scanning all of home stays cheap (#54). Hidden dirs are skipped everywhere
+/// regardless.
+pub const DEFAULT_HOME_IGNORE: &[&str] =
+    &["node_modules", "Downloads", "Library", "go", "snap", "opt"];
+
+/// How long a discovery snapshot is served as-is before the next request
+/// triggers a rescan.
+///
+/// A scan walks the roots and runs one `git worktree list` per hit, holding
+/// the scanner lock throughout, and clients re-request whenever a draft pane
+/// re-mounts — which `multiview.render()` does on unrelated events. Keep this
+/// comfortably longer than [`REFRESH_INTERVAL`] so the background timer is
+/// what refreshes, and a request only rescans when that timer has failed to.
+pub const CACHE_TTL: Duration = Duration::from_secs(180);
+/// Background refresh cadence. Repositories appear rarely; this keeps the
+/// served list eventually fresh without anyone asking.
+pub const REFRESH_INTERVAL: Duration = Duration::from_secs(60);
+
+/// One repository or linked worktree found by [`discover`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DiscoveredRepo {
+    pub path: PathBuf,
+    /// Basename of `path`.
+    pub name: String,
+    pub is_worktree: bool,
+    /// The main checkout this worktree belongs to; set only when
+    /// [`Self::is_worktree`].
+    pub base_repo: Option<PathBuf>,
+    /// Mtime of the checkout's git HEAD — "someone committed / checked out
+    /// here". The later-of merge with spawn history happens in
+    /// [`to_projects`], which also sorts.
+    pub head_mtime: Option<DateTime<Utc>>,
+}
+
+/// Repo toplevels under each root of `roots`, at most `max_depth` levels deep.
+/// A dir holding `.git` (dir *or* file) is a hit and is not descended into;
+/// hidden directories are never entered, and `DEFAULT_HOME_IGNORE` names are
+/// skipped directly under `home`.
+pub fn scan_roots(roots: &[PathBuf], max_depth: u32, home: &Path) -> Vec<PathBuf> {
+    let mut found = Vec::new();
+    for root in roots {
+        walk(root, 0, max_depth, home, &mut found);
+    }
+    found.sort();
+    found.dedup();
+    found
+}
+
+fn walk(dir: &Path, depth: u32, max_depth: u32, home: &Path, found: &mut Vec<PathBuf>) {
+    let entries = match std::fs::read_dir(dir) {
+        Ok(e) => e,
+        Err(_) => return,
+    };
+    let mut subdirs = Vec::new();
+    let mut has_git = false;
+    for entry in entries.flatten() {
+        match entry.file_name().to_string_lossy().into_owned() {
+            name if name == ".git" => has_git = true,
+            name if name.starts_with('.') => {}
+            name if dir == home && DEFAULT_HOME_IGNORE.contains(&name.as_str()) => {}
+            _ => {
+                if entry.file_type().map(|t| t.is_dir()).unwrap_or(false) {
+                    subdirs.push(entry.path());
+                }
+            }
+        }
+    }
+    if has_git {
+        // Match `git worktree list` output, which prints real paths.
+        found.push(std::fs::canonicalize(dir).unwrap_or_else(|_| dir.to_path_buf()));
+        return;
+    }
+    if depth >= max_depth {
+        return;
+    }
+    for sub in subdirs {
+        walk(&sub, depth + 1, max_depth, home, found);
+    }
+}
+
+/// Every discovered project: the scanned repos plus all worktrees their
+/// `git worktree list` reports (linked worktrees can live outside the roots).
+/// A hit whose git invocation fails still lists, un-worktreed.
+pub fn discover(roots: &[PathBuf], max_depth: u32, home: &Path) -> Vec<DiscoveredRepo> {
+    let scanned = scan_roots(roots, max_depth, home);
+    let mut map: Vec<(PathBuf, PathBuf)> = Vec::new(); // (checkout, main)
+    for repo in scanned {
+        if map.iter().any(|(c, _)| c == &repo) {
+            continue;
+        }
+        let worktrees = list_worktrees(&repo).unwrap_or_else(|| vec![repo.clone()]);
+        let main = worktrees[0].clone();
+        for wt in worktrees {
+            if !map.iter().any(|(c, _)| c == &wt) {
+                map.push((wt, main.clone()));
+            }
+        }
+    }
+    map.into_iter()
+        .map(|(path, main)| {
+            let is_worktree = path != main;
+            DiscoveredRepo {
+                name: path
+                    .file_name()
+                    .map(|n| n.to_string_lossy().into_owned())
+                    .unwrap_or_default(),
+                is_worktree,
+                base_repo: is_worktree.then_some(main),
+                head_mtime: head_mtime(&path),
+                path,
+            }
+        })
+        .collect()
+}
+
+/// `git worktree list --porcelain` from `repo`: absolute paths, main first.
+/// `None` when git fails (broken/bare checkout).
+fn list_worktrees(repo: &Path) -> Option<Vec<PathBuf>> {
+    let out = std::process::Command::new("git")
+        .arg("-C")
+        .arg(repo)
+        .args(["worktree", "list", "--porcelain"])
+        .output()
+        .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    let mut paths = Vec::new();
+    for line in String::from_utf8_lossy(&out.stdout).lines() {
+        if let Some(p) = line.strip_prefix("worktree ") {
+            paths.push(PathBuf::from(p));
+        }
+    }
+    (!paths.is_empty()).then_some(paths)
+}
+
+/// Mtime of the checkout's reflog, falling back to `HEAD` itself.
+///
+/// `HEAD` is only rewritten on checkout — committing updates
+/// `refs/heads/<branch>` and appends to `logs/HEAD`, leaving `HEAD` alone. A
+/// repo worked on daily from one long-lived branch would otherwise report its
+/// last *branch switch* as its activity and get dimmed as stale (#54 review).
+///
+/// For a linked worktree `.git` is a file holding a `gitdir:` pointer;
+/// resolve it so worktrees report their own reflog rather than nothing.
+fn head_mtime(repo: &Path) -> Option<DateTime<Utc>> {
+    let dot_git = repo.join(".git");
+    let head = if dot_git.is_dir() {
+        dot_git.join("HEAD")
+    } else {
+        let ptr = std::fs::read_to_string(&dot_git).ok()?;
+        let gitdir = ptr.trim().strip_prefix("gitdir:")?.trim();
+        // Relative pointers are relative to the worktree.
+        let p = Path::new(gitdir);
+        let p = if p.is_absolute() {
+            p.to_path_buf()
+        } else {
+            repo.join(p)
+        };
+        p.join("HEAD")
+    };
+    // Prefer the reflog next to whichever HEAD we resolved.
+    let reflog = head.with_file_name("logs").join("HEAD");
+    let head = if reflog.exists() { reflog } else { head };
+    let mtime = std::fs::metadata(head).ok()?.modified().ok()?;
+    Some(DateTime::<Utc>::from(mtime))
+}
+
+/// Fold spawn history into the discovery snapshot and produce the wire list,
+/// sorted newest-activity-first. `history` must be newest-first (what
+/// [`SpawnHistory::all_recent_dirs`](crate::spawn_history::SpawnHistory)
+/// returns): the first entry whose cwd sits inside a project is its most
+/// recent use.
+pub fn to_projects(
+    repos: &[DiscoveredRepo],
+    history: &[RecentDir],
+) -> Vec<maestro_protocol::Project> {
+    let mut projects: Vec<maestro_protocol::Project> = repos
+        .iter()
+        .map(|repo| {
+            let last_use = history.iter().find(|h| contains(&repo.path, &h.cwd));
+            maestro_protocol::Project {
+                path: repo.path.clone(),
+                name: repo.name.clone(),
+                is_worktree: repo.is_worktree,
+                base_repo: repo.base_repo.clone(),
+                last_activity: max_opt(repo.head_mtime, last_use.map(|u| u.last_used)),
+                last_command: last_use.map(|u| u.last_command.clone()),
+            }
+        })
+        .collect();
+    projects.sort_by_key(|p| std::cmp::Reverse(p.last_activity));
+    projects
+}
+
+/// Whether `dir` is `project` itself or anywhere inside it.
+fn contains(project: &Path, dir: &Path) -> bool {
+    dir == project || dir.starts_with(project)
+}
+
+fn max_opt(a: Option<DateTime<Utc>>, b: Option<DateTime<Utc>>) -> Option<DateTime<Utc>> {
+    match (a, b) {
+        (Some(a), Some(b)) => Some(a.max(b)),
+        (a, b) => a.or(b),
+    }
+}
+
+/// Cached discovery behind a short TTL plus an optional slow background
+/// refresh. Clone-free shared handle via `Arc` in [`crate::local_api`].
+#[derive(Debug)]
+pub struct ProjectScanner {
+    roots: Vec<PathBuf>,
+    max_depth: u32,
+    home: PathBuf,
+    ttl: Duration,
+    cache: tokio::sync::Mutex<Option<(Instant, std::sync::Arc<Vec<DiscoveredRepo>>)>>,
+}
+
+impl ProjectScanner {
+    /// Scanner over the resolved config roots. An empty `roots` list scans
+    /// nothing and always serves an empty list.
+    pub fn new(roots: Vec<PathBuf>, max_depth: u32, home: PathBuf) -> Self {
+        Self {
+            roots,
+            max_depth,
+            home,
+            ttl: CACHE_TTL,
+            cache: tokio::sync::Mutex::new(None),
+        }
+    }
+
+    /// Scanner that never discovers anything — tests and embedders that don't
+    /// want the endpoint populated.
+    pub fn disabled() -> Self {
+        Self::new(Vec::new(), 0, PathBuf::new())
+    }
+
+    /// Cached snapshot, rescanning (off-thread) when the TTL has lapsed.
+    /// Also the background timer's entry point: a tick inside the TTL is a
+    /// no-op (#75).
+    pub async fn repos(&self) -> std::sync::Arc<Vec<DiscoveredRepo>> {
+        let mut cache = self.cache.lock().await;
+        if let Some((at, repos)) = cache.as_ref() {
+            if at.elapsed() < self.ttl {
+                return repos.clone();
+            }
+        }
+        let roots = self.roots.clone();
+        let max_depth = self.max_depth;
+        let home = self.home.clone();
+        // Blocking fs walk + git subprocesses must not stall the reactor.
+        let repos = std::sync::Arc::new(
+            tokio::task::spawn_blocking(move || discover(&roots, max_depth, &home))
+                .await
+                .unwrap_or_default(),
+        );
+        *cache = Some((Instant::now(), repos.clone()));
+        repos
+    }
+
+    /// One background-refresh tick: rescan only if the cached snapshot has
+    /// passed its TTL (#75) — the timer used to bypass it and re-walk the
+    /// roots every [`REFRESH_INTERVAL`].
+    async fn refresh(&self) {
+        self.repos().await;
+    }
+
+    /// Spawn the slow background refresh task. Drop the returned handle to
+    /// detach it; it stops when the runtime shuts down.
+    pub fn start_background_refresh(self: &std::sync::Arc<Self>) -> tokio::task::JoinHandle<()> {
+        let scanner = std::sync::Arc::clone(self);
+        tokio::spawn(async move {
+            let mut ticker = tokio::time::interval(REFRESH_INTERVAL);
+            ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
+            ticker.tick().await; // the immediate first tick — wait a full interval
+            loop {
+                scanner.refresh().await;
+                ticker.tick().await;
+            }
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::spawn_history::RecentDir;
+
+    /// Real git repo at `<root>/<name>`, one initial commit so HEAD exists.
+    fn make_repo(root: &Path, name: &str) -> PathBuf {
+        let path = root.join(name);
+        std::fs::create_dir_all(&path).unwrap();
+        run_git(&path, &["init", "-q"]);
+        std::fs::write(path.join("f.txt"), "x\n").unwrap();
+        run_git(&path, &["add", "-A"]);
+        run_git(
+            &path,
+            &[
+                "-c",
+                "user.email=t@t",
+                "-c",
+                "user.name=t",
+                "commit",
+                "-qm",
+                "init",
+            ],
+        );
+        path
+    }
+
+    fn run_git(dir: &Path, args: &[&str]) {
+        let out = std::process::Command::new("git")
+            .arg("-C")
+            .arg(dir)
+            .args(args)
+            .output()
+            .unwrap();
+        assert!(
+            out.status.success(),
+            "git {args:?} failed: {} | {}",
+            String::from_utf8_lossy(&out.stderr),
+            String::from_utf8_lossy(&out.stdout)
+        );
+    }
+
+    fn names(repos: &[DiscoveredRepo]) -> Vec<String> {
+        let mut v: Vec<String> = repos.iter().map(|r| r.name.clone()).collect();
+        v.sort();
+        v
+    }
+
+    #[test]
+    fn scan_finds_repos_and_stops_at_the_first_hit() {
+        let tmp = tempfile::tempdir().unwrap();
+        let outer = make_repo(tmp.path(), "outer");
+        // A nested independent repo inside `outer` is NOT discovered
+        // separately: descent stops once a repo is found.
+        make_repo(&outer, "vendored");
+        std::fs::create_dir_all(tmp.path().join("plain/deep/deeper")).unwrap();
+
+        let found = scan_roots(
+            &[tmp.path().to_path_buf()],
+            3,
+            Path::new("/nonexistent-home"),
+        );
+        assert_eq!(found, vec![outer]);
+
+        let discovered = discover(
+            &[tmp.path().to_path_buf()],
+            3,
+            Path::new("/nonexistent-home"),
+        );
+        assert_eq!(names(&discovered), ["outer"]);
+        assert!(!discovered[0].is_worktree);
+        assert_eq!(discovered[0].base_repo, None);
+        assert!(discovered[0].head_mtime.is_some());
+    }
+
+    #[test]
+    fn scan_respects_depth_hidden_dirs_and_home_ignore() {
+        let tmp = tempfile::tempdir().unwrap();
+        let home = tmp.path().join("home");
+
+        // Hidden dirs are never entered, at any depth.
+        std::fs::create_dir_all(home.join(".secret/.git")).unwrap();
+        // node_modules directly under home is not descended…
+        let _ignored = make_repo(&home.join("node_modules"), "dep");
+        // …but the same name deeper down is fair game.
+        let kept = make_repo(&home.join("code/node_modules"), "dep2");
+
+        // Depth cap: a repo three levels below the root is the last tier —
+        // found at depth 3, but a fourth-level repo isn't.
+        let at_three = home.join("a/b/c");
+        std::fs::create_dir_all(at_three.join(".git")).unwrap();
+        std::fs::create_dir_all(home.join("a/b/c/d/.git")).unwrap();
+
+        let found = scan_roots(std::slice::from_ref(&home), 3, &home);
+        assert!(found.iter().all(|p| !p.starts_with(home.join(".secret"))));
+        assert!(found
+            .iter()
+            .all(|p| !p.starts_with(home.join("node_modules"))));
+        assert!(found.contains(&kept.canonicalize().unwrap()));
+        assert!(found.contains(&at_three.canonicalize().unwrap()));
+        assert!(!found.iter().any(|p| p.ends_with("d")));
+    }
+
+    #[test]
+    fn worktrees_outside_the_roots_are_discovered_via_git_worktree_list() {
+        let tmp = tempfile::tempdir().unwrap();
+        let root = tmp.path().join("scan-root");
+        std::fs::create_dir_all(&root).unwrap();
+        let main = make_repo(&root, "main-repo");
+        // Linked worktree deliberately outside the scan root.
+        let wt = tmp.path().join("elsewhere/wt-of-main");
+        std::fs::create_dir_all(wt.parent().unwrap()).unwrap();
+        run_git(
+            &main,
+            &[
+                "worktree",
+                "add",
+                "-q",
+                "-b",
+                "feature",
+                &wt.to_string_lossy(),
+            ],
+        );
+
+        let discovered = discover(&[root], 3, Path::new("/nonexistent-home"));
+        assert_eq!(names(&discovered), ["main-repo", "wt-of-main"]);
+        let wt_entry = discovered.iter().find(|d| d.name == "wt-of-main").unwrap();
+        assert!(wt_entry.is_worktree);
+        assert_eq!(
+            wt_entry.base_repo.as_deref(),
+            Some(main.canonicalize().unwrap().as_path())
+        );
+        let main_entry = discovered.iter().find(|d| d.name == "main-repo").unwrap();
+        assert!(!main_entry.is_worktree);
+    }
+
+    #[test]
+    fn head_mtime_resolves_a_worktrees_git_file_pointer() {
+        let tmp = tempfile::tempdir().unwrap();
+        let main = make_repo(tmp.path(), "m");
+        let wt = tmp.path().join("wt");
+        run_git(
+            &main,
+            &["worktree", "add", "-q", "-b", "b2", &wt.to_string_lossy()],
+        );
+        assert!(head_mtime(&wt).is_some());
+    }
+
+    fn recent(cwd: &str, cmd: &str, at: &str) -> RecentDir {
+        RecentDir {
+            cwd: PathBuf::from(cwd),
+            last_command: cmd.into(),
+            last_used: DateTime::parse_from_rfc3339(at)
+                .unwrap()
+                .with_timezone(&Utc),
+        }
+    }
+
+    #[test]
+    fn to_projects_merges_history_and_sorts_newest_first() {
+        let repo_old = DiscoveredRepo {
+            path: PathBuf::from("/w/old"),
+            name: "old".into(),
+            is_worktree: false,
+            base_repo: None,
+            // Committed recently but never spawned in.
+            head_mtime: Some(t("2026-08-23T10:00:00Z")),
+        };
+        let repo_hist = DiscoveredRepo {
+            path: PathBuf::from("/w/hist"),
+            name: "hist".into(),
+            is_worktree: false,
+            base_repo: None,
+            // Old commit…
+            head_mtime: Some(t("2026-08-01T10:00:00Z")),
+        };
+        let repo_stale = DiscoveredRepo {
+            path: PathBuf::from("/w/stale"),
+            name: "stale".into(),
+            is_worktree: false,
+            base_repo: None,
+            head_mtime: None,
+        };
+
+        let history = vec![
+            // Newest overall: a subdir of /w/hist (first match wins for it).
+            recent("/w/hist/crates", "opencode", "2026-08-22T09:00:00Z"),
+            recent("/w/hist", "claude", "2026-08-20T09:00:00Z"),
+        ];
+        let projects = to_projects(&[repo_old, repo_hist, repo_stale], &history);
+
+        let paths: Vec<&str> = projects.iter().map(|p| p.path.to_str().unwrap()).collect();
+        assert_eq!(paths, ["/w/old", "/w/hist", "/w/stale"]);
+
+        // old: git activity wins (never spawned).
+        assert_eq!(projects[0].last_activity, Some(t("2026-08-23T10:00:00Z")));
+        assert_eq!(projects[0].last_command, None);
+        // hist: spawn history beats the old commit; command from the newest
+        // matching entry (the crates/ one, not the repo root one).
+        assert_eq!(projects[1].last_activity, Some(t("2026-08-22T09:00:00Z")));
+        assert_eq!(projects[1].last_command.as_deref(), Some("opencode"));
+        // stale: neither source knows anything.
+        assert_eq!(projects[2].last_activity, None);
+        assert_eq!(projects[2].last_command, None);
+    }
+
+    fn t(s: &str) -> DateTime<Utc> {
+        DateTime::parse_from_rfc3339(s).unwrap().with_timezone(&Utc)
+    }
+
+    #[tokio::test]
+    async fn scanner_caches_within_ttl_and_rescans_after() {
+        let tmp = tempfile::tempdir().unwrap();
+        let mut scanner = ProjectScanner::new(
+            vec![tmp.path().to_path_buf()],
+            3,
+            PathBuf::from("/nonexistent"),
+        );
+
+        let empty = scanner.repos().await;
+        assert!(empty.is_empty());
+
+        make_repo(tmp.path(), "late");
+        // Within the TTL the cached (empty) snapshot is still served.
+        let still_empty = scanner.repos().await;
+        assert!(still_empty.is_empty());
+
+        // After the TTL lapses the rescan sees the new repo.
+        scanner.ttl = Duration::ZERO;
+        let fresh = scanner.repos().await;
+        assert_eq!(fresh.len(), 1);
+        assert_eq!(fresh[0].name, "late");
+    }
+
+    #[tokio::test]
+    async fn background_refresh_honours_the_ttl() {
+        let tmp = tempfile::tempdir().unwrap();
+        let mut scanner = ProjectScanner::new(
+            vec![tmp.path().to_path_buf()],
+            3,
+            PathBuf::from("/nonexistent"),
+        );
+
+        let empty = scanner.repos().await;
+        assert!(empty.is_empty());
+
+        make_repo(tmp.path(), "late");
+        // A background tick inside the TTL must not re-walk the filesystem:
+        // the new repo stays invisible until the cache expires.
+        scanner.refresh().await;
+        assert!(scanner.repos().await.is_empty());
+
+        // Once the TTL lapses, the next tick picks it up.
+        scanner.ttl = Duration::ZERO;
+        scanner.refresh().await;
+        let fresh = scanner.repos().await;
+        assert_eq!(fresh.len(), 1);
+        assert_eq!(fresh[0].name, "late");
+    }
+
+    #[test]
+    fn disabled_scanner_always_serves_empty() {
+        let scanner = ProjectScanner::disabled();
+        assert_eq!(scanner.roots, Vec::<PathBuf>::new());
+    }
+}

crates/maestro-daemon/src/pty.rs

@@ -39,9 +39,9 @@ use tokio::task::JoinHandle;
 
 /// How many recent PTY frames each new subscriber inherits before starting to
 /// receive live frames. A small buffer is fine — clients render a fresh
-/// terminal anyway. Sourced from the shared [`maestro_config::BroadcastTuning`]
+/// terminal anyway. Sourced from [`maestro_config::PTY_CAPACITY`]
 /// (NAP-273).
-pub const PTY_BROADCAST_CAPACITY: usize = maestro_config::BroadcastTuning::DEFAULT.pty_capacity;
+pub const PTY_BROADCAST_CAPACITY: usize = maestro_config::PTY_CAPACITY;
 
 /// Default replay-buffer size — roughly one screenful for a typical 24×80
 /// terminal plus reasonable scrollback. Override via
@@ -58,7 +58,9 @@ const READ_BUF_BYTES: usize = 4096;
 #[derive(Debug)]
 pub struct PtyBridge {
     fifo_path: PathBuf,
-    sender: broadcast::Sender<Vec<u8>>,
+    /// `None` once [`Self::seal`] has run: live subscribers see the channel
+    /// close, but the replay buffer stays readable.
+    sender: Option<broadcast::Sender<Vec<u8>>>,
     replay: ReplayBuffer,
     /// Monotonic timestamp of the last non-empty read off the FIFO, bumped by
     /// `run_reader`. The activity watcher reads it to gauge PTY quiescence
@@ -100,7 +102,7 @@ impl PtyBridge {
         });
         Ok(Self {
             fifo_path,
-            sender,
+            sender: Some(sender),
             replay,
             last_activity,
             task,
@@ -123,7 +125,14 @@ impl PtyBridge {
     /// Subscribe to live PTY frames. Use [`Self::subscribe_with_replay`] for
     /// new attaches that want the buffered scrollback first.
     pub fn subscribe(&self) -> broadcast::Receiver<Vec<u8>> {
-        self.sender.subscribe()
+        match &self.sender {
+            Some(tx) => tx.subscribe(),
+            None => {
+                let (tx, rx) = broadcast::channel(1);
+                drop(tx);
+                rx
+            }
+        }
     }
 
     /// Atomically snapshot the replay buffer and return a fresh subscriber
@@ -132,12 +141,45 @@ impl PtyBridge {
     /// `subscribe()` keeps the reader task from publishing in between, so
     /// the seam has no gap and no duplicates.
     pub fn subscribe_with_replay(&self) -> (Vec<u8>, broadcast::Receiver<Vec<u8>>) {
+        self.subscribe_with_snapshot(|| None)
+    }
+
+    /// As [`Self::subscribe_with_replay`], but lets the caller supply the
+    /// replay payload instead of the raw byte buffer — used to hand a fresh
+    /// client tmux's own view of the screen, which the byte tail cannot
+    /// reconstruct for a full-screen program. `capture` runs while the reader
+    /// is held off, so the payload and the live stream still meet with no gap
+    /// and no duplicate. Returning `None` falls back to the byte buffer.
+    pub fn subscribe_with_snapshot<F>(&self, capture: F) -> (Vec<u8>, broadcast::Receiver<Vec<u8>>)
+    where
+        F: FnOnce() -> Option<Vec<u8>>,
+    {
         let guard = self.replay.lock_for_snapshot();
-        let snapshot = guard.snapshot();
-        let rx = self.sender.subscribe();
+        let snapshot = capture().unwrap_or_else(|| guard.snapshot());
+        let rx = match &self.sender {
+            Some(tx) => tx.subscribe(),
+            // Sealed: hand back the scrollback plus a receiver that is already
+            // closed, so the client renders the final output and then sees the
+            // stream end rather than hanging.
+            None => {
+                let (tx, rx) = broadcast::channel(1);
+                drop(tx);
+                rx
+            }
+        };
         drop(guard);
         (snapshot, rx)
     }
+
+    /// Stop reading and close the live stream, keeping the replay buffer.
+    ///
+    /// Attached clients see the channel close — without that a `maestro attach`
+    /// sits in raw mode against a shell that has exited (NAP-226) — while the
+    /// buffered output survives for anyone who attaches later.
+    pub fn seal(&mut self) {
+        self.task.abort();
+        self.sender = None;
+    }
 }
 
 impl Drop for PtyBridge {

crates/maestro-daemon/src/spawn_history.rs

@@ -143,11 +143,23 @@ impl SpawnHistory {
     /// Recent working dirs, newest use first, deduped by `cwd`, within the
     /// recency cap, capped at `max_results`. Empty when disabled or unreadable.
     pub fn recent_dirs(&self) -> Vec<RecentDir> {
-        self.recent_dirs_as_of(Utc::now())
+        self.recent_dirs_capped(Utc::now(), self.max_results)
+    }
+
+    /// Every deduped recent dir, newest-first, without the picker's result
+    /// cap (#54): project enrichment folds the whole history, not its first
+    /// page, so a project spawned in long ago still reads as fresh.
+    pub fn all_recent_dirs(&self) -> Vec<RecentDir> {
+        self.recent_dirs_capped(Utc::now(), usize::MAX)
     }
 
     /// [`recent_dirs`](Self::recent_dirs) with an explicit clock for testing.
+    #[cfg(test)]
     fn recent_dirs_as_of(&self, now: DateTime<Utc>) -> Vec<RecentDir> {
+        self.recent_dirs_capped(now, self.max_results)
+    }
+
+    fn recent_dirs_capped(&self, now: DateTime<Utc>, max_results: usize) -> Vec<RecentDir> {
         if !self.is_enabled() {
             return Vec::new();
         }
@@ -168,7 +180,7 @@ impl SpawnHistory {
                 last_command: rec.command,
                 last_used: rec.at,
             });
-            if out.len() >= self.max_results {
+            if out.len() >= max_results {
                 break;
             }
         }
@@ -362,4 +374,28 @@ mod tests {
         assert_eq!(recents[0].cwd, PathBuf::from("/d4"));
         assert_eq!(recents[1].cwd, PathBuf::from("/d3"));
     }
+
+    /// Project enrichment (#54) folds the whole log, not just the picker's
+    /// first page.
+    #[test]
+    fn all_recent_dirs_skips_the_result_cap() {
+        let tmp = tempfile::tempdir().unwrap();
+        let mut h = SpawnHistory::new(tmp.path().join("h.jsonl"), 30);
+        h.max_results = 2;
+        // Recent enough to survive the 30-day cap against the real clock.
+        let base = Utc::now() - Duration::hours(1);
+        for i in 0..5 {
+            h.append(&rec(
+                &format!("/d{i}"),
+                "claude",
+                base + Duration::minutes(i),
+            ))
+            .unwrap();
+        }
+        assert_eq!(h.recent_dirs().len(), 2);
+        let all = h.all_recent_dirs();
+        assert_eq!(all.len(), 5);
+        assert_eq!(all[0].cwd, PathBuf::from("/d4"));
+        assert_eq!(all[4].cwd, PathBuf::from("/d0"));
+    }
 }

crates/maestro-daemon/src/tmux.rs

@@ -3,6 +3,7 @@
 //! All sessions managed through this wrapper are named `maestro-<uuid>` so that
 //! the daemon can recover its own sessions on restart (and ignore foreign ones).
 
+use std::collections::BTreeMap;
 use std::env;
 use std::ffi::{OsStr, OsString};
 use std::os::unix::ffi::OsStrExt;
@@ -75,6 +76,10 @@ impl Tmux {
         if let Some(d) = &self.tmpdir {
             c.env("TMUX_TMPDIR", d);
         }
+        // A daemon started from inside a tmux pane inherits `TMUX`, and tmux
+        // resolves that ahead of `TMUX_TMPDIR` — so without this the daemon
+        // drives the developer's own server and `tmux_tmpdir` does nothing.
+        c.env_remove("TMUX");
         c
     }
 
@@ -96,7 +101,13 @@ impl Tmux {
         let command = login_shell_command(env::var_os("SHELL").as_deref(), command);
         let out = self
             .cmd()
-            .args(new_session_args(&name, cwd, &command, None))
+            .args(new_session_args(
+                &name,
+                cwd,
+                &command,
+                &BTreeMap::new(),
+                None,
+            ))
             .output()?;
         check(out)
     }
@@ -112,13 +123,20 @@ impl Tmux {
         id: Uuid,
         cwd: &Path,
         command: &str,
+        session_env: &BTreeMap<String, String>,
         sink_command: &str,
     ) -> Result<(), TmuxError> {
         let name = session_name(id);
         let command = login_shell_command(env::var_os("SHELL").as_deref(), command);
         let out = self
             .cmd()
-            .args(new_session_args(&name, cwd, &command, Some(sink_command)))
+            .args(new_session_args(
+                &name,
+                cwd,
+                &command,
+                session_env,
+                Some(sink_command),
+            ))
             .output()?;
         check(out)
     }
@@ -228,6 +246,70 @@ impl Tmux {
         check(out)
     }
 
+    /// Escape-sequence snapshot of a pane's current screen (#…), for clients
+    /// that just attached.
+    ///
+    /// The raw byte replay buffer cannot reconstruct a full-screen program:
+    /// its tail starts mid-stream, long after the app set up the modes,
+    /// colours and cursor position that give those bytes meaning. A browser
+    /// refresh therefore painted garbage until something forced the app to
+    /// repaint. tmux already holds the authoritative screen, so ask it.
+    ///
+    /// Returns `Ok(None)` when the session or the tmux server is gone — the
+    /// caller falls back to the byte replay, which is all a dead session has.
+    pub fn capture_pane(&self, id: Uuid) -> Result<Option<Vec<u8>>, TmuxError> {
+        let name = session_name(id);
+        let start = format!("-{CAPTURE_HISTORY_LINES}");
+        // One invocation, so tmux runs both commands in a single pass of its
+        // command queue: the cursor position cannot belong to an older screen
+        // than the captured content. Two invocations raced — a program that
+        // switched to the alternate screen in between produced a snapshot with
+        // the new screen and the old cursor.
+        let out = self
+            .cmd()
+            .args([
+                "display-message",
+                "-p",
+                "-t",
+                &name,
+                "-F",
+                SCREEN_GEOMETRY_FORMAT,
+                ";",
+                "capture-pane",
+                "-p",
+                "-e",
+                // Keep trailing spaces, so a line's background colour reaches
+                // the edge instead of stopping at the last glyph and letting
+                // the client's own background show through.
+                "-N",
+                "-t",
+                &name,
+                "-S",
+                &start,
+            ])
+            .output()?;
+        let Some(stdout) = soft_output(out)? else {
+            return Ok(None);
+        };
+        let Some((head, content)) = stdout.split_once('\n') else {
+            return Ok(None);
+        };
+        let Some(geom) = parse_screen_geometry(head) else {
+            return Ok(None);
+        };
+        let mut lines: Vec<&str> = content
+            .strip_suffix('\n')
+            .unwrap_or(content)
+            .split('\n')
+            .collect();
+        // Scrollback belongs to the normal screen. Replaying it under an
+        // alternate-screen program would paste the shell's history behind it.
+        if geom.alternate {
+            lines.drain(..lines.len().saturating_sub(geom.pane_height));
+        }
+        Ok(Some(render_screen_snapshot(&lines, geom)))
+    }
+
     /// `tmux resize-window -t maestro-<id> -x <cols> -y <rows>`.
     pub fn resize_window(&self, id: Uuid, cols: u16, rows: u16) -> Result<(), TmuxError> {
         let name = session_name(id);
@@ -246,6 +328,25 @@ impl Tmux {
         check(out)
     }
 
+    /// `tmux show-environment -t maestro-<id>`, parsed into KEY=VALUE pairs.
+    /// Test-facing view of what a spawned session actually inherits.
+    pub fn show_environment(&self, id: Uuid) -> Result<BTreeMap<String, String>, TmuxError> {
+        let name = session_name(id);
+        let out = self
+            .cmd()
+            .args(["show-environment", "-t", &name])
+            .output()?;
+        check(out.clone())?;
+        let stdout = String::from_utf8_lossy(&out.stdout);
+        let mut env = BTreeMap::new();
+        for line in stdout.lines() {
+            if let Some((k, v)) = line.split_once('=') {
+                env.insert(k.to_string(), v.to_string());
+            }
+        }
+        Ok(env)
+    }
+
     /// `tmux kill-server`. Best-effort cleanup used mostly by tests.
     pub fn kill_server(&self) -> Result<(), TmuxError> {
         let out = self.cmd().arg("kill-server").output()?;
@@ -263,12 +364,22 @@ impl Tmux {
     }
 }
 
+/// Phrasings tmux uses for "there is no server on this socket". They vary by
+/// version, and `list_sessions` turning one of these into an `Err` stops the
+/// liveness watcher reaping for that pass — so a missing phrasing is silent.
+const NO_SERVER_PHRASES: &[&str] = &[
+    "no server running",
+    "no sessions",
+    "error connecting",
+    // tmux >= 3.7 when the server shuts down while this client is connected,
+    // which is exactly what killing the last session does.
+    "server exited unexpectedly",
+];
+
 /// True if tmux's stderr indicates "there is no tmux server running on this
 /// socket" (multiple phrasings across versions).
 fn is_no_server_error(stderr: &str) -> bool {
-    stderr.contains("no server running")
-        || stderr.contains("no sessions")
-        || stderr.contains("error connecting")
+    NO_SERVER_PHRASES.iter().any(|p| stderr.contains(p))
 }
 
 /// A session pane's process id, foreground command, controlling tty, and
@@ -360,6 +471,7 @@ fn new_session_args(
     name: &str,
     cwd: &Path,
     command: &str,
+    env: &BTreeMap<String, String>,
     pipe_sink: Option<&str>,
 ) -> Vec<OsString> {
     let mut args = vec![
@@ -378,8 +490,14 @@ fn new_session_args(
         OsString::from(name),
         OsString::from("-c"),
         cwd.as_os_str().to_os_string(),
-        OsString::from(command),
     ];
+    // Caller-supplied environment. Sorted so the argv is deterministic, and
+    // therefore assertable.
+    for (k, v) in env {
+        args.push(OsString::from("-e"));
+        args.push(OsString::from(format!("{k}={v}")));
+    }
+    args.push(OsString::from(command));
     if let Some(sink) = pipe_sink {
         args.extend([
             OsString::from(";"),
@@ -392,6 +510,191 @@ fn new_session_args(
     args
 }
 
+/// How much scrollback a fresh attach inherits from tmux's history, in lines.
+/// Enough to land in context after a browser refresh without making the first
+/// frame huge.
+const CAPTURE_HISTORY_LINES: usize = 300;
+
+/// `display-message -F` request behind [`parse_screen_geometry`]. tmux expands
+/// a name it does not know to the empty string rather than failing, so a field
+/// missing on an older tmux shifts everything after it — hence the parser keys
+/// the optional tail off the field count.
+const SCREEN_GEOMETRY_FORMAT: &str = concat!(
+    "#{cursor_x} #{cursor_y} #{pane_height} #{alternate_on} #{cursor_flag} ",
+    "#{mouse_standard_flag} #{mouse_button_flag} #{mouse_all_flag} ",
+    "#{mouse_utf8_flag} #{mouse_sgr_flag}",
+);
+
+/// Field count of [`SCREEN_GEOMETRY_FORMAT`]; fewer means an older tmux did not
+/// know one of the names, and the mouse tail cannot be trusted by position.
+const SCREEN_GEOMETRY_FIELDS: usize = 10;
+
+/// Mouse-reporting modes a pane has turned on. A full-screen program sets these
+/// once, at startup, so a client attaching later never sees the sequences —
+/// [`render_screen_snapshot`] replays them.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+struct MouseModes {
+    /// `?1000` — report button press and release.
+    standard: bool,
+    /// `?1002` — also report motion while a button is held.
+    button: bool,
+    /// `?1003` — report all motion.
+    all: bool,
+    /// `?1005` — UTF-8 coordinates (superseded by SGR, still replayed if on).
+    utf8: bool,
+    /// `?1006` — SGR-encoded coordinates.
+    sgr: bool,
+}
+
+impl MouseModes {
+    /// DECSET parameters to re-enable these modes, private-mode order.
+    fn decset_params(self) -> impl Iterator<Item = u16> {
+        [
+            (self.standard, 1000),
+            (self.button, 1002),
+            (self.all, 1003),
+            (self.utf8, 1005),
+            (self.sgr, 1006),
+        ]
+        .into_iter()
+        .filter_map(|(on, param)| on.then_some(param))
+    }
+}
+
+/// Cursor position and screen geometry of a pane, from `display-message`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct ScreenGeometry {
+    cursor_x: usize,
+    cursor_y: usize,
+    pane_height: usize,
+    alternate: bool,
+    cursor_visible: bool,
+    mouse: MouseModes,
+}
+
+fn parse_screen_geometry(s: &str) -> Option<ScreenGeometry> {
+    let line = s.lines().next()?;
+    let fields: Vec<&str> = line.split_whitespace().collect();
+    let cursor_x = fields.first()?.parse().ok()?;
+    let cursor_y = fields.get(1)?.parse().ok()?;
+    let pane_height: usize = fields.get(2)?.parse().ok()?;
+    let alternate = *fields.get(3)? == "1";
+    // Older tmux without `cursor_flag` just means "assume visible".
+    let cursor_visible = fields.get(4).map(|f| *f == "1").unwrap_or(true);
+    // Only trust the mouse tail when every field expanded; a short line means
+    // some name is unknown here and the remaining ones sit at other offsets.
+    let mouse = if fields.len() >= SCREEN_GEOMETRY_FIELDS {
+        MouseModes {
+            standard: fields[5] == "1",
+            button: fields[6] == "1",
+            all: fields[7] == "1",
+            utf8: fields[8] == "1",
+            sgr: fields[9] == "1",
+        }
+    } else {
+        MouseModes::default()
+    };
+    if pane_height == 0 {
+        return None;
+    }
+    Some(ScreenGeometry {
+        cursor_x,
+        cursor_y,
+        pane_height,
+        alternate,
+        cursor_visible,
+        mouse,
+    })
+}
+
+/// Turn captured pane lines into bytes a fresh terminal can replay: clear,
+/// print the lines, then put the cursor back where the pane has it.
+///
+/// The cursor is restored with *relative* moves so the snapshot renders the
+/// same whatever height the client's terminal has — it may not match the
+/// pane's yet, since the client's first `Resize` arrives after this.
+fn render_screen_snapshot(lines: &[&str], geom: ScreenGeometry) -> Vec<u8> {
+    // Screen rows are the last `pane_height` captured lines; anything before
+    // them is scrollback.
+    let screen_top = lines.len().saturating_sub(geom.pane_height);
+    let cursor_row = (screen_top + geom.cursor_y).min(lines.len().saturating_sub(1));
+    // Trailing blank rows would scroll the real content off a short client
+    // terminal, so drop them — but never the cursor's own row or anything
+    // above it, which is where a program that draws below its cursor lives.
+    let last = lines
+        .iter()
+        .rposition(|l| !strip_sgr(l).trim().is_empty())
+        .unwrap_or(0)
+        .max(cursor_row);
+
+    let mut out = Vec::new();
+    // Put the client on the same buffer the pane is using, so a program's
+    // repaints stay out of the client's scrollback while it runs.
+    if geom.alternate {
+        out.extend_from_slice(b"\x1b[?1049h");
+    }
+    // Mouse reporting is set up once, before this client existed. Without it
+    // the client cannot tell a mouse-driven app from a plain alternate screen,
+    // and its wheel and touch gestures have nowhere to go.
+    for param in geom.mouse.decset_params() {
+        out.extend_from_slice(format!("\x1b[?{param}h").as_bytes());
+    }
+    out.extend_from_slice(b"\x1b[H\x1b[2J\x1b[m");
+    for (i, line) in lines[..=last].iter().enumerate() {
+        if i > 0 {
+            out.extend_from_slice(b"\r\n");
+        }
+        out.extend_from_slice(line.as_bytes());
+    }
+    out.extend_from_slice(b"\x1b[m\r");
+    if last > cursor_row {
+        out.extend_from_slice(format!("\x1b[{}A", last - cursor_row).as_bytes());
+    }
+    if geom.cursor_x > 0 {
+        out.extend_from_slice(format!("\x1b[{}C", geom.cursor_x).as_bytes());
+    }
+    if !geom.cursor_visible {
+        out.extend_from_slice(b"\x1b[?25l");
+    }
+    out
+}
+
+/// Text of a line with SGR escapes removed, for emptiness checks.
+fn strip_sgr(line: &str) -> String {
+    let mut out = String::with_capacity(line.len());
+    let mut chars = line.chars();
+    while let Some(c) = chars.next() {
+        if c != '\x1b' {
+            out.push(c);
+            continue;
+        }
+        // Skip CSI ... final-byte. Anything else escape-ish is not produced by
+        // `capture-pane -e`, so treating it the same way is harmless.
+        for c in chars.by_ref() {
+            if c.is_ascii_alphabetic() {
+                break;
+            }
+        }
+    }
+    out
+}
+
+/// `Ok(None)` when tmux failed because the server or the target is gone,
+/// `Ok(Some(stdout))` on success, `Err` for anything else.
+fn soft_output(out: Output) -> Result<Option<String>, TmuxError> {
+    if out.status.success() {
+        return Ok(Some(String::from_utf8_lossy(&out.stdout).into_owned()));
+    }
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    if is_no_server_error(&stderr) || stderr.contains("can't find") {
+        return Ok(None);
+    }
+    Err(TmuxError::NonZero {
+        code: out.status.code().unwrap_or(-1),
+        stderr: stderr.into_owned(),
+    })
+}
+
 fn check(out: Output) -> Result<(), TmuxError> {
     if out.status.success() {
         Ok(())
@@ -407,6 +710,221 @@ fn check(out: Output) -> Result<(), TmuxError> {
 mod tests {
     use super::*;
 
+    #[test]
+    fn parse_screen_geometry_reads_cursor_and_alternate_flag() {
+        let g = parse_screen_geometry("12 3 40 1 0 0 1 0 0 1\n").unwrap();
+        assert_eq!(
+            g,
+            ScreenGeometry {
+                cursor_x: 12,
+                cursor_y: 3,
+                pane_height: 40,
+                alternate: true,
+                cursor_visible: false,
+                mouse: MouseModes {
+                    button: true,
+                    sgr: true,
+                    ..MouseModes::default()
+                },
+            }
+        );
+        let g = parse_screen_geometry("0 0 24 0").unwrap();
+        assert!(!g.alternate);
+        assert!(g.cursor_visible, "missing cursor_flag means visible");
+        assert!(parse_screen_geometry("0 0 0 0").is_none());
+        assert!(parse_screen_geometry("garbage").is_none());
+    }
+
+    /// A tmux that does not know one of the mouse names expands it to nothing,
+    /// so the tail is one field short and every flag in it has slid. Reading it
+    /// by position would claim modes the pane never set.
+    #[test]
+    fn parse_screen_geometry_drops_a_short_mouse_tail() {
+        let g = parse_screen_geometry("0 0 24 1 1 0 0 1 1").unwrap();
+        assert_eq!(g.mouse, MouseModes::default());
+    }
+
+    #[test]
+    fn mouse_modes_map_to_private_mode_parameters() {
+        let all = MouseModes {
+            standard: true,
+            button: true,
+            all: true,
+            utf8: true,
+            sgr: true,
+        };
+        assert_eq!(
+            all.decset_params().collect::<Vec<_>>(),
+            vec![1000, 1002, 1003, 1005, 1006]
+        );
+        assert_eq!(MouseModes::default().decset_params().count(), 0);
+    }
+
+    #[test]
+    fn snapshot_clears_prints_lines_and_parks_the_cursor() {
+        // Two scrollback lines, then a 3-row screen with the cursor on row 1.
+        let lines = ["old", "older", "prompt> hi", "", ""];
+        let out = render_screen_snapshot(
+            &lines,
+            ScreenGeometry {
+                cursor_x: 10,
+                cursor_y: 0,
+                pane_height: 3,
+                alternate: false,
+                cursor_visible: true,
+                mouse: MouseModes::default(),
+            },
+        );
+        let out = String::from_utf8(out).unwrap();
+        assert_eq!(
+            out,
+            "\x1b[H\x1b[2J\x1b[mold\r\nolder\r\nprompt> hi\x1b[m\r\x1b[10C"
+        );
+    }
+
+    #[test]
+    fn snapshot_keeps_rows_below_the_cursor_and_moves_back_up() {
+        let lines = ["prompt> hi", "hint line", ""];
+        let out = render_screen_snapshot(
+            &lines,
+            ScreenGeometry {
+                cursor_x: 0,
+                cursor_y: 0,
+                pane_height: 3,
+                alternate: true,
+                cursor_visible: false,
+                mouse: MouseModes::default(),
+            },
+        );
+        let out = String::from_utf8(out).unwrap();
+        assert!(out.starts_with("\x1b[?1049h\x1b[H\x1b[2J"), "{out:?}");
+        assert!(
+            out.ends_with("prompt> hi\r\nhint line\x1b[m\r\x1b[1A\x1b[?25l"),
+            "{out:?}"
+        );
+    }
+
+    #[test]
+    fn snapshot_ignores_colour_only_rows_when_trimming() {
+        let lines = ["text", "\x1b[38;5;4m\x1b[m", ""];
+        let out = String::from_utf8(render_screen_snapshot(
+            &lines,
+            ScreenGeometry {
+                cursor_x: 4,
+                cursor_y: 0,
+                pane_height: 3,
+                alternate: false,
+                cursor_visible: true,
+                mouse: MouseModes::default(),
+            },
+        ))
+        .unwrap();
+        assert_eq!(out, "\x1b[H\x1b[2J\x1b[mtext\x1b[m\r\x1b[4C");
+    }
+
+    /// A client attaching to a running full-screen app never saw it turn mouse
+    /// reporting on, so the snapshot has to. Without this the client reads the
+    /// pane as a plain alternate screen and its scroll gestures go nowhere.
+    #[test]
+    fn snapshot_replays_the_panes_mouse_modes() {
+        let out = String::from_utf8(render_screen_snapshot(
+            &["app"],
+            ScreenGeometry {
+                cursor_x: 0,
+                cursor_y: 0,
+                pane_height: 1,
+                alternate: true,
+                cursor_visible: true,
+                mouse: MouseModes {
+                    button: true,
+                    sgr: true,
+                    ..MouseModes::default()
+                },
+            },
+        ))
+        .unwrap();
+        assert!(
+            out.starts_with("\x1b[?1049h\x1b[?1002h\x1b[?1006h\x1b[H\x1b[2J"),
+            "{out:?}"
+        );
+    }
+
+    /// Every phrasing must be recognised: an unmatched one makes
+    /// `list_sessions` fail, and a failed pass reaps nothing.
+    #[test]
+    fn new_session_args_emit_sorted_env_flags_before_the_command() {
+        let env: BTreeMap<String, String> = [
+            ("ZED".to_string(), "9".to_string()),
+            ("ALPHA".to_string(), "1".to_string()),
+        ]
+        .into_iter()
+        .collect();
+        let args = new_session_args("maestro-x", Path::new("/tmp"), "bash", &env, None);
+        let flat: Vec<String> = args
+            .iter()
+            .map(|a| a.to_string_lossy().into_owned())
+            .collect();
+
+        let alpha = flat.iter().position(|a| a == "ALPHA=1").expect("ALPHA");
+        let zed = flat.iter().position(|a| a == "ZED=9").expect("ZED");
+        let command = flat.iter().rposition(|a| a == "bash").expect("command");
+        assert!(alpha < zed, "env flags must be sorted for a stable argv");
+        assert!(zed < command, "env must precede the command argument");
+        assert_eq!(flat[alpha - 1], "-e");
+        assert_eq!(flat[zed - 1], "-e");
+    }
+
+    /// `TMUX` beats `TMUX_TMPDIR` when tmux looks for a server, so leaving an
+    /// inherited one in place would silently ignore the configured tmpdir.
+    #[test]
+    fn cmd_clears_an_inherited_tmux_and_sets_the_configured_tmpdir() {
+        let tmux = Tmux::new().with_tmpdir("/run/maestro-dev");
+        let cmd = tmux.cmd();
+        let envs: Vec<_> = cmd.get_envs().collect();
+
+        assert!(
+            envs.contains(&(OsStr::new("TMUX"), None)),
+            "TMUX must be removed, got {envs:?}"
+        );
+        assert!(
+            envs.contains(&(
+                OsStr::new("TMUX_TMPDIR"),
+                Some(OsStr::new("/run/maestro-dev"))
+            )),
+            "TMUX_TMPDIR must be set, got {envs:?}"
+        );
+    }
+
+    /// The removal is unconditional: a daemon manages its own server whether or
+    /// not a tmpdir was configured.
+    #[test]
+    fn cmd_clears_an_inherited_tmux_without_a_configured_tmpdir() {
+        let cmd = Tmux::new().cmd();
+        let envs: Vec<_> = cmd.get_envs().collect();
+        assert!(
+            envs.contains(&(OsStr::new("TMUX"), None)),
+            "TMUX must be removed, got {envs:?}"
+        );
+    }
+
+    #[test]
+    fn is_no_server_error_matches_every_known_phrasing() {
+        for phrase in NO_SERVER_PHRASES {
+            assert!(is_no_server_error(phrase), "unmatched: {phrase}");
+            assert!(
+                is_no_server_error(&format!("{phrase}\n")),
+                "unmatched with trailing newline: {phrase}"
+            );
+        }
+    }
+
+    #[test]
+    fn is_no_server_error_rejects_unrelated_failures() {
+        assert!(!is_no_server_error("can't find session: maestro-x"));
+        assert!(!is_no_server_error("usage: kill-session"));
+        assert!(!is_no_server_error(""));
+    }
+
     #[test]
     fn parse_pane_line_splits_pid_command_tty_path() {
         let p = parse_pane_line("12345 claude /dev/pts/3 /home/naps62/maestro").unwrap();
@@ -440,7 +958,13 @@ mod tests {
 
     #[test]
     fn new_session_args_pass_256color_env_and_default_terminal() {
-        let args = new_session_args("maestro-abc", Path::new("/tmp/proj"), "sleep 30", None);
+        let args = new_session_args(
+            "maestro-abc",
+            Path::new("/tmp/proj"),
+            "sleep 30",
+            &BTreeMap::new(),
+            None,
+        );
         let strs: Vec<&str> = args.iter().map(|s| s.to_str().unwrap()).collect();
         assert_eq!(
             strs,
@@ -496,6 +1020,7 @@ mod tests {
             "maestro-abc",
             Path::new("/tmp/proj"),
             "sleep 30",
+            &BTreeMap::new(),
             Some("cat >> '/tmp/fifo'"),
         );
         let strs: Vec<&str> = args.iter().map(|s| s.to_str().unwrap()).collect();

crates/maestro-daemon/src/worktree.rs

@@ -4,79 +4,277 @@
 use std::path::{Path, PathBuf};
 use std::process::{Command, Output};
 
-use uuid::Uuid;
-
 #[derive(Debug, thiserror::Error)]
 pub enum WorktreeError {
     #[error("failed to spawn git: {0}")]
     Spawn(#[from] std::io::Error),
     #[error("git exited with code {code}: {stderr}")]
     NonZero { code: i32, stderr: String },
+    /// A registered worktree lives under the tree about to be removed; git
+    /// hides its contents from `git status`, so removal would delete its
+    /// uncommitted work unseen (#54 review).
+    #[error("left {} on disk: {}", .path.display(), .reason)]
+    Guarded { path: PathBuf, reason: String },
 }
 
-/// Generates a unique path under `root` and runs `git worktree add` rooted at
-/// `base_repo`. Each call appends a UUID-suffixed directory so concurrent
-/// `add()`s never collide.
+impl From<crate::worktree_probe::ProbeError> for WorktreeError {
+    fn from(e: crate::worktree_probe::ProbeError) -> Self {
+        match e {
+            crate::worktree_probe::ProbeError::Spawn(io) => WorktreeError::Spawn(io),
+            crate::worktree_probe::ProbeError::NonZero { code, stderr } => {
+                WorktreeError::NonZero { code, stderr }
+            }
+        }
+    }
+}
+
+/// Runs `git worktree add` rooted at `base_repo`. By default worktrees land
+/// inside the repository itself at `<repo>/worktrees/<branch>` (#56) so they
+/// are findable from the repo; an operator-set root overrides that.
 #[derive(Debug, Clone)]
 pub struct WorktreeManager {
-    root: PathBuf,
+    /// `[daemon].worktree_root` override. `None` uses the default
+    /// `<repo>/worktrees/<branch>` placement.
+    root_override: Option<PathBuf>,
 }
 
 impl WorktreeManager {
-    pub fn new(root: impl Into<PathBuf>) -> Self {
-        Self { root: root.into() }
+    pub fn new(root_override: Option<PathBuf>) -> Self {
+        Self { root_override }
     }
 
-    pub fn root(&self) -> &Path {
-        &self.root
+    pub fn root(&self) -> Option<&Path> {
+        self.root_override.as_deref()
     }
 
-    /// `git -C <base_repo> worktree add -b <branch> <generated-path>`.
-    /// Returns the path of the new worktree on success.
-    pub fn add(&self, base_repo: &Path, branch: &str) -> Result<PathBuf, WorktreeError> {
-        std::fs::create_dir_all(&self.root)?;
-        let path = self.generate_path(branch);
-        let out = Command::new("git")
-            .arg("-C")
-            .arg(base_repo)
-            .args(["worktree", "add", "-b", branch])
-            .arg(&path)
-            .output()?;
+    /// Where a worktree for `branch` will be created: the override root, or
+    /// `<main checkout>/worktrees/<sanitized branch>` by default. If the path
+    /// is occupied, [`Self::add_new`] / [`Self::add_existing`] sidestep to
+    /// `<path>-2`, `<path>-3`, ... instead.
+    ///
+    /// `base_repo` is whatever the client picked, which the project list makes
+    /// easy to point at a *linked worktree* — placing the new tree inside it
+    /// would nest one worktree in another, and git hides a registered
+    /// worktree's contents from the outer `git status`, so the outer tree
+    /// would later look clean and its removal would delete the inner one's
+    /// uncommitted work (#54 review). Always place against the main checkout.
+    ///
+    /// The override root gets the repo's basename too: without it two repos
+    /// spawning the same branch name target one directory.
+    fn target_path(&self, base_repo: &Path, branch: &str) -> PathBuf {
+        // An unusable branch name falls back to a digest rather than escaping
+        // the root; `run_add` surfaces git's own error for it anyway.
+        let slug = branch_relpath(branch).unwrap_or_else(|| PathBuf::from(short_hash(branch)));
+        let main = main_checkout(base_repo);
+        match &self.root_override {
+            Some(root) => {
+                // Basename alone collides for two checkouts of the same name
+                // (`~/a/maestro` and `~/b/maestro`), so disambiguate with a
+                // digest of the full path (#54 review).
+                let base = main
+                    .file_name()
+                    .map(|n| n.to_string_lossy().into_owned())
+                    .unwrap_or_else(|| "repo".into());
+                let repo = format!("{base}-{}", short_hash(&main.to_string_lossy()));
+                root.join(repo).join(slug)
+            }
+            None => main.join("worktrees").join(slug),
+        }
+    }
+
+    /// [`Self::target_path`] with `-n` appended to the final component, the
+    /// collision suffix (#77).
+    fn target_path_suffixed(&self, base_repo: &Path, branch: &str, n: u32) -> PathBuf {
+        let mut name = self.target_path(base_repo, branch).into_os_string();
+        name.push(format!("-{n}"));
+        PathBuf::from(name)
+    }
+
+    /// `git -C <base_repo> worktree add -b <branch> <path>` — creates the
+    /// branch. Returns the path of the new worktree on success.
+    pub fn add_new(&self, base_repo: &Path, branch: &str) -> Result<PathBuf, WorktreeError> {
+        self.run_add(base_repo, branch, true)
+    }
+
+    /// `git -C <base_repo> worktree add <path> <branch>` — checks out a branch
+    /// that must already exist (#56).
+    pub fn add_existing(&self, base_repo: &Path, branch: &str) -> Result<PathBuf, WorktreeError> {
+        self.run_add(base_repo, branch, false)
+    }
+
+    fn run_add(
+        &self,
+        base_repo: &Path,
+        branch: &str,
+        create_branch: bool,
+    ) -> Result<PathBuf, WorktreeError> {
+        // Clear registrations whose directory is gone first, so a
+        // previously-leaked entry doesn't push this branch to a suffix.
+        prune(base_repo)?;
+        // Anything occupying the target — a tree we left behind, one the
+        // operator made, an unrelated directory — is sidestepped with a
+        // numeric suffix on the directory; the branch stays whatever was
+        // requested (#77). The daemon never adopts what it finds.
+        let mut path = self.target_path(base_repo, branch);
+        let mut n = 1;
+        while path.symlink_metadata().is_ok() {
+            n += 1;
+            path = self.target_path_suffixed(base_repo, branch, n);
+        }
+        // The parent (`<repo>/worktrees` or the override root) may not exist
+        // yet; the target itself must not.
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        let mut cmd = Command::new("git");
+        cmd.arg("-C").arg(base_repo).args(["worktree", "add"]);
+        if create_branch {
+            cmd.arg("-b").arg(branch).arg(&path);
+        } else {
+            // Existing branch: `worktree add <path> <branch>` with no `-b`.
+            cmd.arg(&path).arg(branch);
+        }
+        let out = cmd.output()?;
         check(out)?;
         Ok(path)
     }
 
-    /// `git -C <base_repo> worktree remove --force <path>`.
+    /// `git -C <base_repo> worktree remove <path>`.
+    ///
+    /// Unconditional (#79): the guard moved off the worktree and onto the
+    /// kill, so by the time removal runs the caller has already chosen to
+    /// destroy the tree — the kill only gets here after
+    /// [`crate::worktree_probe::in_the_way`] came back clear. Still refused for a tree holding a
+    /// nested registered worktree, which `git status` cannot see.
     pub fn remove(&self, base_repo: &Path, path: &Path) -> Result<(), WorktreeError> {
+        // Gone from disk already (operator `rm -rf`, or a create that failed
+        // half-way). Probing it with git would fail and be misread as unsaved
+        // work, stranding the registration — and since paths are
+        // deterministic, `worktree add` would then refuse that branch forever
+        // with "missing but already registered" (#56 review).
+        if !path.exists() {
+            return prune(base_repo);
+        }
+        if let Some(inner) = nested_worktree(path) {
+            return Err(WorktreeError::Guarded {
+                path: path.to_path_buf(),
+                reason: format!("holds a nested worktree at {}", inner.display()),
+            });
+        }
         let out = Command::new("git")
             .arg("-C")
             .arg(base_repo)
-            .args(["worktree", "remove", "--force"])
+            .args(["worktree", "remove"])
             .arg(path)
             .output()?;
         check(out)
     }
-
-    fn generate_path(&self, branch: &str) -> PathBuf {
-        let slug = sanitize_branch_for_path(branch);
-        let unique = Uuid::new_v4().simple();
-        self.root.join(format!("{slug}-{unique}"))
-    }
 }
 
-fn sanitize_branch_for_path(branch: &str) -> String {
-    let mut out = String::with_capacity(branch.len());
-    for c in branch.chars() {
-        if c.is_ascii_alphanumeric() || c == '-' || c == '_' {
-            out.push(c);
-        } else if c == '/' || c == '.' {
-            out.push('-');
-        }
+/// The repository's main checkout. `--git-common-dir` points at the shared
+/// `.git` for every linked worktree, so its parent is the main tree. Falls
+/// back to the input when git can't answer.
+/// The repository a path belongs to: the main checkout, even when `path` is a
+/// linked worktree. Clients group sessions by this (#99), and placement uses it
+/// so a worktree is never nested inside another.
+pub fn main_checkout_of(path: &Path) -> PathBuf {
+    main_checkout(path)
+}
+
+fn main_checkout(path: &Path) -> PathBuf {
+    let out = Command::new("git")
+        .arg("-C")
+        .arg(path)
+        .args(["rev-parse", "--path-format=absolute", "--git-common-dir"])
+        .output();
+    let Ok(out) = out else {
+        return path.to_path_buf();
+    };
+    if !out.status.success() {
+        return path.to_path_buf();
     }
-    if out.is_empty() {
-        out.push_str("wt");
+    let common = PathBuf::from(String::from_utf8_lossy(&out.stdout).trim().to_string());
+    common
+        .parent()
+        .map(Path::to_path_buf)
+        .unwrap_or_else(|| path.to_path_buf())
+}
+
+/// `Some(inner)` when a registered worktree lives under `path`. Git omits
+/// those directories from `git status`, so the dirty-work guard cannot see
+/// them and removal would delete them (#54 review).
+fn nested_worktree(path: &Path) -> Option<PathBuf> {
+    let out = Command::new("git")
+        .arg("-C")
+        .arg(path)
+        .args(["worktree", "list", "--porcelain"])
+        .output()
+        .ok()?;
+    // `worktree list` prints fully-resolved paths while ours comes from
+    // `--git-common-dir` and may still hold symlinks. Comparing the two forms
+    // directly makes the guard silently pass on any symlinked repo path — and
+    // this guard is what stands between a kill and deleting an inner
+    // worktree's uncommitted work (#54 review).
+    let needle = path.canonicalize().unwrap_or_else(|_| path.to_path_buf());
+    let text = String::from_utf8_lossy(&out.stdout);
+    text.lines()
+        .filter_map(|l| l.strip_prefix("worktree "))
+        .map(PathBuf::from)
+        .find(|p| {
+            let real = p.canonicalize().unwrap_or_else(|_| p.clone());
+            real != needle && real.starts_with(&needle)
+        })
+}
+
+/// Short digest used to disambiguate override roots.
+///
+/// Hand-rolled FNV-1a rather than `DefaultHasher`: this value becomes a
+/// directory name, and `DefaultHasher`'s algorithm is explicitly not
+/// guaranteed stable across Rust releases — a toolchain bump would remap every
+/// repo to a new directory and orphan the worktrees under the old one
+/// (#67 review).
+fn short_hash(s: &str) -> String {
+    let mut h: u32 = 0x811c_9dc5;
+    for b in s.as_bytes() {
+        h ^= u32::from(*b);
+        h = h.wrapping_mul(0x0100_0193);
     }
-    out
+    format!("{h:08x}")
+}
+
+/// The relative directory a branch's worktree lives in.
+///
+/// A git branch name is already a valid relative path — git stores it as
+/// `.git/refs/heads/feat/example` — so it is used verbatim and `feat/example`
+/// nests under `worktrees/feat/`. That keeps the path readable *and* keeps the
+/// mapping injective: flattening `/` and `.` to `-` made `feat/x`, `feat.x`
+/// and `feat-x` share one directory (#54 review).
+///
+/// Git already forbids holding both `feat` and `feat/x`, so the directory
+/// collision that nesting could cause cannot arise from valid refs. Only
+/// traversal and absolute components are rejected.
+fn branch_relpath(branch: &str) -> Option<PathBuf> {
+    use std::path::Component;
+    let candidate = Path::new(branch);
+    if branch.is_empty()
+        || !candidate
+            .components()
+            .all(|c| matches!(c, Component::Normal(_)))
+    {
+        return None;
+    }
+    Some(candidate.to_path_buf())
+}
+
+/// `git -C <base_repo> worktree prune` — drops registrations whose directory
+/// no longer exists.
+fn prune(base_repo: &Path) -> Result<(), WorktreeError> {
+    let out = Command::new("git")
+        .arg("-C")
+        .arg(base_repo)
+        .args(["worktree", "prune"])
+        .output()?;
+    check(out)
 }
 
 fn check(out: Output) -> Result<(), WorktreeError> {

crates/maestro-daemon/src/worktree_probe.rs

@@ -0,0 +1,318 @@
+//! The one git probe for what a worktree holds that would be lost (#79).
+//!
+//! [`in_the_way`] is the single predicate behind both paths: the kill refusal
+//! (#79) and the natural-exit classifier (#82). It lives here rather than in
+//! `worktree.rs` so that neither can answer the question differently.
+
+use std::path::Path;
+
+use maestro_protocol::InTheWay;
+
+#[derive(Debug, thiserror::Error)]
+pub enum ProbeError {
+    #[error("failed to spawn git: {0}")]
+    Spawn(#[from] std::io::Error),
+    #[error("git exited with code {code}: {stderr}")]
+    NonZero { code: i32, stderr: String },
+}
+
+/// What a kill refusal would report about the worktree at `path`, right now.
+///
+/// Ignored files never count (`--ignored=no`) — every Rust worktree has a
+/// `target/`, and counting those would put every tree permanently in the way.
+/// A directory that no longer exists reports nothing in the way: there is
+/// nothing left to lose.
+pub fn in_the_way(path: &Path) -> Result<InTheWay, ProbeError> {
+    let mut breakdown = InTheWay::default();
+    // `symlink_metadata` rather than `exists`: a broken symlink is gone for
+    // our purposes, and following it would probe the wrong tree.
+    if std::fs::symlink_metadata(path).is_err() {
+        return Ok(breakdown);
+    }
+    let status = run_git(
+        path,
+        [
+            "status",
+            "--porcelain",
+            "--ignored=no",
+            "--untracked-files=normal",
+        ],
+    )?;
+    for line in String::from_utf8_lossy(&status.stdout).lines() {
+        if line.starts_with("??") {
+            breakdown.untracked_files += 1;
+        } else if !line.is_empty() {
+            breakdown.uncommitted_files += 1;
+        }
+    }
+    // The line delta behind the sidebar's `+N −M` (docs/SIDEBAR.md). Diffing
+    // the working tree against HEAD covers staged and unstaged changes in one
+    // pass, so a `git add` never makes the counter drop.
+    let numstat = run_git(path, ["diff", "--numstat", "HEAD"]);
+    if let Ok(numstat) = numstat {
+        for line in String::from_utf8_lossy(&numstat.stdout).lines() {
+            let mut cols = line.split('\t');
+            // A binary file reports `-` for both columns; it has no lines to
+            // add to either total.
+            let added: usize = cols.next().and_then(|c| c.parse().ok()).unwrap_or(0);
+            let removed: usize = cols.next().and_then(|c| c.parse().ok()).unwrap_or(0);
+            breakdown.insertions += added;
+            breakdown.deletions += removed;
+        }
+    }
+    // A repo with no commits yet has no HEAD to diff against, and the counts
+    // stay zero rather than failing the whole probe — the file counts above
+    // already reported the work.
+
+    // Resolved inside the worktree so a detached HEAD still has a starting
+    // point; asking the base repo for `refs/heads/<branch>` fails there.
+    let head = run_git(path, ["rev-parse", "--abbrev-ref", "HEAD"])?;
+    let branch = String::from_utf8_lossy(&head.stdout).trim().to_string();
+    let tip: &str = if branch == "HEAD" { "HEAD" } else { &branch };
+    // Commits reachable from the tip but from no remote-tracking ref. A branch
+    // pushed anywhere counts as pushed; there is no "which remote" question to
+    // get wrong.
+    let unpushed = run_git(path, ["rev-list", "--count", tip, "--not", "--remotes"])?;
+    breakdown.unpushed_commits = String::from_utf8_lossy(&unpushed.stdout)
+        .trim()
+        .parse()
+        .unwrap_or(0);
+    Ok(breakdown)
+}
+
+fn run_git<I, S>(dir: &Path, args: I) -> Result<std::process::Output, ProbeError>
+where
+    I: IntoIterator<Item = S>,
+    S: AsRef<std::ffi::OsStr>,
+{
+    let mut cmd = std::process::Command::new("git");
+    cmd.arg("-C").arg(dir).args(args);
+    let out = cmd.output()?;
+    if !out.status.success() {
+        return Err(ProbeError::NonZero {
+            code: out.status.code().unwrap_or(-1),
+            stderr: String::from_utf8_lossy(&out.stderr).into_owned(),
+        });
+    }
+    Ok(out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+    use std::process::Command;
+
+    struct Repo {
+        root: tempfile::TempDir,
+        repo: PathBuf,
+    }
+
+    fn git(dir: &Path, args: &[&str]) {
+        let out = Command::new("git")
+            .arg("-C")
+            .arg(dir)
+            .args(args)
+            .output()
+            .expect("git spawn");
+        assert!(
+            out.status.success(),
+            "git {args:?} failed: {}",
+            String::from_utf8_lossy(&out.stderr)
+        );
+    }
+
+    /// A repo with a remote, one commit on `main`, and a linked worktree for
+    /// branch `feature` at `<repo>/worktrees/feature`.
+    fn repo_with_worktree() -> Repo {
+        let root = tempfile::tempdir().expect("tempdir");
+        let repo = root.path().join("repo");
+        let remote = root.path().join("remote.git");
+        std::fs::create_dir_all(&repo).unwrap();
+        std::fs::create_dir_all(&remote).unwrap();
+        git(&repo, &["init", "-q", "-b", "main"]);
+        git(&repo, &["config", "user.email", "t@t"]);
+        git(&repo, &["config", "user.name", "T"]);
+        std::fs::write(repo.join("README"), b"hello\n").unwrap();
+        git(&repo, &["add", "."]);
+        git(&repo, &["commit", "-q", "-m", "init"]);
+        git(&remote, &["init", "-q", "--bare"]);
+        git(&repo, &["remote", "add", "origin", &path_str(&remote)]);
+        git(&repo, &["push", "-q", "-u", "origin", "main"]);
+        git(
+            &repo,
+            &[
+                "worktree",
+                "add",
+                "-q",
+                "-b",
+                "feature",
+                "worktrees/feature",
+            ],
+        );
+        Repo { root, repo }
+    }
+
+    fn path_str(path: &Path) -> String {
+        path.to_string_lossy().into_owned()
+    }
+
+    impl Repo {
+        fn wt(&self) -> PathBuf {
+            self.repo.join("worktrees").join("feature")
+        }
+
+        fn commit_in_wt(&self, msg: &str) {
+            std::fs::write(self.wt().join("README"), msg.as_bytes()).unwrap();
+            git(&self.wt(), &["add", "-A"]);
+            git(&self.wt(), &["commit", "-qm", msg]);
+        }
+    }
+
+    #[test]
+    fn a_clean_pushed_worktree_has_nothing_in_the_way() {
+        let r = repo_with_worktree();
+        git(&r.wt(), &["push", "-q", "-u", "origin", "feature"]);
+        let breakdown = in_the_way(&r.wt()).expect("probe");
+        assert_eq!(breakdown, InTheWay::default());
+        assert!(breakdown.is_clear());
+    }
+
+    #[test]
+    fn uncommitted_untracked_and_unpushed_are_counted_separately() {
+        let r = repo_with_worktree();
+        std::fs::write(r.wt().join("README"), b"edited\n").unwrap();
+        std::fs::write(r.wt().join("scratch.txt"), b"untracked\n").unwrap();
+
+        let dirty = in_the_way(&r.wt()).expect("probe");
+        assert_eq!(dirty.uncommitted_files, 1);
+        assert_eq!(dirty.untracked_files, 1);
+        assert_eq!(dirty.unpushed_commits, 0);
+        assert!(!dirty.is_clear());
+
+        // Committing clears exactly one dimension and creates another.
+        git(&r.wt(), &["add", "README"]);
+        git(&r.wt(), &["commit", "-qm", "wip"]);
+
+        let breakdown = in_the_way(&r.wt()).expect("probe");
+        assert_eq!(breakdown.uncommitted_files, 0);
+        assert_eq!(breakdown.untracked_files, 1);
+        assert_eq!(breakdown.unpushed_commits, 1);
+    }
+
+    #[test]
+    fn tracked_edits_count_as_uncommitted() {
+        let r = repo_with_worktree();
+        std::fs::write(r.wt().join("README"), b"edited\n").unwrap();
+        let breakdown = in_the_way(&r.wt()).expect("probe");
+        assert_eq!(breakdown.uncommitted_files, 1);
+        assert_eq!(breakdown.untracked_files, 0);
+    }
+
+    #[test]
+    fn pushing_clears_unpushed_but_keeps_other_entries() {
+        let r = repo_with_worktree();
+        std::fs::write(r.wt().join("new.txt"), b"x\n").unwrap();
+        r.commit_in_wt("wip");
+
+        let before = in_the_way(&r.wt()).expect("probe");
+        assert_eq!(before.unpushed_commits, 1);
+
+        git(&r.wt(), &["push", "-q", "-u", "origin", "feature"]);
+        // Same stored entry, different tree: the breakdown must move with it.
+        let after = in_the_way(&r.wt()).expect("probe");
+        assert_eq!(after.unpushed_commits, 0);
+        assert_eq!(after.untracked_files, 0);
+
+        std::fs::write(r.wt().join("loose.txt"), b"x\n").unwrap();
+        let dirty = in_the_way(&r.wt()).expect("probe");
+        assert_eq!(dirty.untracked_files, 1);
+    }
+
+    /// docs/SIDEBAR.md: the sidebar renders `+N −M`, so the probe carries the
+    /// line delta of the tracked changes — staged and unstaged together,
+    /// against HEAD.
+    #[test]
+    fn staged_and_unstaged_lines_both_count() {
+        let r = repo_with_worktree();
+        std::fs::write(r.wt().join("staged.txt"), b"a\nb\n").unwrap();
+        git(&r.wt(), &["add", "staged.txt"]);
+        // README loses its one line and gains three, unstaged.
+        std::fs::write(r.wt().join("README"), b"x\ny\nz\n").unwrap();
+
+        let breakdown = in_the_way(&r.wt()).expect("probe");
+        assert_eq!(breakdown.insertions, 5, "2 staged + 3 unstaged");
+        assert_eq!(breakdown.deletions, 1);
+    }
+
+    /// Untracked files are counted as files and never as lines — reading each
+    /// one off disk is the cost the sidebar contract declines to pay.
+    #[test]
+    fn untracked_files_contribute_no_lines() {
+        let r = repo_with_worktree();
+        std::fs::write(r.wt().join("scratch.txt"), b"a\nb\nc\n").unwrap();
+        let breakdown = in_the_way(&r.wt()).expect("probe");
+        assert_eq!(breakdown.untracked_files, 1);
+        assert_eq!(breakdown.insertions, 0);
+        assert_eq!(breakdown.deletions, 0);
+    }
+
+    /// A binary file's numstat is `-\t-`. It must not poison the totals, and
+    /// it must not abort the probe either.
+    #[test]
+    fn binary_changes_add_no_lines() {
+        let r = repo_with_worktree();
+        std::fs::write(r.wt().join("blob.bin"), [0u8, 159, 0, 12]).unwrap();
+        git(&r.wt(), &["add", "blob.bin"]);
+        git(&r.wt(), &["commit", "-qm", "blob"]);
+        std::fs::write(r.wt().join("blob.bin"), [0u8, 1, 2, 3, 4]).unwrap();
+
+        let breakdown = in_the_way(&r.wt()).expect("probe");
+        assert_eq!(breakdown.uncommitted_files, 1);
+        assert_eq!(breakdown.insertions, 0);
+        assert_eq!(breakdown.deletions, 0);
+    }
+
+    /// A line delta alone never decides `is_clear` — the file counts do — so a
+    /// mode change with no line delta still blocks a kill.
+    #[test]
+    fn a_line_less_change_still_blocks() {
+        let r = repo_with_worktree();
+        let script = r.wt().join("run.sh");
+        std::fs::write(&script, b"echo hi\n").unwrap();
+        git(&r.wt(), &["add", "run.sh"]);
+        git(&r.wt(), &["commit", "-qm", "script"]);
+        git(&r.wt(), &["update-index", "--chmod=+x", "run.sh"]);
+
+        let breakdown = in_the_way(&r.wt()).expect("probe");
+        assert_eq!(breakdown.insertions, 0);
+        assert_eq!(breakdown.deletions, 0);
+        assert!(!breakdown.is_clear());
+    }
+
+    #[test]
+    fn ignored_files_never_count() {
+        let r = repo_with_worktree();
+        std::fs::write(r.wt().join(".gitignore"), b"target/\n").unwrap();
+        std::fs::create_dir_all(r.wt().join("target")).unwrap();
+        std::fs::write(r.wt().join("target/artifact"), b"x").unwrap();
+
+        let breakdown = in_the_way(&r.wt()).expect("probe");
+        assert_eq!(
+            breakdown,
+            InTheWay {
+                untracked_files: 1,
+                ..InTheWay::default()
+            },
+            "the .gitignore itself is untracked; target/ is not"
+        );
+    }
+
+    #[test]
+    fn a_missing_directory_reports_nothing_in_the_way() {
+        let r = repo_with_worktree();
+        let gone = r.root.path().join("nowhere");
+        let breakdown = in_the_way(&gone).expect("probe");
+        assert!(breakdown.is_clear());
+    }
+}

crates/maestro-daemon/tests/activity.rs

@@ -0,0 +1,211 @@
+//! Activity detection against real processes on a real tty.
+//!
+//! The review noted this pipeline had no end-to-end coverage — `activity::decide`
+//! was unit-tested, but nothing exercised the `/proc` inspection that feeds it.
+//! These use a real tmux pane because that is the only way to get a controlling
+//! terminal with a genuine foreground process group.
+
+mod common;
+
+use std::time::Duration;
+
+use common::TmuxFixture;
+use maestro_daemon::proc::{awaiting_input, ProcGroups};
+use tempfile::TempDir;
+use uuid::Uuid;
+
+/// Poll `awaiting_input` until it reports `want`, so we don't race the shell
+/// reaching its blocking read. Reports what it last saw — the useful half of
+/// the failure.
+fn wait_for_awaiting(fx: &TmuxFixture, id: Uuid, want: bool, label: &str) {
+    let deadline = std::time::Instant::now() + Duration::from_secs(5);
+    let mut last = None;
+    while std::time::Instant::now() < deadline {
+        if let Ok(Some(pane)) = fx.tmux.pane_info(id) {
+            // Fresh each poll: the tree is still settling.
+            let got = awaiting_input(pane.pane_pid, &pane.tty, &ProcGroups::snapshot());
+            if got == want {
+                return;
+            }
+            last = Some(got);
+        }
+        std::thread::sleep(Duration::from_millis(25));
+    }
+    panic!("{label}: wanted awaiting_input={want}, last saw {last:?}");
+}
+
+#[test]
+fn an_idle_shell_is_awaiting_input() {
+    let fx = TmuxFixture::new();
+    let cwd = TempDir::new().unwrap();
+    let id = Uuid::new_v4();
+    fx.tmux
+        .new_session(id, cwd.path(), "bash --noprofile --norc")
+        .expect("new_session");
+
+    wait_for_awaiting(&fx, id, true, "an idle shell sits in read()");
+}
+
+/// The case the old heuristic got wrong. It walked `children` to the deepest
+/// descendant, so it landed on the background `sleep` — which is not on the
+/// terminal — and reported the session as *not* awaiting input, while the
+/// foreground process was blocked on `read`.
+#[test]
+fn a_foreground_reader_with_a_background_helper_is_awaiting_input() {
+    let fx = TmuxFixture::new();
+    let cwd = TempDir::new().unwrap();
+    let script = cwd.path().join("agentish.sh");
+    std::fs::write(&script, "#!/bin/bash\nsleep 300 &\nread -r line\n").unwrap();
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
+    }
+
+    let id = Uuid::new_v4();
+    fx.tmux
+        .new_session(
+            id,
+            cwd.path(),
+            &format!("bash --noprofile --norc {}", script.display()),
+        )
+        .expect("new_session");
+
+    // Wait for the helper itself. Asserting before it exists would pass
+    // against a deepest-descendant walk too, because until then the newest
+    // process in the tree *is* the one blocked on read.
+    let pane = fx.tmux.pane_info(id).expect("pane_info").expect("pane");
+    wait_until(
+        || subtree_has_comm(pane.pane_pid, "sleep"),
+        "the background helper to be spawned",
+    );
+
+    wait_for_awaiting(
+        &fx,
+        id,
+        true,
+        "a foreground reader must win over a newer background child",
+    );
+}
+
+/// A pure timer sleep also parks in 'S' with the terminal inherited; it must
+/// read as idle, not as waiting on the user.
+#[test]
+fn a_foreground_sleep_is_not_awaiting_input() {
+    let fx = TmuxFixture::new();
+    let cwd = TempDir::new().unwrap();
+    let id = Uuid::new_v4();
+    fx.tmux
+        .new_session(id, cwd.path(), "sleep 300")
+        .expect("new_session");
+
+    wait_for_awaiting(&fx, id, false, "a timer sleep is not user input");
+}
+
+/// Whether any process under `root` (inclusive) has this `comm`.
+fn subtree_has_comm(root: i32, comm: &str) -> bool {
+    let mut queue = vec![root];
+    while let Some(pid) = queue.pop() {
+        if std::fs::read_to_string(format!("/proc/{pid}/comm")).is_ok_and(|c| c.trim() == comm) {
+            return true;
+        }
+        queue.extend(
+            std::fs::read_to_string(format!("/proc/{pid}/task/{pid}/children"))
+                .map(|s| {
+                    s.split_whitespace()
+                        .filter_map(|x| x.parse::<i32>().ok())
+                        .collect::<Vec<_>>()
+                })
+                .unwrap_or_default(),
+        );
+    }
+    false
+}
+
+/// Block until `cond` holds, so a test asserts on the state it means to
+/// exercise rather than on whatever the tree looked like first.
+fn wait_until(cond: impl Fn() -> bool, what: &str) {
+    let deadline = std::time::Instant::now() + Duration::from_secs(5);
+    while std::time::Instant::now() < deadline {
+        if cond() {
+            return;
+        }
+        std::thread::sleep(Duration::from_millis(20));
+    }
+    panic!("timed out waiting for {what}");
+}
+
+/// Read `pgrp` and `tpgid` for a pid straight from `/proc`, so the test can
+/// wait for the exact condition it means to exercise rather than a proxy.
+fn pgrp_and_tpgid(pid: i32) -> Option<(i32, i32)> {
+    let stat = std::fs::read_to_string(format!("/proc/{pid}/stat")).ok()?;
+    let close = stat.rfind(')')?;
+    let f: Vec<&str> = stat[close + 1..].split_whitespace().collect();
+    Some((f.get(2)?.parse().ok()?, f.get(5)?.parse().ok()?))
+}
+
+/// `tpgid` names a process *group*, and its leader can exit while another
+/// member still holds the terminal — a foreground pipeline whose first stage
+/// finished. Reading `/proc/<tpgid>` directly then finds nothing and reports
+/// idle, so the group has to be searched for a live member.
+///
+/// Needs an interactive shell: job control is what puts a pipeline in its own
+/// process group, and that is how the daemon spawns commands
+/// (`$SHELL -lic '<cmd>'`).
+#[test]
+fn a_foreground_pipeline_whose_leader_exited_is_still_awaiting_input() {
+    let fx = TmuxFixture::new();
+    let cwd = TempDir::new().unwrap();
+    let id = Uuid::new_v4();
+    fx.tmux
+        .new_session(id, cwd.path(), "bash --noprofile --norc -i")
+        .expect("new_session");
+    wait_for_awaiting(&fx, id, true, "the shell must settle first");
+
+    // `true` leads the group and exits immediately; the right-hand stage
+    // survives, blocked reading the terminal.
+    fx.tmux
+        .send_keys(id, b"true | { read -r line < /dev/tty; }\n")
+        .expect("send_keys");
+
+    // Wait for the state this test exists for: the foreground group is no
+    // longer the shell's own, and its leader is gone. Asserting before that
+    // would pass against a leader-only lookup, because the shell is still
+    // foreground and alive.
+    let pane = fx.tmux.pane_info(id).expect("pane_info").expect("pane");
+    let deadline = std::time::Instant::now() + Duration::from_secs(5);
+    let mut reached = false;
+    while std::time::Instant::now() < deadline {
+        if let Some((pgrp, tpgid)) = pgrp_and_tpgid(pane.pane_pid) {
+            if tpgid > 0 && tpgid != pgrp && pgrp_and_tpgid(tpgid).is_none() {
+                reached = true;
+                break;
+            }
+        }
+        std::thread::sleep(Duration::from_millis(20));
+    }
+    assert!(
+        reached,
+        "never observed a foreground group whose leader had exited"
+    );
+
+    // 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/activity_report.rs

@@ -0,0 +1,164 @@
+//! Agent-reported activity (#105): `POST /api/sessions/:id/activity`
+//! semantics at the SessionManager level — precedence over the daemon's own
+//! inference, detail handling, and lapse back to inference at the TTL.
+
+mod common;
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use common::TmuxFixture;
+use maestro_daemon::sidecar::SidecarStore;
+use maestro_daemon::worktree::WorktreeManager;
+use maestro_daemon::SessionManager;
+use maestro_protocol::{ActivityState, CreateSessionRequest};
+use tempfile::TempDir;
+use tokio::time::sleep;
+use uuid::Uuid;
+
+struct Fixture {
+    manager: SessionManager,
+    _tmux: TmuxFixture,
+    _state_dir: TempDir,
+}
+
+async fn fixture(ttl: Duration) -> Fixture {
+    let tmux = TmuxFixture::new();
+    let state_dir = TempDir::new().unwrap();
+    let manager = SessionManager::new(
+        Arc::new(tmux.tmux.clone()),
+        SidecarStore::new(state_dir.path().join("sessions")),
+        WorktreeManager::new(None),
+        state_dir.path().join("fifos"),
+    )
+    .with_activity_report_ttl(ttl);
+    Fixture {
+        manager,
+        _tmux: tmux,
+        _state_dir: state_dir,
+    }
+}
+
+async fn spawn_sleeping(manager: &SessionManager) -> Uuid {
+    manager
+        .create(CreateSessionRequest {
+            cwd: "/tmp".into(),
+            command: "sleep 60".into(),
+            env: Default::default(),
+            metadata: Default::default(),
+            worktree: None,
+        })
+        .await
+        .unwrap()
+        .id
+}
+
+async fn observed(manager: &SessionManager, id: Uuid) -> maestro_protocol::Session {
+    manager
+        .snapshot()
+        .await
+        .into_iter()
+        .find(|s| s.id == id)
+        .expect("session still tracked")
+}
+
+#[tokio::test]
+async fn report_on_unknown_session_is_not_found() {
+    let fx = fixture(Duration::from_secs(300)).await;
+    let err = fx
+        .manager
+        .report_activity(Uuid::new_v4(), ActivityState::Idle, None)
+        .await
+        .unwrap_err();
+    assert!(matches!(err, maestro_daemon::SessionError::NotFound(_)));
+}
+
+#[tokio::test]
+async fn report_sets_error_state_and_detail() {
+    let fx = fixture(Duration::from_secs(300)).await;
+    let id = spawn_sleeping(&fx.manager).await;
+
+    fx.manager
+        .report_activity(
+            id,
+            ActivityState::Error,
+            Some("cargo build failed: link error".into()),
+        )
+        .await
+        .unwrap();
+
+    let s = observed(&fx.manager, id).await;
+    assert_eq!(s.activity, ActivityState::Error);
+    assert_eq!(
+        s.activity_detail.as_deref(),
+        Some("cargo build failed: link error")
+    );
+}
+
+#[tokio::test]
+async fn replacing_a_report_replaces_both_state_and_detail() {
+    let fx = fixture(Duration::from_secs(300)).await;
+    let id = spawn_sleeping(&fx.manager).await;
+
+    fx.manager
+        .report_activity(id, ActivityState::Error, Some("first failure".into()))
+        .await
+        .unwrap();
+    fx.manager
+        .report_activity(
+            id,
+            ActivityState::AwaitingInput,
+            Some("needs approval".into()),
+        )
+        .await
+        .unwrap();
+
+    let s = observed(&fx.manager, id).await;
+    assert_eq!(s.activity, ActivityState::AwaitingInput);
+    assert_eq!(s.activity_detail.as_deref(), Some("needs approval"));
+}
+
+#[tokio::test]
+async fn detail_is_capped_server_side() {
+    let fx = fixture(Duration::from_secs(300)).await;
+    let id = spawn_sleeping(&fx.manager).await;
+
+    let long = "x".repeat(10_000);
+    fx.manager
+        .report_activity(id, ActivityState::Error, Some(long))
+        .await
+        .unwrap();
+
+    let s = observed(&fx.manager, id).await;
+    let detail = s.activity_detail.expect("detail present");
+    assert_eq!(
+        detail.chars().count(),
+        maestro_daemon::MAX_REPORT_DETAIL_CHARS
+    );
+}
+
+#[tokio::test]
+async fn reported_state_survives_watcher_ticks_until_the_ttl_then_inference_resumes() {
+    let fx = fixture(Duration::from_millis(150)).await;
+    let id = spawn_sleeping(&fx.manager).await;
+    fx.manager.start_liveness_watcher(Duration::from_millis(50));
+
+    fx.manager
+        .report_activity(id, ActivityState::Error, Some("agent died mid-run".into()))
+        .await
+        .unwrap();
+
+    // Several watcher ticks inside the TTL: nothing infers `Error`, so the
+    // report must hold above inference.
+    sleep(Duration::from_millis(80)).await;
+    let s = observed(&fx.manager, id).await;
+    assert_eq!(s.activity, ActivityState::Error);
+    assert_eq!(s.activity_detail.as_deref(), Some("agent died mid-run"));
+
+    // After the TTL lapses, inference resumes and the detail goes with it.
+    common::wait_for_async(Duration::from_secs(5), || async {
+        let s = observed(&fx.manager, id).await;
+        s.activity != ActivityState::Error && s.activity_detail.is_none()
+    })
+    .await;
+}

crates/maestro-daemon/tests/attach.rs

@@ -11,7 +11,7 @@ use std::time::Duration;
 
 use common::DaemonFixture;
 use futures_util::{SinkExt, StreamExt};
-use maestro_daemon::{local_api, LocalEventBus, SessionManager};
+use maestro_daemon::{local_api, SessionManager};
 use maestro_protocol::CreateSessionRequest;
 use tempfile::TempDir;
 use tokio::net::TcpListener;
@@ -37,7 +37,7 @@ async fn spawn_daemon_ws() -> Harness {
         "test-host",
         "/home/test",
         Vec::new(),
-        LocalEventBus::new(),
+        std::sync::Arc::new(maestro_daemon::projects::ProjectScanner::disabled()),
     ));
     let listener = TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, 0)))
         .await
@@ -121,7 +121,7 @@ async fn pty_round_trip_through_real_tmux() {
         "marker not seen in {} bytes",
         got.len()
     );
-    let _ = h.manager.kill(id).await;
+    let _ = h.manager.kill(id, false).await;
 }
 
 #[tokio::test]
@@ -169,7 +169,7 @@ async fn multi_attach_broadcasts_to_every_client() {
         "client B missed marker"
     );
 
-    let _ = h.manager.kill(id).await;
+    let _ = h.manager.kill(id, false).await;
 }
 
 #[tokio::test]
@@ -218,7 +218,7 @@ async fn sends_close_frame_when_session_is_killed() {
     // give the broadcast subscriber a moment to register before killing.
     tokio::time::sleep(Duration::from_millis(100)).await;
 
-    h.manager.kill(id).await.unwrap();
+    h.manager.kill(id, false).await.unwrap();
 
     let mut saw_close = false;
     let deadline = std::time::Instant::now() + Duration::from_secs(2);
@@ -266,7 +266,7 @@ async fn ping_text_frame_gets_pong() {
         }
     }
     assert!(saw_pong, "no Pong frame received");
-    let _ = h.manager.kill(id).await;
+    let _ = h.manager.kill(id, false).await;
 }
 
 #[tokio::test]
@@ -326,3 +326,57 @@ async fn second_attach_sees_replay_buffer_of_prior_output() {
         "fresh attach did not receive replay containing prior output"
     );
 }
+
+/// The point of keeping a dead session: attach afterwards and read what it
+/// printed before it died. The stream then ends rather than hanging.
+#[tokio::test]
+async fn attaching_to_a_dead_session_replays_its_final_output() {
+    let h = spawn_daemon_ws().await;
+    let id = create_bash_session(&h).await;
+
+    // Produce output, then let the session die out-of-band.
+    {
+        let mut ws = connect_attach(h.addr, id).await.unwrap();
+        ws.send(WsMessage::Binary(b"echo last-words\n".to_vec()))
+            .await
+            .unwrap();
+        tokio::time::sleep(Duration::from_millis(300)).await;
+    }
+    h.manager.start_liveness_watcher(Duration::from_millis(50));
+    h._fx.tmux.tmux.kill_session(id).expect("kill tmux");
+
+    // Wait for the daemon to notice.
+    let deadline = std::time::Instant::now() + Duration::from_secs(3);
+    while std::time::Instant::now() < deadline {
+        if h.manager.status(id).await == Some(maestro_protocol::SessionStatus::Dead) {
+            break;
+        }
+        tokio::time::sleep(Duration::from_millis(25)).await;
+    }
+    assert_eq!(
+        h.manager.status(id).await,
+        Some(maestro_protocol::SessionStatus::Dead),
+        "session should be marked dead, not removed"
+    );
+
+    let mut ws = connect_attach(h.addr, id)
+        .await
+        .expect("a dead session must still accept an attach");
+
+    let mut seen = Vec::new();
+    let deadline = std::time::Instant::now() + Duration::from_secs(3);
+    while std::time::Instant::now() < deadline {
+        match tokio::time::timeout(Duration::from_millis(200), ws.next()).await {
+            Ok(Some(Ok(WsMessage::Binary(b)))) => seen.extend_from_slice(&b),
+            Ok(Some(Ok(WsMessage::Close(_)))) | Ok(None) => break,
+            Ok(Some(Ok(_))) => continue,
+            Ok(Some(Err(_))) => break,
+            Err(_) => continue,
+        }
+    }
+    let text = String::from_utf8_lossy(&seen);
+    assert!(
+        text.contains("last-words"),
+        "replay of a dead session lost its final output: {text:?}"
+    );
+}

crates/maestro-daemon/tests/blocked_work_cost.rs

@@ -0,0 +1,116 @@
+//! The performance contract of #83: the blocked-work pass must cost NO git
+//! probe at all for a session without a worktree, while a session with one is
+//! still probed.
+//!
+//! `git` itself is shimmed through PATH with a wrapper that logs every
+//! invocation before exec'ing the real binary, so the assertion counts actual
+//! probes rather than inferring them from state. This lives in its own test
+//! binary because it mutates the process environment.
+
+mod common;
+
+use std::collections::HashMap;
+use std::process::Command;
+use std::time::Duration;
+
+use common::{init_bare_repo, init_repo, push_all_to_origin, wait_for_async, DaemonFixture};
+use maestro_protocol::{CreateSessionRequest, InTheWay, WorktreeSpec};
+use tempfile::TempDir;
+
+fn request(cwd: &std::path::Path, repo: &std::path::Path, branch: &str) -> CreateSessionRequest {
+    CreateSessionRequest {
+        cwd: cwd.to_path_buf(),
+        command: "sleep 30".into(),
+        env: HashMap::new(),
+        metadata: HashMap::new(),
+        worktree: Some(WorktreeSpec {
+            base_repo: repo.to_path_buf(),
+            branch: branch.into(),
+            create_branch: true,
+        }),
+    }
+}
+
+#[tokio::test]
+async fn a_session_without_a_worktree_costs_no_probe() {
+    let fx = DaemonFixture::new();
+    let log = TempDir::new().unwrap();
+    let log_path = log.path().join("git-calls.log");
+
+    // Session A owns a real (pristine, pushed) worktree; session B has none.
+    let repo_a = TempDir::new().unwrap();
+    init_repo(repo_a.path());
+    init_bare_repo(&repo_a.path().join("origin.git"));
+    push_all_to_origin(repo_a.path(), &repo_a.path().join("origin.git"));
+    fx.manager
+        .create(request(repo_a.path(), repo_a.path(), "feat/probed"))
+        .await
+        .expect("create A");
+
+    let cwd_b = TempDir::new().unwrap();
+    let mut req_b = request(cwd_b.path(), cwd_b.path(), "feat/unused");
+    req_b.worktree = None;
+    fx.manager.create(req_b).await.expect("create B");
+
+    // Shim `git` AFTER setup so only watcher-driven probes get logged.
+    let real_git = String::from_utf8(
+        Command::new("sh")
+            .arg("-c")
+            .arg("command -v git")
+            .output()
+            .expect("locate git")
+            .stdout,
+    )
+    .unwrap()
+    .trim()
+    .to_string();
+    let shim_dir = TempDir::new().unwrap();
+    let script = format!(
+        "#!/bin/sh\nprintf '%s\\n' \"$*\" >> {}\nexec {} \"$@\"\n",
+        log_path.display(),
+        real_git,
+    );
+    std::fs::write(shim_dir.path().join("git"), script).unwrap();
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        std::fs::set_permissions(
+            shim_dir.path().join("git"),
+            std::fs::Permissions::from_mode(0o755),
+        )
+        .unwrap();
+    }
+    let old_path = std::env::var("PATH").unwrap_or_default();
+    std::env::set_var(
+        "PATH",
+        format!("{}:{}", shim_dir.path().display(), old_path),
+    );
+
+    fx.manager.start_liveness_watcher_with_blocked_work(
+        Duration::from_millis(50),
+        Duration::from_millis(100),
+    );
+
+    // The pass demonstrably runs and probed A's tree...
+    wait_for_async(Duration::from_secs(5), || async {
+        fx.manager
+            .snapshot()
+            .await
+            .iter()
+            .any(|s| s.worktree.is_some() && s.blocked_work == Some(InTheWay::default()))
+    })
+    .await;
+
+    std::env::set_var("PATH", &old_path);
+
+    let calls = std::fs::read_to_string(&log_path).unwrap_or_default();
+    assert!(
+        !calls.is_empty(),
+        "the pass never probed anything — the shim saw no git call at all"
+    );
+    // ...while B — no worktree, so nothing to probe — was never touched.
+    assert!(
+        !calls.contains(cwd_b.path().to_str().unwrap()),
+        "a worktree-less session was probed:\n{calls}"
+    );
+}

crates/maestro-daemon/tests/branches.rs

@@ -0,0 +1,141 @@
+//! Integration tests for `GET /api/branches` (#55).
+
+mod common;
+
+use std::net::{Ipv4Addr, SocketAddr};
+use std::path::Path;
+use std::process::Command;
+use std::sync::Arc;
+
+use common::DaemonFixture;
+use maestro_daemon::local_api;
+use tokio::net::TcpListener;
+use tokio::sync::oneshot;
+
+struct Harness {
+    addr: SocketAddr,
+    _shutdown: oneshot::Sender<()>,
+    _fx: DaemonFixture,
+}
+
+async fn spawn() -> Harness {
+    let fx = DaemonFixture::new();
+    let presets = maestro_config::SpawnSection::default().resolve().unwrap();
+    let router = local_api::router(local_api::state_for(
+        fx.manager.clone(),
+        "naps-laptop",
+        "/home/test",
+        presets,
+        Arc::new(maestro_daemon::projects::ProjectScanner::disabled()),
+    ));
+    let listener = TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, 0)))
+        .await
+        .unwrap();
+    let addr = listener.local_addr().unwrap();
+    let (tx, rx) = oneshot::channel::<()>();
+    tokio::spawn(async move {
+        let _ = axum::serve(listener, router)
+            .with_graceful_shutdown(async move {
+                let _ = rx.await;
+            })
+            .await;
+    });
+    Harness {
+        addr,
+        _shutdown: tx,
+        _fx: fx,
+    }
+}
+
+fn git(repo: &Path, args: &[&str]) {
+    let out = Command::new("git")
+        .arg("-C")
+        .arg(repo)
+        .args(args)
+        .output()
+        .unwrap();
+    assert!(
+        out.status.success(),
+        "git {args:?} failed: {}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+}
+
+/// A real repo on `main` with a second branch `feature`, and a linked
+/// worktree at `<tmp>/wt-feature` holding `feature`.
+fn repo_with_occupied_branch() -> tempfile::TempDir {
+    let tmp = tempfile::tempdir().unwrap();
+    let repo = tmp.path();
+    git(repo, &["init", "-q", "-b", "main"]);
+    git(
+        repo,
+        &[
+            "-c",
+            "user.email=t@t",
+            "-c",
+            "user.name=t",
+            "commit",
+            "-qm",
+            "init",
+            "--allow-empty",
+        ],
+    );
+    git(repo, &["branch", "feature"]);
+    let wt = tmp.path().join("wt-feature");
+    git(repo, &["worktree", "add", &wt.to_string_lossy(), "feature"]);
+    tmp
+}
+
+async fn get_branches(addr: SocketAddr, path: &Path) -> Vec<maestro_protocol::BranchInfo> {
+    reqwest::get(format!(
+        "http://{addr}/api/branches?path={}",
+        urlencoding::encode(&path.to_string_lossy())
+    ))
+    .await
+    .unwrap()
+    .json()
+    .await
+    .unwrap()
+}
+
+/// #55: every local branch is listed; the main checkout's HEAD reports
+/// `is_head`, and a branch held by a linked worktree reports that worktree's
+/// path so the client can explain why the entry is disabled.
+#[tokio::test]
+async fn branches_lists_local_branches_and_worktree_occupancy() {
+    let tmp = repo_with_occupied_branch();
+    let h = spawn().await;
+
+    let mut branches = get_branches(h.addr, tmp.path()).await;
+    branches.sort_by(|a, b| a.name.cmp(&b.name));
+
+    assert_eq!(
+        branches.iter().map(|b| b.name.as_str()).collect::<Vec<_>>(),
+        ["feature", "main"]
+    );
+
+    let main = branches.iter().find(|b| b.name == "main").unwrap();
+    assert!(main.is_head, "main is the main checkout's HEAD");
+    assert_eq!(main.worktree, None, "HEAD occupancy rides `is_head`");
+
+    let feature = branches.iter().find(|b| b.name == "feature").unwrap();
+    assert!(!feature.is_head);
+    assert_eq!(
+        feature.worktree.as_deref(),
+        Some(tmp.path().join("wt-feature").as_path()),
+        "the linked worktree holding the branch must be reported"
+    );
+}
+
+/// #55: a path outside any repository is not an error — an empty list,
+/// matching how `/api/gitroot` reports "not a repository".
+#[tokio::test]
+async fn branches_returns_empty_for_a_path_outside_a_repository() {
+    let h = spawn().await;
+    let tmp = tempfile::tempdir().unwrap();
+    let plain = tmp.path().join("plain");
+    std::fs::create_dir_all(&plain).unwrap();
+
+    let branches = get_branches(h.addr, &plain).await;
+    assert!(branches.is_empty());
+}

crates/maestro-daemon/tests/common/mod.rs

@@ -7,6 +7,7 @@
 use std::future::Future;
 use std::path::{Path, PathBuf};
 use std::process::Command;
+use std::sync::Arc;
 use std::thread;
 use std::time::{Duration, Instant};
 
@@ -92,6 +93,38 @@ fn run(cmd: &mut Command) {
     );
 }
 
+/// An empty bare repository at `dir`, usable as a push target (#79).
+pub fn init_bare_repo(dir: &Path) {
+    run(Command::new("git")
+        .arg("init")
+        .arg("-q")
+        .arg("--bare")
+        .arg(dir.to_str().expect("non-utf8 bare repo path")));
+}
+
+/// Push every branch of `repo` to `origin`, creating remote-tracking refs.
+///
+/// The unsaved-work probe (#79) counts commits reachable from no
+/// remote-tracking ref as unpushed, so tests that want a killable worktree
+/// must give its branch one. Safe to call again: re-adding an existing
+/// remote is ignored.
+pub fn push_all_to_origin(repo: &Path, origin: &Path) {
+    let _ = Command::new("git")
+        .arg("-C")
+        .arg(repo)
+        .args([
+            "remote",
+            "add",
+            "origin",
+            origin.to_str().expect("non-utf8 origin path"),
+        ])
+        .status();
+    run(Command::new("git")
+        .arg("-C")
+        .arg(repo)
+        .args(["push", "-q", "--all", "origin"]));
+}
+
 /// Async polling sibling of [`wait_for`] for tokio tests.
 pub async fn wait_for_async<F, Fut>(timeout: Duration, mut cond: F)
 where
@@ -114,7 +147,6 @@ pub struct DaemonFixture {
     pub tmux: TmuxFixture,
     pub manager: SessionManager,
     pub state_dir: TempDir,
-    pub worktree_root: TempDir,
 }
 
 impl DaemonFixture {
@@ -131,11 +163,11 @@ impl DaemonFixture {
     fn build(history_days: Option<u32>) -> Self {
         let tmux = TmuxFixture::new();
         let state_dir = TempDir::new().unwrap();
-        let worktree_root = TempDir::new().unwrap();
         let sidecar = SidecarStore::new(state_dir.path().join("sessions"));
-        let worktree_mgr = WorktreeManager::new(worktree_root.path().to_path_buf());
+        // Default placement: worktrees land under their base repo (#56).
+        let worktree_mgr = WorktreeManager::new(None);
         let mut manager = SessionManager::new(
-            tmux.tmux.clone(),
+            Arc::new(tmux.tmux.clone()),
             sidecar,
             worktree_mgr,
             state_dir.path().join("fifos"),
@@ -148,7 +180,6 @@ impl DaemonFixture {
             tmux,
             manager,
             state_dir,
-            worktree_root,
         }
     }
 

crates/maestro-daemon/tests/local_api.rs

@@ -8,8 +8,8 @@ use std::time::Duration;
 
 use common::DaemonFixture;
 use futures_util::{SinkExt, StreamExt};
-use maestro_daemon::{local_api, LocalEventBus};
-use maestro_protocol::{CreateSessionRequest, Session};
+use maestro_daemon::local_api;
+use maestro_protocol::{ApiError, CreateSessionRequest, Session, WorktreeSpec};
 use tokio::net::TcpListener;
 use tokio::sync::oneshot;
 use tokio_tungstenite::tungstenite::Message as WsMessage;
@@ -26,9 +26,19 @@ struct Harness {
 }
 
 async fn spawn(hostname: &str) -> Harness {
+    spawn_with(
+        hostname,
+        std::sync::Arc::new(maestro_daemon::projects::ProjectScanner::disabled()),
+    )
+    .await
+}
+
+async fn spawn_with(
+    hostname: &str,
+    projects: std::sync::Arc<maestro_daemon::projects::ProjectScanner>,
+) -> Harness {
     let fx = DaemonFixture::new();
     let manager = fx.manager.clone();
-    let events = LocalEventBus::new();
     // Built-in presets (claude/opencode/zsh + custom) so `/api/info` advertises
     // a known set (#26).
     let presets = maestro_config::SpawnSection::default().resolve().unwrap();
@@ -37,7 +47,7 @@ async fn spawn(hostname: &str) -> Harness {
         hostname,
         "/home/test",
         presets,
-        events,
+        projects,
     ));
     let listener = TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, 0)))
         .await
@@ -63,6 +73,10 @@ fn url(addr: SocketAddr, path: &str) -> String {
     format!("http://{addr}{path}")
 }
 
+fn ws_url(addr: SocketAddr, path: &str) -> String {
+    format!("ws://{addr}{path}")
+}
+
 #[tokio::test]
 async fn info_returns_daemon_identity() {
     let h = spawn("naps-laptop").await;
@@ -151,6 +165,121 @@ async fn recent_dirs_returns_empty_without_history() {
     assert_eq!(resp["truncated"], false);
 }
 
+/// #54: `GET /api/projects` lists every git repo under the scan roots, with
+/// real git checkouts — not mocks.
+#[tokio::test]
+async fn projects_lists_repos_under_the_scan_roots() {
+    let tmp = tempfile::tempdir().unwrap();
+    for name in ["alpha", "beta"] {
+        let repo = tmp.path().join(name);
+        std::fs::create_dir_all(&repo).unwrap();
+        for args in [
+            vec!["init", "-q"],
+            vec![
+                "-c",
+                "user.email=t@t",
+                "-c",
+                "user.name=t",
+                "commit",
+                "-qm",
+                "init",
+                "--allow-empty",
+            ],
+        ] {
+            let out = std::process::Command::new("git")
+                .arg("-C")
+                .arg(&repo)
+                .args(&args)
+                .output()
+                .unwrap();
+            assert!(out.status.success());
+        }
+    }
+
+    let scanner = std::sync::Arc::new(maestro_daemon::projects::ProjectScanner::new(
+        vec![tmp.path().to_path_buf()],
+        3,
+        tmp.path().to_path_buf(),
+    ));
+    let h = spawn_with("naps-laptop", scanner).await;
+
+    let projects: Vec<maestro_protocol::Project> = reqwest::get(url(h.addr, "/api/projects"))
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+
+    let mut names: Vec<&str> = projects.iter().map(|p| p.name.as_str()).collect();
+    names.sort();
+    assert_eq!(names, ["alpha", "beta"]);
+    for p in &projects {
+        assert!(!p.is_worktree);
+        assert_eq!(p.base_repo, None);
+        assert!(p.last_activity.is_some(), "fresh commit ⇒ HEAD mtime known");
+    }
+}
+
+#[tokio::test]
+async fn projects_returns_empty_for_a_disabled_scanner() {
+    let h = spawn("naps-laptop").await;
+    let projects: Vec<maestro_protocol::Project> = reqwest::get(url(h.addr, "/api/projects"))
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    assert!(projects.is_empty());
+}
+
+/// #53: every returned handle is one word from the shared list.
+fn assert_valid_names(batch: &maestro_protocol::NameBatch) {
+    for name in &batch.names {
+        assert!(!name.contains('-'), "handle {name:?} is not one word");
+        assert!(
+            maestro_names::WORDS.contains(&name.as_str()),
+            "{name} not in WORDS"
+        );
+    }
+}
+
+#[tokio::test]
+async fn names_defaults_to_one_handle() {
+    let h = spawn("naps-laptop").await;
+    let batch: maestro_protocol::NameBatch = reqwest::get(url(h.addr, "/api/names"))
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    assert_eq!(batch.names.len(), 1);
+    assert_valid_names(&batch);
+}
+
+#[tokio::test]
+async fn names_honors_count_and_caps_it() {
+    use maestro_names::MAX_BATCH;
+    let h = spawn("naps-laptop").await;
+
+    let batch: maestro_protocol::NameBatch = reqwest::get(url(h.addr, "/api/names?count=5"))
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    assert_eq!(batch.names.len(), 5);
+    assert_valid_names(&batch);
+
+    let batch: maestro_protocol::NameBatch =
+        reqwest::get(url(h.addr, &format!("/api/names?count={}", MAX_BATCH * 10)))
+            .await
+            .unwrap()
+            .json()
+            .await
+            .unwrap();
+    assert_eq!(batch.names.len(), MAX_BATCH);
+}
+
 #[tokio::test]
 async fn gitroot_probes_path() {
     // #26: resolves the query against the daemon home dir and walks up for a
@@ -183,6 +312,48 @@ async fn delete_unknown_session_returns_404() {
     assert_eq!(resp.status(), reqwest::StatusCode::NOT_FOUND);
 }
 
+/// #125: the rename endpoint answers with the updated session, and the name
+/// it stored is the trimmed one.
+#[tokio::test]
+async fn patch_session_renames_it() {
+    let h = spawn("naps-laptop").await;
+    let session = h
+        .manager
+        .create(CreateSessionRequest {
+            cwd: "/tmp".into(),
+            command: "sleep 60".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+        })
+        .await
+        .unwrap();
+    let resp = reqwest::Client::new()
+        .patch(url(h.addr, &format!("/api/sessions/{}", session.id)))
+        .json(&serde_json::json!({ "name": "  crimson-otter " }))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), reqwest::StatusCode::OK);
+    let updated: Session = resp.json().await.unwrap();
+    assert_eq!(
+        updated.metadata.get("name").and_then(|v| v.as_str()),
+        Some("crimson-otter")
+    );
+}
+
+#[tokio::test]
+async fn patch_unknown_session_returns_404() {
+    let h = spawn("naps-laptop").await;
+    let resp = reqwest::Client::new()
+        .patch(url(h.addr, &format!("/api/sessions/{}", Uuid::new_v4())))
+        .json(&serde_json::json!({ "name": "nope" }))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), reqwest::StatusCode::NOT_FOUND);
+}
+
 #[tokio::test]
 async fn delete_owned_session_kills_it() {
     let h = spawn("naps-laptop").await;
@@ -206,6 +377,198 @@ async fn delete_owned_session_kills_it() {
     assert!(!h.manager.has(session.id).await);
 }
 
+/// Spawn a session through the manager and return its id.
+async fn spawn_via_manager(h: &Harness) -> Uuid {
+    h.manager
+        .create(CreateSessionRequest {
+            cwd: "/tmp".into(),
+            command: "sleep 60".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+        })
+        .await
+        .unwrap()
+        .id
+}
+
+/// The agent activity endpoint on the wire (#105): a report lands in the
+/// session snapshot with its detail.
+#[tokio::test]
+async fn post_activity_reports_error_with_detail() {
+    let h = spawn("naps-laptop").await;
+    let id = spawn_via_manager(&h).await;
+
+    let resp = reqwest::Client::new()
+        .post(url(h.addr, &format!("/api/sessions/{id}/activity")))
+        .json(&serde_json::json!({
+            "state": "Error",
+            "detail": "cargo build failed"
+        }))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), reqwest::StatusCode::NO_CONTENT);
+
+    let sessions: Vec<Session> = reqwest::get(url(h.addr, "/api/sessions"))
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    let s = sessions.iter().find(|s| s.id == id).unwrap();
+    assert_eq!(s.activity, maestro_protocol::ActivityState::Error);
+    assert_eq!(s.activity_detail.as_deref(), Some("cargo build failed"));
+}
+
+#[tokio::test]
+async fn post_activity_to_unknown_session_returns_404() {
+    let h = spawn("naps-laptop").await;
+    let resp = reqwest::Client::new()
+        .post(url(
+            h.addr,
+            &format!("/api/sessions/{}/activity", Uuid::new_v4()),
+        ))
+        .json(&serde_json::json!({ "state": "Idle" }))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), reqwest::StatusCode::NOT_FOUND);
+}
+
+/// Unknown state values are rejected rather than coerced (#105).
+#[tokio::test]
+async fn post_activity_rejects_an_unknown_state_value() {
+    let h = spawn("naps-laptop").await;
+    let id = spawn_via_manager(&h).await;
+
+    let resp = reqwest::Client::new()
+        .post(url(h.addr, &format!("/api/sessions/{id}/activity")))
+        .json(&serde_json::json!({ "state": "Teleported" }))
+        .send()
+        .await
+        .unwrap();
+    assert!(resp.status().is_client_error(), "got {}", resp.status());
+}
+
+#[tokio::test]
+async fn post_activity_caps_an_overlong_detail_server_side() {
+    let h = spawn("naps-laptop").await;
+    let id = spawn_via_manager(&h).await;
+
+    let resp = reqwest::Client::new()
+        .post(url(h.addr, &format!("/api/sessions/{id}/activity")))
+        .json(&serde_json::json!({
+            "state": "Error",
+            "detail": "x".repeat(10_000)
+        }))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), reqwest::StatusCode::NO_CONTENT);
+
+    let sessions: Vec<Session> = reqwest::get(url(h.addr, "/api/sessions"))
+        .await
+        .unwrap()
+        .json()
+        .await
+        .unwrap();
+    let s = sessions.iter().find(|s| s.id == id).unwrap();
+    assert_eq!(
+        s.activity_detail.as_ref().map(|d| d.chars().count()),
+        Some(maestro_daemon::MAX_REPORT_DETAIL_CHARS)
+    );
+}
+
+/// The kill guard on the wire (#79): `DELETE /api/sessions/:id` answers 409
+/// with the structured breakdown, and the session keeps running.
+#[tokio::test]
+async fn delete_a_session_whose_worktree_holds_unsaved_work_returns_409_with_the_breakdown() {
+    let h = spawn("naps-laptop").await;
+    let repo = tempfile::TempDir::new().unwrap();
+    common::init_repo(repo.path());
+    let session = h
+        .manager
+        .create(CreateSessionRequest {
+            cwd: repo.path().to_path_buf(),
+            command: "sleep 60".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: repo.path().to_path_buf(),
+                branch: "feat/guarded".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .unwrap();
+    std::fs::write(
+        repo.path()
+            .join("worktrees")
+            .join("feat")
+            .join("guarded")
+            .join("README"),
+        b"unsaved edits\n",
+    )
+    .unwrap();
+
+    let resp = reqwest::Client::new()
+        .delete(url(h.addr, &format!("/api/sessions/{}", session.id)))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), reqwest::StatusCode::CONFLICT);
+    let body: ApiError = resp.json().await.unwrap();
+    assert_eq!(body.error.code, "kill_guarded");
+    let breakdown = body.error.unsaved_work.expect("breakdown on the wire");
+    assert_eq!(breakdown.uncommitted_files, 1);
+
+    assert!(h.manager.has(session.id).await, "the session keeps running");
+}
+
+/// `?force=true` on the wire (#81): the refusal is overridden and the session
+/// ends, while the guarded worktree survives on disk.
+#[tokio::test]
+async fn delete_with_force_ends_the_session_and_keeps_the_worktree() {
+    let h = spawn("naps-laptop").await;
+    let repo = tempfile::TempDir::new().unwrap();
+    common::init_repo(repo.path());
+    let wt_path = repo
+        .path()
+        .join("worktrees")
+        .join("feat")
+        .join("guarded")
+        .to_path_buf();
+    let session = h
+        .manager
+        .create(CreateSessionRequest {
+            cwd: repo.path().to_path_buf(),
+            command: "sleep 60".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: repo.path().to_path_buf(),
+                branch: "feat/guarded".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .unwrap();
+    std::fs::write(wt_path.join("README"), b"unsaved edits\n").unwrap();
+
+    let resp = reqwest::Client::new()
+        .delete(url(h.addr, &format!("/api/sessions/{}", session.id)))
+        .query(&[("force", "true")])
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), reqwest::StatusCode::NO_CONTENT);
+
+    // The tree would have blocked; force must not have removed it.
+    assert!(wt_path.exists(), "a forced kill never removes the worktree");
+    assert!(!h.manager.has(session.id).await, "the session is gone");
+}
+
 #[tokio::test]
 async fn attach_ws_streams_pty_bytes() {
     let h = spawn("naps-laptop").await;
@@ -260,3 +623,103 @@ async fn attach_ws_for_unknown_session_returns_404() {
         "{msg}"
     );
 }
+
+/// `WS /api/events` had no daemon-level test: the Snapshot-then-deltas contract
+/// and the subscribe-before-snapshot ordering were only described in a comment.
+#[tokio::test]
+async fn events_ws_sends_a_snapshot_then_streams_deltas() {
+    let h = spawn("konishi").await;
+    let cwd = tempfile::TempDir::new().unwrap();
+
+    let (mut ws, _) = connect_async(ws_url(h.addr, "/api/events"))
+        .await
+        .expect("events ws");
+
+    match next_event(&mut ws).await {
+        maestro_protocol::CatalogEvent::Snapshot { sessions } => assert!(sessions.is_empty()),
+        other => panic!("first frame must be a Snapshot, got {other:?}"),
+    }
+
+    let created = h
+        .manager
+        .create(CreateSessionRequest {
+            cwd: cwd.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+        })
+        .await
+        .expect("create");
+
+    match next_event(&mut ws).await {
+        maestro_protocol::CatalogEvent::SessionAdded { session } => {
+            assert_eq!(session.id, created.id);
+        }
+        other => panic!("expected SessionAdded, got {other:?}"),
+    }
+
+    h.manager.kill(created.id, false).await.expect("kill");
+
+    // Activity ticks may interleave; the removal is what we are waiting for.
+    let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
+    loop {
+        assert!(
+            tokio::time::Instant::now() < deadline,
+            "timed out waiting for SessionRemoved"
+        );
+        if let maestro_protocol::CatalogEvent::SessionRemoved { id } = next_event(&mut ws).await {
+            assert_eq!(id, created.id);
+            break;
+        }
+    }
+}
+
+/// Each subscriber has its own lag domain now that the publisher task is gone:
+/// two clients connected at different times both get their own Snapshot.
+#[tokio::test]
+async fn every_events_subscriber_gets_its_own_snapshot() {
+    let h = spawn("konishi").await;
+    let cwd = tempfile::TempDir::new().unwrap();
+
+    let (mut first, _) = connect_async(ws_url(h.addr, "/api/events")).await.unwrap();
+    let _ = next_event(&mut first).await;
+
+    h.manager
+        .create(CreateSessionRequest {
+            cwd: cwd.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+        })
+        .await
+        .expect("create");
+
+    let (mut second, _) = connect_async(ws_url(h.addr, "/api/events")).await.unwrap();
+    match next_event(&mut second).await {
+        maestro_protocol::CatalogEvent::Snapshot { sessions } => {
+            assert_eq!(
+                sessions.len(),
+                1,
+                "a late subscriber must see current state"
+            );
+        }
+        other => panic!("expected Snapshot, got {other:?}"),
+    }
+}
+
+async fn next_event(ws: &mut WsClient) -> maestro_protocol::CatalogEvent {
+    loop {
+        match tokio::time::timeout(Duration::from_secs(5), ws.next())
+            .await
+            .expect("events ws timed out")
+        {
+            Some(Ok(WsMessage::Text(t))) => {
+                return serde_json::from_str(&t).expect("decode catalog event")
+            }
+            Some(Ok(_)) => continue,
+            other => panic!("unexpected events frame: {other:?}"),
+        }
+    }
+}

crates/maestro-daemon/tests/rename.rs

@@ -0,0 +1,138 @@
+//! Renaming a live session (#125): `SessionManager::rename` semantics —
+//! what lands in `metadata.name`, what reaches the sidecar, and what goes out
+//! on the event stream.
+
+mod common;
+
+use std::sync::Arc;
+
+use common::TmuxFixture;
+use maestro_daemon::sidecar::SidecarStore;
+use maestro_daemon::worktree::WorktreeManager;
+use maestro_daemon::SessionManager;
+use maestro_protocol::{CatalogEvent, CreateSessionRequest, MAX_SESSION_NAME_LEN};
+use tempfile::TempDir;
+use uuid::Uuid;
+
+struct Fixture {
+    manager: SessionManager,
+    sidecar: SidecarStore,
+    _tmux: TmuxFixture,
+    _state_dir: TempDir,
+}
+
+fn fixture() -> Fixture {
+    let tmux = TmuxFixture::new();
+    let state_dir = TempDir::new().unwrap();
+    let sidecar = SidecarStore::new(state_dir.path().join("sessions"));
+    let manager = SessionManager::new(
+        Arc::new(tmux.tmux.clone()),
+        sidecar.clone(),
+        WorktreeManager::new(None),
+        state_dir.path().join("fifos"),
+    );
+    Fixture {
+        manager,
+        sidecar,
+        _tmux: tmux,
+        _state_dir: state_dir,
+    }
+}
+
+async fn spawn_named(manager: &SessionManager, name: Option<&str>) -> Uuid {
+    let metadata = match name {
+        Some(n) => std::collections::HashMap::from([(
+            "name".to_string(),
+            serde_json::Value::String(n.to_string()),
+        )]),
+        None => Default::default(),
+    };
+    manager
+        .create(CreateSessionRequest {
+            cwd: "/tmp".into(),
+            command: "sleep 60".into(),
+            env: Default::default(),
+            metadata,
+            worktree: None,
+        })
+        .await
+        .unwrap()
+        .id
+}
+
+fn name_of(session: &maestro_protocol::Session) -> Option<&str> {
+    session.metadata.get("name").and_then(|v| v.as_str())
+}
+
+#[tokio::test]
+async fn rename_on_unknown_session_is_not_found() {
+    let fx = fixture();
+    let err = fx
+        .manager
+        .rename(Uuid::new_v4(), "whatever")
+        .await
+        .unwrap_err();
+    assert!(matches!(err, maestro_daemon::SessionError::NotFound(_)));
+}
+
+#[tokio::test]
+async fn rename_sets_the_name_in_memory_and_on_disk() {
+    let fx = fixture();
+    let id = spawn_named(&fx.manager, Some("amber-falcon")).await;
+
+    let renamed = fx.manager.rename(id, "  crimson-otter  ").await.unwrap();
+    assert_eq!(name_of(&renamed), Some("crimson-otter"));
+
+    let snapshot = fx.manager.snapshot().await;
+    let live = snapshot.iter().find(|s| s.id == id).unwrap();
+    assert_eq!(name_of(live), Some("crimson-otter"));
+
+    // A rename a daemon restart would undo is worse than one that failed.
+    let persisted = fx.sidecar.read(id).unwrap().unwrap();
+    assert_eq!(name_of(&persisted), Some("crimson-otter"));
+}
+
+#[tokio::test]
+async fn a_blank_rename_clears_the_name() {
+    let fx = fixture();
+    let id = spawn_named(&fx.manager, Some("amber-falcon")).await;
+
+    let renamed = fx.manager.rename(id, "   ").await.unwrap();
+    assert_eq!(name_of(&renamed), None);
+    // Line 1 falls back to the command, per docs/SIDEBAR.md.
+    assert_eq!(renamed.command, "sleep 60");
+    assert_eq!(name_of(&fx.sidecar.read(id).unwrap().unwrap()), None);
+}
+
+#[tokio::test]
+async fn rename_caps_a_long_name() {
+    let fx = fixture();
+    let id = spawn_named(&fx.manager, None).await;
+    let long = "x".repeat(MAX_SESSION_NAME_LEN + 20);
+    let renamed = fx.manager.rename(id, &long).await.unwrap();
+    assert_eq!(
+        name_of(&renamed).unwrap().chars().count(),
+        MAX_SESSION_NAME_LEN
+    );
+}
+
+#[tokio::test]
+async fn rename_broadcasts_a_session_update() {
+    let fx = fixture();
+    let id = spawn_named(&fx.manager, Some("amber-falcon")).await;
+    let mut events = fx.manager.events();
+
+    fx.manager.rename(id, "crimson-otter").await.unwrap();
+
+    let event = tokio::time::timeout(std::time::Duration::from_secs(5), events.recv())
+        .await
+        .expect("an update within the timeout")
+        .expect("the event channel stays open");
+    match event {
+        CatalogEvent::SessionUpdated { session } => {
+            assert_eq!(session.id, id);
+            assert_eq!(name_of(&session), Some("crimson-otter"));
+        }
+        other => panic!("expected SessionUpdated, got {other:?}"),
+    }
+}

crates/maestro-daemon/tests/session_decisions.rs

@@ -0,0 +1,557 @@
+//! The session manager's decisions, driven through [`FakePanes`].
+//!
+//! These are the branches that used to need a forked tmux server to reach:
+//! spawn rollback ordering, liveness diffing, and activity change-detection.
+//! Nothing here spawns a process, so they run everywhere and in milliseconds.
+
+use std::collections::{BTreeMap, HashMap};
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::Duration;
+
+use maestro_daemon::panes::{Call, FakePanes, Op};
+use maestro_daemon::session::{SessionError, SessionManager};
+use maestro_daemon::sidecar::SidecarStore;
+use maestro_daemon::tmux::PaneInfo;
+use maestro_daemon::worktree::WorktreeManager;
+use maestro_protocol::{ActivityState, CatalogEvent, CreateSessionRequest, SessionStatus};
+use tempfile::TempDir;
+use tokio::sync::broadcast::error::TryRecvError;
+use uuid::Uuid;
+
+struct Fx {
+    manager: SessionManager,
+    fake: Arc<FakePanes>,
+    tmp: TempDir,
+}
+
+impl Fx {
+    fn new() -> Self {
+        Self::with_sidecar_dir(|tmp| tmp.join("sidecars"))
+    }
+
+    /// Variant whose manager knows the daemon's own base URL (#103), the way
+    /// the production runner wires it from `[daemon].bind_addr`.
+    fn with_daemon_url(url: &str) -> Self {
+        let fx = Self::new();
+        fx.manager.set_daemon_url(url.to_string());
+        fx
+    }
+
+    /// The env map of the (single, expected) spawn call.
+    fn spawned_env(&self) -> BTreeMap<String, String> {
+        let calls = self.fake.calls();
+        let Some(Call::NewSessionPiped { env, .. }) = calls.first() else {
+            panic!("expected a spawn call, got {calls:?}");
+        };
+        assert_eq!(calls.len(), 1, "expected exactly one spawn: {calls:?}");
+        env.clone()
+    }
+
+    fn with_sidecar_dir(pick: impl Fn(&std::path::Path) -> PathBuf) -> Self {
+        let tmp = TempDir::new().expect("tempdir");
+        let fake = Arc::new(FakePanes::new());
+        let fifo_dir = tmp.path().join("fifos");
+        std::fs::create_dir_all(&fifo_dir).expect("fifo dir");
+        let manager = SessionManager::new(
+            fake.clone(),
+            SidecarStore::new(pick(tmp.path())),
+            WorktreeManager::new(Some(tmp.path().join("worktrees"))),
+            fifo_dir,
+        );
+        Self { manager, fake, tmp }
+    }
+
+    fn request(&self, command: &str) -> CreateSessionRequest {
+        CreateSessionRequest {
+            cwd: self.tmp.path().to_path_buf(),
+            command: command.into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+        }
+    }
+}
+
+/// Poll until `id` reaches `want`.
+async fn wait_for_status(manager: &SessionManager, id: uuid::Uuid, want: SessionStatus) {
+    let deadline = tokio::time::Instant::now() + Duration::from_secs(3);
+    while tokio::time::Instant::now() < deadline {
+        if manager.status(id).await == Some(want) {
+            return;
+        }
+        tokio::time::sleep(Duration::from_millis(10)).await;
+    }
+    panic!("timed out waiting for {id} to become {want:?}");
+}
+
+/// NAP-260 rollback, asserted as an *ordering* rather than an end state.
+///
+/// Replaces a test that forced the sidecar failure with `chmod 0o500` and then
+/// returned early when it detected root — so on CI it asserted nothing. Here
+/// the sidecar directory cannot be created because a regular file sits where
+/// its parent must be, which no uid can work around.
+#[tokio::test]
+async fn create_kills_the_tmux_session_when_the_sidecar_write_fails() {
+    let fx = Fx::with_sidecar_dir(|tmp| {
+        let blocker = tmp.join("blocker");
+        std::fs::write(&blocker, b"not a directory").expect("blocker file");
+        blocker.join("sidecars")
+    });
+
+    let res = fx.manager.create(fx.request("sleep 30")).await;
+
+    assert!(
+        matches!(res, Err(SessionError::Sidecar(_))),
+        "expected the sidecar write to fail, got {res:?}"
+    );
+
+    let calls = fx.fake.calls();
+    assert_eq!(
+        calls.len(),
+        2,
+        "expected spawn then rollback kill, got {calls:?}"
+    );
+    assert!(matches!(calls[0], Call::NewSessionPiped { .. }));
+    let Call::NewSessionPiped { id, .. } = calls[0] else {
+        unreachable!()
+    };
+    assert_eq!(
+        calls[1],
+        Call::KillSession(id),
+        "the rollback must kill the session it just spawned"
+    );
+
+    assert!(!fx.fake.is_live(id), "create left a ghost tmux session");
+    assert!(fx.manager.snapshot().await.is_empty());
+}
+
+/// A failed spawn must not roll back anything, least of all kill a session id
+/// tmux never accepted.
+#[tokio::test]
+async fn create_does_not_roll_back_when_the_spawn_itself_fails() {
+    let fx = Fx::new();
+    fx.fake.fail(Op::NewSessionPiped, "no server running");
+
+    let res = fx.manager.create(fx.request("sleep 30")).await;
+    assert!(res.is_err(), "expected the spawn to fail, got {res:?}");
+
+    assert_eq!(
+        fx.fake.calls().len(),
+        1,
+        "only the failed spawn should have been attempted: {:?}",
+        fx.fake.calls()
+    );
+    assert!(fx.manager.snapshot().await.is_empty());
+}
+
+/// A restarted daemon adopts whatever tmux still holds, and must re-pipe each
+/// one — without that the adopted session produces no output.
+#[tokio::test]
+async fn recover_adopts_live_sessions_and_repipes_them() {
+    let fx = Fx::new();
+    let orphan = Uuid::new_v4();
+    fx.fake.add_live(orphan);
+
+    let adopted = fx.manager.recover().await.expect("recover");
+    assert_eq!(adopted, 1);
+
+    let snap = fx.manager.snapshot().await;
+    assert_eq!(snap.len(), 1);
+    assert_eq!(snap[0].id, orphan);
+
+    assert!(
+        fx.fake.calls().contains(&Call::PipePane(orphan)),
+        "adopted session was never re-piped: {:?}",
+        fx.fake.calls()
+    );
+}
+
+/// A session tmux lost is marked `Dead` and kept, so the operator can still see
+/// it exited and read what it printed. It is not removed.
+#[tokio::test]
+async fn liveness_marks_the_lost_session_dead_and_keeps_it() {
+    let fx = Fx::new();
+    let keep = fx.manager.create(fx.request("keep")).await.expect("keep");
+    let lose = fx.manager.create(fx.request("lose")).await.expect("lose");
+    let mut events = fx.manager.events();
+
+    fx.fake.remove_live(lose.id);
+    fx.manager.start_liveness_watcher(Duration::from_millis(25));
+    wait_for_status(&fx.manager, lose.id, SessionStatus::Dead).await;
+
+    let all = fx.manager.snapshot().await;
+    assert_eq!(all.len(), 2, "the dead session must stay in the catalog");
+    let survivor = all.iter().find(|s| s.id == keep.id).expect("keep");
+    assert_eq!(survivor.status, SessionStatus::Running);
+
+    let mut removed = Vec::new();
+    while let Ok(ev) = events.try_recv() {
+        if let CatalogEvent::SessionRemoved { id } = ev {
+            removed.push(id);
+        }
+    }
+    assert!(removed.is_empty(), "nothing should be removed: {removed:?}");
+}
+
+/// The transition fires once. Without the Running filter the pass re-announces
+/// the same dead session on every tick, forever.
+#[tokio::test]
+async fn a_dead_session_is_announced_only_once() {
+    let fx = Fx::new();
+    let s = fx.manager.create(fx.request("bash")).await.expect("create");
+    let mut events = fx.manager.events();
+
+    fx.fake.remove_live(s.id);
+    fx.manager.start_liveness_watcher(Duration::from_millis(25));
+    wait_for_status(&fx.manager, s.id, SessionStatus::Dead).await;
+
+    let mut dead_updates = 0;
+    let deadline = tokio::time::Instant::now() + Duration::from_millis(300);
+    while tokio::time::Instant::now() < deadline {
+        if let Ok(CatalogEvent::SessionUpdated { session }) = events.try_recv() {
+            if session.status == SessionStatus::Dead {
+                dead_updates += 1;
+            }
+        }
+        tokio::time::sleep(Duration::from_millis(10)).await;
+    }
+    assert_eq!(dead_updates, 1, "expected exactly one Dead announcement");
+}
+
+/// Dismissing a dead session releases it — without asking tmux to kill
+/// something tmux already lost.
+#[tokio::test]
+async fn killing_a_dead_session_dismisses_it_without_touching_tmux() {
+    let fx = Fx::new();
+    let s = fx.manager.create(fx.request("bash")).await.expect("create");
+    fx.fake.remove_live(s.id);
+    fx.manager.start_liveness_watcher(Duration::from_millis(25));
+    wait_for_status(&fx.manager, s.id, SessionStatus::Dead).await;
+
+    fx.manager.kill(s.id, false).await.expect("dismiss");
+
+    assert!(fx.manager.snapshot().await.is_empty());
+    assert!(
+        !fx.fake
+            .calls()
+            .iter()
+            .any(|c| matches!(c, Call::KillSession(k) if *k == s.id)),
+        "kill-session was called on a session tmux had already lost: {:?}",
+        fx.fake.calls()
+    );
+}
+
+/// A dead session has no pane, so input is dropped rather than surfacing as a
+/// tmux failure the client would have to interpret.
+#[tokio::test]
+async fn a_dead_session_is_read_only() {
+    let fx = Fx::new();
+    let s = fx.manager.create(fx.request("bash")).await.expect("create");
+    fx.fake.remove_live(s.id);
+    fx.manager.start_liveness_watcher(Duration::from_millis(25));
+    wait_for_status(&fx.manager, s.id, SessionStatus::Dead).await;
+
+    fx.manager
+        .send_keys(s.id, b"ls\n")
+        .await
+        .expect("send_keys");
+    fx.manager.resize(s.id, 80, 24).await.expect("resize");
+
+    assert!(
+        !fx.fake
+            .calls()
+            .iter()
+            .any(|c| matches!(c, Call::SendKeys { .. } | Call::ResizeWindow { .. })),
+        "input reached tmux for a dead session: {:?}",
+        fx.fake.calls()
+    );
+}
+
+/// `CreateSessionRequest.env` was accepted, stored, echoed back to clients, and
+/// then dropped: `new_session_piped` had no env parameter at all.
+#[tokio::test]
+async fn requested_env_reaches_tmux() {
+    let fx = Fx::new();
+    let mut req = fx.request("bash");
+    req.env.insert("FOO".into(), "bar".into());
+    req.env.insert("EMPTY".into(), String::new());
+
+    fx.manager.create(req).await.expect("create");
+
+    let spawned = match fx.fake.calls().first() {
+        Some(Call::NewSessionPiped { env, .. }) => env.clone(),
+        other => panic!("expected a spawn call, got {other:?}"),
+    };
+    let id = spawned
+        .get("MAESTRO_SESSION_ID")
+        .expect("spawn must export MAESTRO_SESSION_ID (#103)")
+        .clone();
+    // The daemon-owned variable rides alongside whatever was requested.
+    let want: BTreeMap<String, String> = [
+        ("EMPTY".to_string(), String::new()),
+        ("FOO".to_string(), "bar".to_string()),
+        ("MAESTRO_SESSION_ID".to_string(), id),
+    ]
+    .into_iter()
+    .collect();
+    assert_eq!(&spawned, &want);
+}
+
+#[tokio::test]
+async fn an_env_key_tmux_would_misparse_is_rejected() {
+    let fx = Fx::new();
+    let mut req = fx.request("bash");
+    req.env.insert("A=B".into(), "x".into());
+
+    let err = fx.manager.create(req).await.expect_err("should reject");
+    assert_eq!(err.to_error_info().code, "invalid_env");
+    assert!(
+        fx.fake.calls().is_empty(),
+        "nothing should have been spawned: {:?}",
+        fx.fake.calls()
+    );
+}
+
+/// If `list_sessions` fails the pass has no idea what is alive. Reaping on that
+/// basis would kill the whole catalog.
+#[tokio::test]
+async fn liveness_reaps_nothing_when_tmux_cannot_be_listed() {
+    let fx = Fx::new();
+    let alive = fx.manager.create(fx.request("bash")).await.expect("create");
+
+    fx.fake.fail(Op::ListSessions, "connection refused");
+    fx.manager.start_liveness_watcher(Duration::from_millis(25));
+
+    // Give the watcher several passes to do the wrong thing.
+    tokio::time::sleep(Duration::from_millis(200)).await;
+
+    let snap = fx.manager.snapshot().await;
+    assert_eq!(
+        snap.len(),
+        1,
+        "a failed list must not be read as 'everything died'"
+    );
+    assert_eq!(snap[0].id, alive.id);
+}
+
+#[tokio::test]
+async fn activity_pass_emits_updated_only_when_something_changed() {
+    let fx = Fx::new();
+    let session = fx.manager.create(fx.request("zsh")).await.expect("create");
+    let mut events = fx.manager.events();
+
+    fx.fake.set_pane_info(
+        session.id,
+        PaneInfo {
+            // A pid nothing can be reading from, so `awaiting_input` is a
+            // deterministic false rather than a probe of this machine.
+            pane_pid: i32::MAX,
+            command: "claude".into(),
+            tty: "/dev/null".into(),
+            current_path: "/srv/work".into(),
+        },
+    );
+    fx.manager.start_liveness_watcher(Duration::from_millis(25));
+
+    let updated = wait_for_updated(&mut events).await;
+    assert_eq!(updated.foreground.as_deref(), Some("claude"));
+    assert_eq!(
+        updated.current_cwd.as_deref(),
+        Some(std::path::Path::new("/srv/work"))
+    );
+    // Still inside `activity::ACTIVE_WINDOW` (3s) since the spawn, so the
+    // change here is `foreground`, not the activity state.
+    assert_eq!(updated.activity, ActivityState::Active);
+    // A foreground/cwd-only change is not a state transition (#104): the
+    // sidebar's duration must keep counting from the original stamp.
+    assert_eq!(updated.activity_since, session.activity_since);
+
+    // Drain anything already queued, then confirm a steady pane stays quiet.
+    // Stays well inside the 3s window, so no Active -> Idle transition either.
+    while events.try_recv().is_ok() {}
+    tokio::time::sleep(Duration::from_millis(200)).await;
+    assert!(
+        matches!(events.try_recv(), Err(TryRecvError::Empty)),
+        "an unchanged pane must not re-emit SessionUpdated every tick"
+    );
+}
+
+/// The sidebar's duration (#104) is time in the *current* state, so
+/// `activity_since` is stamped exactly when the decided state differs from
+/// the stored one — once per transition. Stamping it every tick would make
+/// the duration permanently read zero.
+#[tokio::test]
+async fn activity_transition_stamps_activity_since_once_per_transition() {
+    let fx = Fx::new();
+    let session = fx
+        .manager
+        .create(fx.request("sleep 300"))
+        .await
+        .expect("create");
+    fx.fake.set_pane_info(
+        session.id,
+        PaneInfo {
+            // Nothing reads from this pid: `awaiting_input` is deterministically
+            // false, so past `ACTIVE_WINDOW` the session decides as Idle.
+            pane_pid: i32::MAX,
+            command: "sleep".into(),
+            tty: "/dev/null".into(),
+            current_path: String::new(),
+        },
+    );
+    let mut events = fx.manager.events();
+    fx.manager.start_liveness_watcher(Duration::from_millis(25));
+
+    let idle = wait_for_activity(&fx.manager, session.id, ActivityState::Idle).await;
+    assert!(
+        idle.activity_since >= session.activity_since + chrono::Duration::seconds(2),
+        "the Active -> Idle transition must stamp a fresh activity_since \
+         (spawn stamp {:?}, transition stamp {:?})",
+        session.activity_since,
+        idle.activity_since
+    );
+
+    // Steady Idle across many more ticks must not re-stamp — no further
+    // SessionUpdated at all, or the sidebar clock would keep resetting.
+    while events.try_recv().is_ok() {}
+    tokio::time::sleep(Duration::from_millis(300)).await;
+    assert!(
+        matches!(events.try_recv(), Err(TryRecvError::Empty)),
+        "a steady state must not re-emit (and re-stamp) on every tick"
+    );
+}
+
+async fn wait_for_activity(
+    manager: &SessionManager,
+    id: uuid::Uuid,
+    want: ActivityState,
+) -> maestro_protocol::Session {
+    let deadline = tokio::time::Instant::now() + Duration::from_secs(6);
+    loop {
+        if tokio::time::Instant::now() >= deadline {
+            panic!("timed out waiting for {id} to become {want:?}");
+        }
+        if let Some(s) = manager.snapshot().await.into_iter().find(|s| s.id == id) {
+            if s.activity == want {
+                return s;
+            }
+        }
+        tokio::time::sleep(Duration::from_millis(20)).await;
+    }
+}
+
+async fn wait_for_updated(
+    events: &mut tokio::sync::broadcast::Receiver<CatalogEvent>,
+) -> maestro_protocol::Session {
+    let deadline = tokio::time::Instant::now() + Duration::from_secs(3);
+    while tokio::time::Instant::now() < deadline {
+        match events.try_recv() {
+            Ok(CatalogEvent::SessionUpdated { session }) => return session,
+            Ok(_) => continue,
+            Err(_) => tokio::time::sleep(Duration::from_millis(10)).await,
+        }
+    }
+    panic!("timed out waiting for SessionUpdated");
+}
+
+/// The kill handler used to check `has()` first, which opened a window for the
+/// liveness watcher to reap the session in between — turning a 404 into a 502.
+/// `kill` reports the miss itself now.
+#[tokio::test]
+async fn killing_an_unknown_session_is_reported_as_not_found() {
+    let fx = Fx::new();
+    let err = fx
+        .manager
+        .kill(uuid::Uuid::new_v4(), false)
+        .await
+        .expect_err("should fail");
+    assert_eq!(err.to_error_info().code, "not_found");
+}
+
+/// A construction-order mistake must be loud: a silently-ignored history leaves
+/// the recent-dirs picker permanently empty.
+#[test]
+#[should_panic(expected = "before the SessionManager is cloned")]
+fn attaching_spawn_history_after_cloning_panics() {
+    let tmp = TempDir::new().expect("tempdir");
+    let fake = Arc::new(FakePanes::new());
+    let manager = SessionManager::new(
+        fake,
+        SidecarStore::new(tmp.path().join("sidecars")),
+        WorktreeManager::new(Some(tmp.path().join("worktrees"))),
+        tmp.path().join("fifos"),
+    );
+    let _clone = manager.clone();
+    let _ = manager.with_spawn_history(maestro_daemon::spawn_history::SpawnHistory::new(
+        tmp.path().join("history.jsonl"),
+        7,
+    ));
+}
+
+/// Every tmux-spawned session learns who it is (#103): its own UUID under
+/// `MAESTRO_SESSION_ID`, so the reporting hook in #106 can name the session
+/// it is running inside.
+#[tokio::test]
+async fn spawn_exports_maestro_session_id() {
+    let fx = Fx::new();
+    let s = fx.manager.create(fx.request("bash")).await.expect("create");
+
+    let env = fx.spawned_env();
+    assert_eq!(
+        env.get("MAESTRO_SESSION_ID").map(String::as_str),
+        Some(&s.id.to_string()[..]),
+        "MAESTRO_SESSION_ID must be the session's UUID, got {env:?}"
+    );
+}
+
+/// The hook also needs to know where to report to: `MAESTRO_URL` carries the
+/// daemon's base URL derived from `[daemon].bind_addr` (#103).
+#[tokio::test]
+async fn spawn_exports_maestro_url_when_the_daemon_is_wired() {
+    let fx = Fx::with_daemon_url("http://127.0.0.1:7070");
+    fx.manager.create(fx.request("bash")).await.expect("create");
+
+    let env = fx.spawned_env();
+    assert_eq!(
+        env.get("MAESTRO_URL").map(String::as_str),
+        Some("http://127.0.0.1:7070"),
+        "MAESTRO_URL must be the daemon's base URL, got {env:?}"
+    );
+}
+
+/// Without a wired URL (tests, or a caller that never set one) only the
+/// session id is injected — an empty or bogus `MAESTRO_URL` would send the
+/// #106 hook's reports nowhere useful.
+#[tokio::test]
+async fn spawn_omits_maestro_url_when_not_wired() {
+    let fx = Fx::new();
+    fx.manager.create(fx.request("bash")).await.expect("create");
+
+    let env = fx.spawned_env();
+    assert!(
+        !env.contains_key("MAESTRO_URL"),
+        "MAESTRO_URL must be absent when no daemon URL is known, got {env:?}"
+    );
+}
+
+/// The daemon-owned variables win over anything the spawner sent: a client
+/// cannot spoof another session's identity.
+#[tokio::test]
+async fn spawn_overrides_client_supplied_maestro_variables() {
+    let fx = Fx::with_daemon_url("http://127.0.0.1:7070");
+    let mut req = fx.request("bash");
+    req.env.insert(
+        "MAESTRO_SESSION_ID".into(),
+        "00000000-0000-0000-0000-000000000000".into(),
+    );
+    req.env.insert("MAESTRO_URL".into(), "http://evil:1".into());
+    let s = fx.manager.create(req).await.expect("create");
+
+    let env = fx.spawned_env();
+    assert_eq!(env.get("MAESTRO_SESSION_ID"), Some(&s.id.to_string()));
+    assert_eq!(
+        env.get("MAESTRO_URL"),
+        Some(&"http://127.0.0.1:7070".to_string())
+    );
+}

crates/maestro-daemon/tests/session_manager.rs

@@ -4,11 +4,14 @@ mod common;
 
 use std::collections::HashMap;
 use std::path::PathBuf;
+use std::process::Command;
+use std::sync::Arc;
 use std::time::Duration;
 
-use common::{wait_for_async, DaemonFixture};
-use maestro_daemon::SessionEvent;
+use common::{init_bare_repo, init_repo, push_all_to_origin, wait_for_async, DaemonFixture};
+use maestro_daemon::SessionError;
 use maestro_protocol::CreateSessionRequest;
+use maestro_protocol::{CatalogEvent, SessionStatus, WorktreeSpec};
 use tempfile::TempDir;
 
 #[tokio::test]
@@ -41,7 +44,7 @@ async fn create_then_kill_round_trip() {
     // FIFO should also exist
     assert!(fx.fifo_dir().join(format!("{}.fifo", session.id)).exists());
 
-    fx.manager.kill(session.id).await.expect("kill");
+    fx.manager.kill(session.id, false).await.expect("kill");
     assert!(!fx.manager.has(session.id).await);
     assert!(!fx
         .sidecar_dir()
@@ -76,7 +79,7 @@ async fn create_appends_to_spawn_history() {
     assert_eq!(recents[0].cwd, cwd.path());
     assert_eq!(recents[0].last_command, "sleep 30");
 
-    fx.manager.kill(session.id).await.expect("kill");
+    fx.manager.kill(session.id, false).await.expect("kill");
     // History is durable — it survives the kill that deletes the sidecar.
     assert_eq!(fx.manager.recent_dirs().len(), 1);
 }
@@ -101,63 +104,6 @@ async fn create_without_history_logs_nothing() {
     assert!(!fx.spawn_history_path().exists());
 }
 
-/// NAP-260: when the sidecar write fails *after* tmux has spawned the session,
-/// `create` must roll back — no ghost tmux session, no in-memory record left
-/// behind. We force the failure by making the sidecar directory read-only (the
-/// FIFO + tmux steps use other dirs and still succeed).
-#[tokio::test]
-async fn create_rolls_back_tmux_session_when_sidecar_write_fails() {
-    use std::os::unix::fs::PermissionsExt;
-
-    let fx = DaemonFixture::new();
-    let cwd = TempDir::new().unwrap();
-
-    let sidecar_dir = fx.sidecar_dir();
-    std::fs::create_dir_all(&sidecar_dir).unwrap();
-    std::fs::set_permissions(&sidecar_dir, std::fs::Permissions::from_mode(0o500)).unwrap();
-
-    // The failure is injected by making the sidecar dir read-only — but root
-    // bypasses directory permission bits, so the write would succeed and the
-    // rollback path never trigger. CI runs as root; detect that with a write
-    // probe and skip rather than report a spurious failure (the rollback is
-    // still covered in any non-root environment).
-    let probe = sidecar_dir.join(".perm_probe");
-    if std::fs::write(&probe, b"x").is_ok() {
-        let _ = std::fs::remove_file(&probe);
-        std::fs::set_permissions(&sidecar_dir, std::fs::Permissions::from_mode(0o700)).unwrap();
-        eprintln!("skipping: sidecar dir writable despite 0o500 (running as root?)");
-        return;
-    }
-
-    let res = fx
-        .manager
-        .create(CreateSessionRequest {
-            cwd: cwd.path().to_path_buf(),
-            command: "sleep 30".into(),
-            env: HashMap::new(),
-            metadata: HashMap::new(),
-            worktree: None,
-        })
-        .await;
-
-    // Restore perms so the TempDir can be cleaned up regardless of assertions.
-    std::fs::set_permissions(&sidecar_dir, std::fs::Permissions::from_mode(0o700)).unwrap();
-
-    assert!(
-        matches!(res, Err(maestro_daemon::SessionError::Sidecar(_))),
-        "expected the sidecar write to fail, got {res:?}"
-    );
-
-    // The session tmux spawned must have been killed — no ghost left running.
-    let live = fx.tmux.tmux.list_sessions().expect("list tmux sessions");
-    assert!(
-        live.is_empty(),
-        "create left a ghost tmux session behind: {live:?}"
-    );
-    // And nothing in the in-memory catalog.
-    assert!(fx.manager.snapshot().await.is_empty());
-}
-
 #[tokio::test]
 async fn recover_adopts_existing_tmux_sessions() {
     let fx = DaemonFixture::new();
@@ -179,10 +125,9 @@ async fn recover_adopts_existing_tmux_sessions() {
 
     // build a parallel manager pointing at the same dirs + same tmux server
     let sidecar = maestro_daemon::sidecar::SidecarStore::new(fx.sidecar_dir());
-    let worktree_mgr =
-        maestro_daemon::worktree::WorktreeManager::new(fx.worktree_root.path().to_path_buf());
+    let worktree_mgr = maestro_daemon::worktree::WorktreeManager::new(None);
     let revived = maestro_daemon::SessionManager::new(
-        fx.tmux.tmux.clone(),
+        Arc::new(fx.tmux.tmux.clone()),
         sidecar,
         worktree_mgr,
         fx.fifo_dir(),
@@ -240,7 +185,118 @@ async fn create_captures_initial_output_in_replay_buffer() {
         "first-line marker never reached the replay buffer — pipe-pane raced past the child's initial output",
     );
 
-    fx.manager.kill(s.id).await.unwrap();
+    fx.manager.kill(s.id, false).await.unwrap();
+}
+
+/// A fresh attach must land on the pane's *current* screen. Replaying the raw
+/// byte tail instead reproduced a browser refresh painting garbage over an
+/// agent TUI: the tail starts mid-stream, so the clears, modes and cursor
+/// moves that gave those bytes meaning are long gone.
+#[tokio::test]
+async fn attach_replay_is_the_current_screen_not_the_byte_tail() {
+    let fx = DaemonFixture::new();
+    let cwd = TempDir::new().unwrap();
+
+    let s = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: cwd.path().to_path_buf(),
+            // Print a line, then switch to the alternate screen the way a
+            // full-screen program does on startup. Only the second marker is
+            // on the pane; the first belongs to the screen behind it.
+            command: "sh -c 'printf STALE_MARKER_LINE\\\\n; sleep 0.5; printf \"\\\\033[?1049h\\\\033[2J\\\\033[HLIVE_MARKER\"; exec sleep 30'"
+                .into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+        })
+        .await
+        .expect("create");
+
+    let want = b"LIVE_MARKER";
+    let deadline = std::time::Instant::now() + Duration::from_secs(5);
+    let mut replay = Vec::new();
+    while std::time::Instant::now() < deadline {
+        let (bytes, _rx) = fx
+            .manager
+            .subscribe_pty_with_replay(s.id)
+            .await
+            .expect("subscribe");
+        replay = bytes;
+        if replay.windows(want.len()).any(|w| w == want) {
+            break;
+        }
+        tokio::time::sleep(Duration::from_millis(50)).await;
+    }
+
+    let text = String::from_utf8_lossy(&replay).into_owned();
+    assert!(
+        replay.starts_with(b"\x1b[?1049h\x1b[H\x1b[2J"),
+        "replay did not start with an alternate-screen snapshot: {text:?}"
+    );
+    assert!(
+        text.contains("LIVE_MARKER"),
+        "replay lost the live screen: {text:?}"
+    );
+    assert!(
+        !text.contains("STALE_MARKER_LINE"),
+        "replay carried bytes from behind the alternate screen: {text:?}"
+    );
+
+    fx.manager.kill(s.id, false).await.unwrap();
+}
+
+/// A full-screen app turns mouse reporting on once, at startup. A client that
+/// attaches later never sees those sequences, so it reads the pane as a plain
+/// alternate screen and its wheel and touch gestures have nowhere to go. The
+/// snapshot must carry the pane's mouse modes with it.
+#[tokio::test]
+async fn attach_replay_carries_the_panes_mouse_modes() {
+    let fx = DaemonFixture::new();
+    let cwd = TempDir::new().unwrap();
+
+    let s = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: cwd.path().to_path_buf(),
+            // Alternate screen, then button-event tracking (?1002) with SGR
+            // coordinates (?1006) — what tmux and agent TUIs actually request.
+            command: "sh -c 'printf \"\\\\033[?1049h\\\\033[?1002h\\\\033[?1006h\\\\033[2J\\\\033[HMOUSE_MARKER\"; exec sleep 30'"
+                .into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+        })
+        .await
+        .expect("create");
+
+    let want = b"MOUSE_MARKER";
+    let deadline = std::time::Instant::now() + Duration::from_secs(5);
+    let mut replay = Vec::new();
+    while std::time::Instant::now() < deadline {
+        let (bytes, _rx) = fx
+            .manager
+            .subscribe_pty_with_replay(s.id)
+            .await
+            .expect("subscribe");
+        replay = bytes;
+        if replay.windows(want.len()).any(|w| w == want) {
+            break;
+        }
+        tokio::time::sleep(Duration::from_millis(50)).await;
+    }
+
+    let text = String::from_utf8_lossy(&replay).into_owned();
+    assert!(
+        text.contains("MOUSE_MARKER"),
+        "replay never reached the live screen: {text:?}"
+    );
+    assert!(
+        replay.starts_with(b"\x1b[?1049h\x1b[?1002h\x1b[?1006h\x1b[H\x1b[2J"),
+        "replay dropped the pane's mouse modes: {text:?}"
+    );
+
+    fx.manager.kill(s.id, false).await.unwrap();
 }
 
 /// Regression for NAP-228: after `recover`, PTY output must reach new
@@ -270,7 +326,6 @@ async fn recover_re_pipes_pane_so_output_reaches_subscribers() {
     let sidecar_dir = fx.sidecar_dir();
     let fifo_dir = fx.fifo_dir();
     let tmux = fx.tmux.tmux.clone();
-    let worktree_root = fx.worktree_root.path().to_path_buf();
 
     // Drop the original manager. Its PtyBridge closes the FIFO's only
     // reader, so tmux's `cat >> fifo` writer hits SIGPIPE and exits — but
@@ -279,8 +334,9 @@ async fn recover_re_pipes_pane_so_output_reaches_subscribers() {
     drop(fx.manager);
 
     let sidecar = maestro_daemon::sidecar::SidecarStore::new(sidecar_dir);
-    let worktree_mgr = maestro_daemon::worktree::WorktreeManager::new(worktree_root);
-    let revived = maestro_daemon::SessionManager::new(tmux, sidecar, worktree_mgr, fifo_dir);
+    let worktree_mgr = maestro_daemon::worktree::WorktreeManager::new(None);
+    let revived =
+        maestro_daemon::SessionManager::new(Arc::new(tmux), sidecar, worktree_mgr, fifo_dir);
     assert_eq!(revived.recover().await.expect("recover"), 1);
 
     let mut rx = revived.subscribe_pty(s.id).await.expect("subscribe");
@@ -306,7 +362,7 @@ async fn recover_re_pipes_pane_so_output_reaches_subscribers() {
         String::from_utf8_lossy(&buf),
     );
 
-    revived.kill(s.id).await.unwrap();
+    revived.kill(s.id, false).await.unwrap();
 }
 
 #[tokio::test]
@@ -355,12 +411,12 @@ async fn pty_broadcast_delivers_bytes_to_subscribers() {
     assert!(buf_a.windows(want.len()).any(|w| w == want), "A missed");
     assert!(buf_b.windows(want.len()).any(|w| w == want), "B missed");
 
-    fx.manager.kill(s.id).await.unwrap();
+    fx.manager.kill(s.id, false).await.unwrap();
     let _ = (cwd, PathBuf::from("/"));
 }
 
 #[tokio::test]
-async fn liveness_watcher_reaps_dead_sessions_and_emits_removed() {
+async fn liveness_watcher_marks_dead_sessions_and_keeps_them_until_dismissed() {
     let fx = DaemonFixture::new();
     let cwd = TempDir::new().unwrap();
 
@@ -385,29 +441,530 @@ async fn liveness_watcher_reaps_dead_sessions_and_emits_removed() {
     // daemon never finds out through its normal channels.
     fx.tmux.tmux.kill_session(s.id).expect("kill tmux directly");
 
-    // Within a few watcher ticks the daemon should drop the session.
     wait_for_async(Duration::from_secs(3), || async {
-        !fx.manager.has(s.id).await
+        fx.manager.status(s.id).await == Some(SessionStatus::Dead)
     })
     .await;
 
-    // Sidecar + FIFO should be cleaned up too.
-    assert!(!fx.sidecar_dir().join(format!("{}.json", s.id)).exists());
-    assert!(!fx.fifo_dir().join(format!("{}.fifo", s.id)).exists());
+    // Marked, not removed — the operator still sees it exited, and its
+    // artifacts stay so the output can be replayed.
+    assert!(fx.manager.has(s.id).await);
+    assert!(fx.sidecar_dir().join(format!("{}.json", s.id)).exists());
 
-    // And we should have seen a Removed event for this id.
-    let mut saw_removed = false;
+    let mut saw_dead = false;
     let deadline = std::time::Instant::now() + Duration::from_secs(1);
-    while std::time::Instant::now() < deadline && !saw_removed {
+    while std::time::Instant::now() < deadline && !saw_dead {
         match tokio::time::timeout(Duration::from_millis(50), events.recv()).await {
-            Ok(Ok(SessionEvent::Removed(id))) if id == s.id => saw_removed = true,
+            Ok(Ok(CatalogEvent::SessionUpdated { session }))
+                if session.id == s.id && session.status == SessionStatus::Dead =>
+            {
+                saw_dead = true
+            }
             Ok(Ok(_)) => continue,
             _ => break,
         }
     }
     assert!(
-        saw_removed,
-        "expected SessionEvent::Removed for dead session"
+        saw_dead,
+        "expected a SessionUpdated marking the session dead"
+    );
+
+    // Dismissing it is what finally releases the artifacts.
+    fx.manager.kill(s.id, false).await.expect("dismiss");
+    assert!(!fx.manager.has(s.id).await);
+    assert!(!fx.sidecar_dir().join(format!("{}.json", s.id)).exists());
+    assert!(!fx.fifo_dir().join(format!("{}.fifo", s.id)).exists());
+}
+
+/// #83: the watcher refreshes `Session.blocked_work` on its own cadence —
+/// first "nothing blocks" for a pristine tree, then the breakdown once the
+/// tree picks up unsaved work, so clients can warn before the kill attempt.
+#[tokio::test]
+async fn watcher_refreshes_the_blocked_work_indicator() {
+    let fx = DaemonFixture::new();
+    let repo = TempDir::new().unwrap();
+    init_repo(repo.path());
+    let wt_path = repo.path().join("worktrees").join("feat").join("indicator");
+
+    fx.manager
+        .create(CreateSessionRequest {
+            cwd: repo.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: repo.path().to_path_buf(),
+                branch: "feat/indicator".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .expect("create");
+
+    // Pushed and clean: nothing in the way, and the indicator must say so.
+    let origin = TempDir::new().unwrap();
+    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),
+    );
+
+    wait_for_async(Duration::from_secs(5), || async {
+        fx.manager.snapshot().await[0].blocked_work == Some(maestro_protocol::InTheWay::default())
+    })
+    .await;
+
+    // Unsaved work appears; the next pass must surface it.
+    std::fs::write(wt_path.join("README"), b"unsaved edits\n").unwrap();
+    std::fs::write(wt_path.join("notes.txt"), b"untracked\n").unwrap();
+    wait_for_async(Duration::from_secs(5), || async {
+        matches!(
+            &fx.manager.snapshot().await[0].blocked_work,
+            Some(b) if b.uncommitted_files >= 1 && b.untracked_files >= 1
+        )
+    })
+    .await;
+
+    // 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;
+    // 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
+/// that says "don't clean up" loses its worktree — the branch was pushed, so
+/// nothing in the tree is unique and removal goes ahead.
+#[tokio::test]
+async fn kill_removes_worktree_even_when_spec_says_keep() {
+    let fx = DaemonFixture::new();
+    let repo = TempDir::new().unwrap();
+    init_repo(repo.path());
+    let wt_path = repo.path().join("worktrees").join("feat").join("keep");
+
+    let s = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: repo.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: repo.path().to_path_buf(),
+                branch: "feat/keep".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .expect("create");
+    assert!(wt_path.exists());
+
+    // Push the branch so its commits are reachable from a remote-tracking ref.
+    let origin = TempDir::new().unwrap();
+    init_bare_repo(origin.path());
+    push_all_to_origin(repo.path(), origin.path());
+
+    fx.manager.kill(s.id, false).await.expect("kill");
+    assert!(!wt_path.exists(), "worktree must be removed on kill");
+}
+
+/// The kill guard (#79): a worktree holding uncommitted changes refuses the
+/// kill outright. Nothing happens — the session keeps running as the
+/// operator's handle on their unfinished work, and the tree is untouched.
+/// The refusal names what blocked it and how much of it there is.
+#[tokio::test]
+async fn killing_refuses_a_worktree_with_unsaved_work_and_keeps_the_session() {
+    let fx = DaemonFixture::new();
+    let repo = TempDir::new().unwrap();
+    init_repo(repo.path());
+    let wt_path = repo.path().join("worktrees").join("feat").join("guarded");
+
+    let s = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: repo.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: repo.path().to_path_buf(),
+                branch: "feat/guarded".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .expect("create");
+    std::fs::write(wt_path.join("README"), b"unsaved edits\n").unwrap();
+    std::fs::write(wt_path.join("notes.txt"), b"untracked\n").unwrap();
+
+    let err = fx
+        .manager
+        .kill(s.id, false)
+        .await
+        .expect_err("kill must refuse");
+    let SessionError::KillGuarded(breakdown) = err else {
+        panic!("expected KillGuarded, got {err:?}");
+    };
+    assert_eq!(breakdown.uncommitted_files, 1);
+    assert_eq!(breakdown.untracked_files, 1);
+    assert!(
+        breakdown.unpushed_commits >= 1,
+        "a fresh branch has no remote-tracking ref"
+    );
+    let message = breakdown.to_string();
+    assert!(message.contains("1 uncommitted file"), "{message}");
+    assert!(message.contains("1 untracked file"), "{message}");
+
+    // Nothing happened: the session survives and so does the tree.
+    assert!(fx.manager.has(s.id).await, "the session must keep running");
+    assert!(wt_path.exists(), "the worktree must be untouched");
+
+    // A second kill after the work is saved goes through.
+    run_git_in(&wt_path, &["add", "."]);
+    run_git_in(&wt_path, &["commit", "-q", "-m", "saved"]);
+    let origin = TempDir::new().unwrap();
+    init_bare_repo(origin.path());
+    push_all_to_origin(repo.path(), origin.path());
+    fx.manager
+        .kill(s.id, false)
+        .await
+        .expect("kill after saving");
+    assert!(!fx.manager.has(s.id).await);
+}
+
+/// Unpushed commits alone block the kill (#79): a feature branch almost
+/// always has them, which is why `--force` (which retains) is the ordinary
+/// way to end such a session.
+#[tokio::test]
+async fn killing_refuses_until_the_branch_is_pushed() {
+    let fx = DaemonFixture::new();
+    let repo = TempDir::new().unwrap();
+    init_repo(repo.path());
+    let wt_path = repo.path().join("worktrees").join("feat").join("pushed");
+
+    let s = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: repo.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: repo.path().to_path_buf(),
+                branch: "feat/pushed".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .expect("create");
+
+    let err = fx
+        .manager
+        .kill(s.id, false)
+        .await
+        .expect_err("unpushed blocks");
+    let SessionError::KillGuarded(breakdown) = err else {
+        panic!("expected KillGuarded, got {err:?}");
+    };
+    assert_eq!(breakdown.uncommitted_files, 0);
+    assert_eq!(breakdown.untracked_files, 0);
+    assert!(breakdown.unpushed_commits >= 1);
+
+    let origin = TempDir::new().unwrap();
+    init_bare_repo(origin.path());
+    push_all_to_origin(repo.path(), origin.path());
+
+    fx.manager
+        .kill(s.id, false)
+        .await
+        .expect("pushed branch kills");
+    assert!(!wt_path.exists());
+    assert!(!fx.manager.has(s.id).await);
+}
+
+/// `--force` overrides the refusal and nothing else (#81): the session ends,
+/// but the guarded worktree is left on disk — never removed.
+#[tokio::test]
+async fn force_killing_a_guarded_worktree_leaves_it_on_disk() {
+    let fx = DaemonFixture::new();
+    let repo = TempDir::new().unwrap();
+    init_repo(repo.path());
+    let wt_path = repo.path().join("worktrees").join("feat").join("forced");
+
+    let s = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: repo.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: repo.path().to_path_buf(),
+                branch: "feat/forced".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .expect("create");
+    std::fs::write(wt_path.join("README"), b"unsaved edits\n").unwrap();
+
+    // Without force the same kill is refused (#79).
+    assert!(fx.manager.kill(s.id, false).await.is_err());
+
+    fx.manager
+        .kill(s.id, true)
+        .await
+        .expect("force overrides the refusal");
+
+    // The tree would have blocked, so force must NOT have removed it...
+    assert!(
+        wt_path.exists(),
+        "a forced kill never removes a tree that would have blocked"
+    );
+    // ...but the session itself still ends.
+    assert!(!fx.manager.has(s.id).await);
+    assert!(!fx.sidecar_dir().join(format!("{}.json", s.id)).exists());
+}
+
+/// Force overrides the *refusal*, not ordinary cleanup (#81): a tree whose
+/// guard is clear never needed the override, so a forced kill removes it as
+/// usual.
+#[tokio::test]
+async fn force_on_a_clear_worktree_removes_it_as_usual() {
+    let fx = DaemonFixture::new();
+    let repo = TempDir::new().unwrap();
+    init_repo(repo.path());
+    let wt_path = repo.path().join("worktrees").join("feat").join("clear");
+
+    let s = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: repo.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: repo.path().to_path_buf(),
+                branch: "feat/clear".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .expect("create");
+
+    let origin = TempDir::new().unwrap();
+    init_bare_repo(origin.path());
+    push_all_to_origin(repo.path(), origin.path());
+
+    fx.manager.kill(s.id, true).await.expect("kill");
+    assert!(!wt_path.exists(), "a clear tree needs no override");
+}
+
+/// Ignored files NEVER block (#79): build output like `target/` exists in
+/// every Rust checkout, and an ignored-only worktree stays killable.
+#[tokio::test]
+async fn killing_an_ignored_only_worktree_succeeds() {
+    let fx = DaemonFixture::new();
+    let repo = TempDir::new().unwrap();
+    init_repo(repo.path());
+    // .gitignore must be committed before the worktree branches off, or it
+    // would itself read as an untracked file.
+    std::fs::write(repo.path().join(".gitignore"), b"/target\n").unwrap();
+    run_git_in(repo.path(), &["add", ".gitignore"]);
+    run_git_in(repo.path(), &["commit", "-q", "-m", "ignore target"]);
+    let origin = TempDir::new().unwrap();
+    init_bare_repo(origin.path());
+
+    let wt_path = repo.path().join("worktrees").join("feat").join("rusty");
+    let s = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: repo.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: repo.path().to_path_buf(),
+                branch: "feat/rusty".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .expect("create");
+    std::fs::create_dir_all(wt_path.join("target")).unwrap();
+    std::fs::write(wt_path.join("target").join("app.o"), b"binary\n").unwrap();
+
+    // Branch pushed; the only dirt is ignored output.
+    push_all_to_origin(repo.path(), origin.path());
+
+    fx.manager
+        .kill(s.id, false)
+        .await
+        .expect("ignored files never block");
+    assert!(!wt_path.exists());
+    assert!(!fx.manager.has(s.id).await);
+}
+
+/// Natural exit (#82): a session that ends on its own never reaches the kill
+/// path, so the watcher applies the kill's rule itself. A worktree holding
+/// unsaved work is LEFT ON DISK and stays attached to the dead record; the
+/// session stays in the catalog marked dead until dismissed, and dismissing
+/// it goes through `--force`, which leaves the tree alone too.
+#[tokio::test]
+async fn natural_exit_of_a_guarded_worktree_leaves_it_on_disk() {
+    let fx = DaemonFixture::new();
+    let repo = TempDir::new().unwrap();
+    init_repo(repo.path());
+    let wt_path = repo.path().join("worktrees").join("feat").join("exited");
+
+    let s = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: repo.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: repo.path().to_path_buf(),
+                branch: "feat/exited".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .expect("create");
+    std::fs::write(wt_path.join("README"), b"unsaved edits\n").unwrap();
+
+    // The command finishes / the operator types exit: tmux loses the session.
+    fx.tmux.tmux.kill_session(s.id).expect("kill tmux directly");
+    fx.manager.start_liveness_watcher(Duration::from_millis(50));
+    wait_for_async(Duration::from_secs(3), || async {
+        fx.manager.status(s.id).await == Some(SessionStatus::Dead)
+    })
+    .await;
+
+    // The settle step has been applied or refused either way — here refused,
+    // since the tree holds unsaved work. Only from this point is "the tree
+    // survived" a settled fact rather than a race (#115).
+    wait_for_async(Duration::from_secs(3), || async {
+        fx.manager.is_settled(s.id).await == Some(true)
+    })
+    .await;
+
+    // The tree would have blocked a kill, so the exit kept it.
+    assert!(
+        wt_path.exists(),
+        "a dirty worktree must be left alone on natural exit"
+    );
+    let snap = fx.manager.snapshot().await;
+    assert_eq!(snap.len(), 1);
+    assert!(
+        snap[0].worktree.is_some(),
+        "the tree stays attached to the dead record"
+    );
+
+    // Dismissing it needs --force, and force never removes what would block.
+    assert!(fx.manager.kill(s.id, false).await.is_err());
+    fx.manager.kill(s.id, true).await.expect("forced dismissal");
+    assert!(!fx.manager.has(s.id).await);
+    assert!(wt_path.exists(), "dismissal must not remove the work");
+}
+
+/// Natural exit (#82), pristine side of the same rule: nothing in the tree,
+/// nothing to keep — the worktree is removed.
+#[tokio::test]
+async fn natural_exit_of_a_pristine_worktree_removes_it() {
+    let fx = DaemonFixture::new();
+    let repo = TempDir::new().unwrap();
+    init_repo(repo.path());
+    let wt_path = repo.path().join("worktrees").join("feat").join("clean");
+
+    let s = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: repo.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: repo.path().to_path_buf(),
+                branch: "feat/clean".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .expect("create");
+
+    // Push everything so the branch has no unpushed commits: fully pristine.
+    let origin = TempDir::new().unwrap();
+    init_bare_repo(origin.path());
+    push_all_to_origin(repo.path(), origin.path());
+
+    fx.tmux.tmux.kill_session(s.id).expect("kill tmux directly");
+    fx.manager.start_liveness_watcher(Duration::from_millis(50));
+    wait_for_async(Duration::from_secs(3), || async {
+        fx.manager.status(s.id).await == Some(SessionStatus::Dead)
+    })
+    .await;
+
+    // (`Dead` is observable a moment before the settle step removes the tree.)
+    wait_for_async(Duration::from_secs(3), || async { !wt_path.exists() }).await;
+
+    assert!(
+        !wt_path.exists(),
+        "a pristine worktree leaves nothing behind"
+    );
+    assert!(
+        fx.manager.has(s.id).await,
+        "the session stays until dismissed"
+    );
+}
+
+fn run_git_in(dir: &std::path::Path, args: &[&str]) {
+    let out = Command::new("git")
+        .arg("-C")
+        .arg(dir)
+        .args(args)
+        .output()
+        .expect("git spawn");
+    assert!(
+        out.status.success(),
+        "git {args:?} failed: {}",
+        String::from_utf8_lossy(&out.stderr)
     );
 }
 
@@ -434,5 +991,103 @@ async fn liveness_watcher_leaves_running_sessions_alone() {
     tokio::time::sleep(Duration::from_millis(400)).await;
     assert!(fx.manager.has(s.id).await, "live session got reaped");
 
-    fx.manager.kill(s.id).await.unwrap();
+    fx.manager.kill(s.id, false).await.unwrap();
+}
+
+/// #99: clients group a session under `worktree.base_repo`, so that field has
+/// to name the repository even when the spawn request pointed at a linked
+/// worktree. Recording the request verbatim put the session in a folder of its
+/// own — `<repo>/worktrees/<branch>` — instead of under the repo.
+#[tokio::test]
+async fn worktree_base_repo_records_the_main_checkout_not_the_request() {
+    let fx = DaemonFixture::new();
+    let repo = TempDir::new().unwrap();
+    init_repo(repo.path());
+
+    // A linked worktree of that repo, then a spawn whose `base_repo` names it
+    // rather than the main checkout — what happens when the operator spawns
+    // from inside a worktree.
+    let first = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: repo.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: repo.path().to_path_buf(),
+                branch: "feat/one".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .expect("create first");
+    let inner_worktree = first.worktree.expect("first has a worktree").path;
+
+    let second = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: inner_worktree.clone(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: inner_worktree.clone(),
+                branch: "feat/two".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .expect("create second");
+
+    let wt = second.worktree.expect("second has a worktree");
+    assert_eq!(
+        wt.base_repo,
+        repo.path()
+            .canonicalize()
+            .unwrap_or_else(|_| repo.path().to_path_buf()),
+        "base_repo must be the repository, not the worktree the request named",
+    );
+    assert_ne!(wt.base_repo, inner_worktree, "the worktree is not the repo");
+}
+
+/// #103: every tmux-spawned session carries the daemon's identity variables in
+/// its environment — its UUID under `MAESTRO_SESSION_ID` and the daemon's base
+/// URL under `MAESTRO_URL` — so the in-session reporting hook (#106) can find
+/// both without any out-of-band channel.
+#[tokio::test]
+async fn spawned_sessions_export_maestro_session_id_and_url() {
+    let fx = DaemonFixture::new();
+    fx.manager
+        .set_daemon_url("http://127.0.0.1:7071".to_string());
+    let cwd = TempDir::new().unwrap();
+
+    let s = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: cwd.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+        })
+        .await
+        .expect("create");
+
+    let env = fx
+        .tmux
+        .tmux
+        .show_environment(s.id)
+        .expect("show-environment");
+    assert_eq!(
+        env.get("MAESTRO_SESSION_ID"),
+        Some(&s.id.to_string()),
+        "session env: {env:?}"
+    );
+    assert_eq!(
+        env.get("MAESTRO_URL"),
+        Some(&"http://127.0.0.1:7071".to_string())
+    );
+
+    fx.manager.kill(s.id, false).await.expect("kill");
 }

crates/maestro-daemon/tests/sidecar.rs

@@ -19,14 +19,18 @@ fn sample(id: Uuid) -> Session {
         command: "bash".into(),
         env: HashMap::from([("FOO".into(), "bar".into())]),
         metadata: HashMap::from([("name".into(), Value::String("maestro-impl".into()))]),
+        worktree: None,
         status: SessionStatus::Running,
         created_at: DateTime::parse_from_rfc3339("2026-05-24T12:00:00Z")
             .unwrap()
             .with_timezone(&Utc),
         foreground: None,
         activity: Default::default(),
+        activity_detail: None,
         last_activity_at: chrono::Utc::now(),
+        activity_since: chrono::Utc::now(),
         current_cwd: Some(PathBuf::from("/tmp/work/crates")),
+        blocked_work: None,
     }
 }
 

crates/maestro-daemon/tests/worktree.rs

@@ -6,8 +6,9 @@ mod common;
 use std::path::PathBuf;
 use std::process::Command;
 
-use common::init_repo;
+use common::{init_bare_repo, init_repo, push_all_to_origin};
 use maestro_daemon::worktree::WorktreeManager;
+use maestro_daemon::worktree_probe::in_the_way;
 use tempfile::TempDir;
 
 fn worktree_branches(repo: &PathBuf) -> Vec<String> {
@@ -31,9 +32,9 @@ fn add_creates_worktree_on_new_branch() {
     init_repo(&repo);
 
     let wt_root = TempDir::new().unwrap();
-    let mgr = WorktreeManager::new(wt_root.path());
+    let mgr = WorktreeManager::new(Some(wt_root.path().to_path_buf()));
 
-    let path = mgr.add(&repo, "feat/example").expect("add worktree");
+    let path = mgr.add_new(&repo, "feat/example").expect("add worktree");
     assert!(path.exists());
     assert!(path.join("README").exists());
     assert!(path.starts_with(wt_root.path()));
@@ -42,6 +43,82 @@ fn add_creates_worktree_on_new_branch() {
     assert!(branches.iter().any(|b| b == "feat/example"), "{branches:?}");
 }
 
+#[test]
+fn add_places_worktree_inside_the_base_repo_by_default() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    // No override: the worktree must land where the repository keeps its
+    // own worktrees (#56), not under some daemon state dir.
+    let mgr = WorktreeManager::new(None);
+
+    let path = mgr.add_new(&repo, "feat/example").expect("add worktree");
+    assert_eq!(path, repo.join("worktrees").join("feat").join("example"));
+    assert!(path.exists());
+    assert!(path.join("README").exists());
+
+    let branches = worktree_branches(&repo);
+    assert!(branches.iter().any(|b| b == "feat/example"), "{branches:?}");
+}
+
+#[test]
+fn worktree_root_override_redirects_placement() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    let wt_root = TempDir::new().unwrap();
+    let mgr = WorktreeManager::new(Some(wt_root.path().to_path_buf()));
+
+    // The repo's basename sits between the root and the branch slug, so two
+    // repos spawning the same branch name don't target one directory.
+    let repo_name = repo.file_name().unwrap();
+    let path = mgr.add_new(&repo, "feat/example").expect("add worktree");
+    // The override root disambiguates same-named checkouts with a digest of
+    // the full repo path, and the branch keeps its own shape.
+    // <root>/<repo basename>-<digest>/feat/example
+    let prefix = format!("{}-", repo_name.to_string_lossy());
+    let repo_dir_name = path
+        .strip_prefix(wt_root.path())
+        .unwrap()
+        .components()
+        .next()
+        .unwrap();
+    assert!(
+        repo_dir_name
+            .as_os_str()
+            .to_string_lossy()
+            .starts_with(&prefix),
+        "{path:?}"
+    );
+    assert!(path.ends_with("feat/example"), "{path:?}");
+    assert!(path.exists());
+}
+
+/// Anything at all occupying the target path — ours, the operator's, or an
+/// unrelated directory — is sidestepped, not adopted and not reported (#77).
+#[test]
+fn an_occupied_target_path_gets_a_numeric_suffix() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    // A non-git directory sits exactly where the worktree would go.
+    let squatter = repo.join("worktrees").join("feat").join("collide");
+    std::fs::create_dir_all(&squatter).unwrap();
+    std::fs::write(squatter.join("operator-notes.txt"), b"mine\n").unwrap();
+
+    let mgr = WorktreeManager::new(None);
+    let path = mgr.add_new(&repo, "feat/collide").expect("sidesteps");
+    assert_eq!(path, repo.join("worktrees").join("feat").join("collide-2"));
+    assert!(path.exists());
+    assert!(
+        squatter.join("operator-notes.txt").exists(),
+        "the occupant is untouched"
+    );
+}
+
 #[test]
 fn add_twice_generates_distinct_paths() {
     let repo_dir = TempDir::new().unwrap();
@@ -49,15 +126,132 @@ fn add_twice_generates_distinct_paths() {
     init_repo(&repo);
 
     let wt_root = TempDir::new().unwrap();
-    let mgr = WorktreeManager::new(wt_root.path());
+    let mgr = WorktreeManager::new(Some(wt_root.path().to_path_buf()));
 
-    let p1 = mgr.add(&repo, "feat/a").expect("add a");
-    let p2 = mgr.add(&repo, "feat/b").expect("add b");
+    let p1 = mgr.add_new(&repo, "feat/a").expect("add a");
+    let p2 = mgr.add_new(&repo, "feat/b").expect("add b");
     assert_ne!(p1, p2);
     assert!(p1.exists());
     assert!(p2.exists());
 }
 
+/// The unsaved-work probe (#79) counts uncommitted tracked changes.
+#[test]
+fn the_probe_counts_uncommitted_tracked_changes() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    let mgr = WorktreeManager::new(None);
+    let path = mgr.add_new(&repo, "feat/dirty").expect("add");
+    std::fs::write(path.join("README"), b"unsaved edits\n").unwrap();
+
+    let w = in_the_way(&path).expect("probe");
+    assert_eq!(w.uncommitted_files, 1);
+    assert_eq!(w.untracked_files, 0);
+}
+
+/// Untracked sources count; a staged new file is also unsaved tracked work.
+#[test]
+fn the_probe_counts_untracked_files() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    let mgr = WorktreeManager::new(None);
+    let path = mgr.add_new(&repo, "feat/untracked").expect("add");
+    std::fs::write(path.join("notes.txt"), b"wip\n").unwrap();
+    std::fs::write(path.join("more.txt"), b"also wip\n").unwrap();
+
+    let w = in_the_way(&path).expect("probe");
+    assert_eq!(w.untracked_files, 2);
+    assert_eq!(w.uncommitted_files, 0);
+
+    run_git(&path, &["add", "notes.txt"]);
+    let w = in_the_way(&path).expect("probe");
+    assert_eq!(w.uncommitted_files, 1, "staged counts as uncommitted");
+    assert_eq!(w.untracked_files, 1);
+}
+
+/// Ignored files NEVER block: every Rust checkout has a `target/`, and
+/// counting ignored output would leave no session killable (#79).
+#[test]
+fn the_probe_ignores_ignored_files() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    // .gitignore must be committed, or it would itself read as untracked.
+    std::fs::write(repo.join(".gitignore"), b"/target\n").unwrap();
+    run_git(&repo, &["add", ".gitignore"]);
+    run_git(&repo, &["commit", "-q", "-m", "ignore target"]);
+
+    let mgr = WorktreeManager::new(None);
+    let path = mgr.add_new(&repo, "feat/builds").expect("add");
+    std::fs::create_dir_all(path.join("target")).unwrap();
+    std::fs::write(path.join("target").join("app.o"), b"binary\n").unwrap();
+
+    let w = in_the_way(&path).expect("probe");
+    assert_eq!(w.uncommitted_files, 0);
+    assert_eq!(w.untracked_files, 0);
+
+    // With the branch pushed too, an ignored-only tree reads fully clean.
+    let origin_dir = TempDir::new().unwrap();
+    init_bare_repo(origin_dir.path());
+    push_all_to_origin(&repo, origin_dir.path());
+    let w = in_the_way(&path).expect("probe after push");
+    assert!(w.is_clear(), "ignored-only worktree must read clean: {w:?}");
+}
+
+/// Commits reachable from no remote-tracking ref block; pushing the branch
+/// clears them. With no remote at all every commit is unreachable from one,
+/// which is exactly why feature branches almost always refuse (#79).
+#[test]
+fn the_probe_counts_unpushed_commits_until_the_branch_is_pushed() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    let mgr = WorktreeManager::new(None);
+    let path = mgr.add_new(&repo, "feat/branch").expect("add");
+
+    let w = in_the_way(&path).expect("probe");
+    assert!(
+        w.unpushed_commits >= 1,
+        "a fresh branch has no remote-tracking ref: {w:?}"
+    );
+
+    let origin_dir = TempDir::new().unwrap();
+    init_bare_repo(origin_dir.path());
+    push_all_to_origin(&repo, origin_dir.path());
+
+    let w = in_the_way(&path).expect("probe after push");
+    assert_eq!(w.unpushed_commits, 0, "{w:?}");
+    assert!(w.is_clear(), "pushed and clean must be empty: {w:?}");
+}
+
+/// The full breakdown names each blocker with its count.
+#[test]
+fn the_probe_reports_every_blocker_at_once() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    let mgr = WorktreeManager::new(None);
+    let path = mgr.add_new(&repo, "feat/mixed").expect("add");
+    std::fs::write(path.join("README"), b"edited\n").unwrap();
+    std::fs::write(path.join("scratch.txt"), b"untracked\n").unwrap();
+
+    let w = in_the_way(&path).expect("probe");
+    assert_eq!(w.uncommitted_files, 1);
+    assert_eq!(w.untracked_files, 1);
+    assert!(w.unpushed_commits >= 1);
+    let summary = w.to_string();
+    assert!(summary.contains("1 uncommitted file"), "{summary}");
+    assert!(summary.contains("1 untracked file"), "{summary}");
+    assert!(summary.contains("unpushed commit"), "{summary}");
+}
+
 #[test]
 fn remove_prunes_worktree() {
     let repo_dir = TempDir::new().unwrap();
@@ -65,9 +259,9 @@ fn remove_prunes_worktree() {
     init_repo(&repo);
 
     let wt_root = TempDir::new().unwrap();
-    let mgr = WorktreeManager::new(wt_root.path());
+    let mgr = WorktreeManager::new(Some(wt_root.path().to_path_buf()));
 
-    let path = mgr.add(&repo, "feat/gone").expect("add");
+    let path = mgr.add_new(&repo, "feat/gone").expect("add");
     assert!(path.exists());
 
     mgr.remove(&repo, &path).expect("remove");
@@ -79,6 +273,138 @@ fn remove_prunes_worktree() {
     assert_eq!(branches, vec!["main".to_string()]);
 }
 
+#[test]
+fn add_existing_checks_out_branch_without_creating_it() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    // Pre-create the branch with its own commit so we can tell a checkout
+    // from an accidental `-b`.
+    let created = Command::new("git")
+        .arg("-C")
+        .arg(&repo)
+        .args(["checkout", "-q", "-b", "feat/dup"])
+        .status()
+        .unwrap();
+    assert!(created.success());
+    std::fs::write(repo.join("FEATURE"), b"dup\n").unwrap();
+    let staged = Command::new("git")
+        .arg("-C")
+        .arg(&repo)
+        .args(["add", "."])
+        .status()
+        .unwrap();
+    assert!(staged.success());
+    let committed = Command::new("git")
+        .arg("-C")
+        .arg(&repo)
+        .args(["commit", "-q", "-am", "wip"])
+        .status()
+        .unwrap();
+    assert!(committed.success());
+    let back = Command::new("git")
+        .arg("-C")
+        .arg(&repo)
+        .args(["checkout", "-q", "main"])
+        .status()
+        .unwrap();
+    assert!(back.success());
+
+    let wt_root = TempDir::new().unwrap();
+    let mgr = WorktreeManager::new(Some(wt_root.path().to_path_buf()));
+
+    let path = mgr.add_existing(&repo, "feat/dup").expect("add existing");
+    assert!(path.exists());
+    assert!(path.join("README").exists());
+
+    // The branch set is unchanged: `feat/dup` was checked out, not recreated.
+    let branches = worktree_branches(&repo);
+    let mut sorted = branches.clone();
+    sorted.sort();
+    assert_eq!(
+        sorted,
+        vec!["feat/dup".to_string(), "main".to_string()],
+        "{branches:?}"
+    );
+}
+
+/// Removal is guarded upstream now (#79): the kill refuses unsaved work
+/// before anything is torn down, so by the time `remove` runs the tree is
+/// clean. Git still refuses a dirty tree on its own — this asserts that last
+/// line of defense — and committed-but-unpushed work does not block removal,
+/// because `worktree remove` keeps `refs/heads/<branch>` and the commits stay
+/// reachable.
+#[test]
+fn remove_still_relies_on_git_refusing_a_dirty_tree() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    let mgr = WorktreeManager::new(None);
+    let path = mgr.add_new(&repo, "feat/dirty").expect("add");
+    std::fs::write(path.join("README"), b"unsaved edits\n").unwrap();
+
+    mgr.remove(&repo, &path)
+        .expect_err("dirty worktree must be refused");
+    assert!(path.exists(), "guarded worktree must stay on disk");
+
+    run_git(&path, &["add", "."]);
+    run_git(&path, &["commit", "-q", "-m", "saved"]);
+
+    mgr.remove(&repo, &path).expect("committed work can go");
+    assert!(!path.exists());
+    assert!(
+        worktree_branches(&repo).contains(&"main".to_string()),
+        "the branch survives removal"
+    );
+    let branches = String::from_utf8(
+        Command::new("git")
+            .arg("-C")
+            .arg(&repo)
+            .args(["for-each-ref", "--format=%(refname:short)", "refs/heads"])
+            .output()
+            .unwrap()
+            .stdout,
+    )
+    .unwrap();
+    assert!(branches.contains("feat/dirty"), "{branches}");
+}
+
+/// A worktree whose directory vanished must be pruned, not misread as holding
+/// unsaved work — otherwise the registration is stranded and, because paths
+/// are deterministic, that branch can never be spawned again (#56 review).
+#[test]
+fn remove_prunes_a_worktree_whose_directory_vanished() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    let mgr = WorktreeManager::new(None);
+    let path = mgr.add_new(&repo, "feat/gone").expect("add");
+    std::fs::remove_dir_all(&path).unwrap();
+
+    mgr.remove(&repo, &path)
+        .expect("a vanished worktree prunes");
+    // The registration is gone too, so the same branch can be spawned again.
+    mgr.add_existing(&repo, "feat/gone")
+        .expect("branch is spawnable again");
+}
+
+fn run_git(dir: &std::path::Path, args: &[&str]) {
+    let out = Command::new("git")
+        .arg("-C")
+        .arg(dir)
+        .args(args)
+        .output()
+        .expect("git spawn");
+    assert!(
+        out.status.success(),
+        "git {args:?} failed: {}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+}
+
 #[test]
 fn add_fails_when_branch_already_exists() {
     let repo_dir = TempDir::new().unwrap();
@@ -95,9 +421,152 @@ fn add_fails_when_branch_already_exists() {
     assert!(status.success());
 
     let wt_root = TempDir::new().unwrap();
-    let mgr = WorktreeManager::new(wt_root.path());
+    let mgr = WorktreeManager::new(Some(wt_root.path().to_path_buf()));
 
-    let err = mgr.add(&repo, "feat/dup").unwrap_err();
+    let err = mgr.add_new(&repo, "feat/dup").unwrap_err();
     let msg = format!("{err}");
     assert!(msg.contains("git exited"), "{msg}");
 }
+
+/// The project picker lists linked worktrees as pickable rows, so `base_repo`
+/// is easily a worktree rather than the main checkout. Placing inside it would
+/// nest one worktree in another — and git hides a registered worktree's
+/// contents from the outer `git status`, so the outer tree reads clean and
+/// removing it deletes the inner one's uncommitted work (#54 review).
+#[test]
+fn placement_resolves_a_linked_worktree_to_the_main_checkout() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    let mgr = WorktreeManager::new(None);
+    let outer = mgr.add_new(&repo, "feat/outer").expect("add outer");
+
+    // Spawn again with the *worktree* as the base, the way the picker would.
+    let inner = mgr.add_new(&outer, "feat/inner").expect("add inner");
+    assert!(
+        !inner.starts_with(&outer),
+        "must not nest: {inner:?} inside {outer:?}"
+    );
+    assert!(
+        inner.starts_with(repo.canonicalize().unwrap().join("worktrees")),
+        "placed against the main checkout: {inner:?}"
+    );
+}
+
+/// Belt and braces for a nesting that predates this daemon: refuse to remove
+/// a worktree that has another registered underneath it.
+#[test]
+fn remove_refuses_a_worktree_holding_a_nested_one() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    let mgr = WorktreeManager::new(None);
+    let outer = mgr.add_new(&repo, "feat/outer").expect("add outer");
+    // Register one by hand inside `outer`, bypassing our placement.
+    let nested = outer.join("worktrees").join("hand-rolled");
+    run_git(
+        &repo,
+        &[
+            "worktree",
+            "add",
+            "-b",
+            "feat/hand",
+            nested.to_str().unwrap(),
+        ],
+    );
+    std::fs::write(nested.join("notes.txt"), b"unsaved\n").unwrap();
+
+    mgr.remove(&repo, &outer)
+        .expect_err("a worktree holding a nested one must be refused");
+    assert!(nested.join("notes.txt").exists(), "inner work survives");
+}
+
+/// Two repos spawning the same branch name under one override root must not
+/// collide (#54 review).
+#[test]
+fn override_root_keeps_repos_apart() {
+    let root_dir = TempDir::new().unwrap();
+    let a_dir = TempDir::new().unwrap();
+    let b_dir = TempDir::new().unwrap();
+    init_repo(a_dir.path());
+    init_repo(b_dir.path());
+
+    let mgr = WorktreeManager::new(Some(root_dir.path().to_path_buf()));
+    let a = mgr.add_new(a_dir.path(), "feat/shared").expect("repo a");
+    let b = mgr.add_new(b_dir.path(), "feat/shared").expect("repo b");
+    assert_ne!(a, b, "same branch name in two repos must not collide");
+}
+
+/// Flattening `/` and `.` to `-` made these three share one directory, so the
+/// losers could never get a worktree (#54 review).
+#[test]
+fn similar_branch_names_get_distinct_directories() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    let mgr = WorktreeManager::new(None);
+    let a = mgr.add_new(&repo, "feat/x").expect("feat/x");
+    let b = mgr.add_new(&repo, "feat.x").expect("feat.x");
+    let c = mgr.add_new(&repo, "feat-x").expect("feat-x");
+    assert_ne!(a, b);
+    assert_ne!(b, c);
+    assert_ne!(a, c);
+    assert!(a.ends_with("feat/x"), "{a:?}");
+}
+
+/// A guarded leftover stays on disk untouched, and is never adopted (#77).
+/// Re-spawning its branch is refused by git itself — the branch is still
+/// checked out inside the leftover — which the caller surfaces.
+#[test]
+fn a_guarded_leftover_is_never_adopted() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    let mgr = WorktreeManager::new(None);
+    let first = mgr.add_new(&repo, "feat/resume").expect("add");
+    std::fs::write(first.join("notes.txt"), b"unsaved\n").unwrap();
+
+    // Removal is refused — git itself refuses a dirty tree — leaving it on
+    // disk; the daemon-side guard lives on the kill (#79).
+    mgr.remove(&repo, &first)
+        .expect_err("dirty tree is guarded");
+
+    let err = mgr
+        .add_existing(&repo, "feat/resume")
+        .expect_err("a branch already checked out cannot be spawned twice");
+    assert!(format!("{err}").contains("git exited"), "{err}");
+    assert!(
+        first.join("notes.txt").exists(),
+        "the leftover's unsaved work is untouched"
+    );
+}
+
+/// The `worktree_root` override gets the same collision suffix (#77).
+#[test]
+fn the_override_root_suffixes_collisions_too() {
+    let repo_dir = TempDir::new().unwrap();
+    let repo = repo_dir.path().to_path_buf();
+    init_repo(&repo);
+
+    let wt_root = TempDir::new().unwrap();
+    let mgr = WorktreeManager::new(Some(wt_root.path().to_path_buf()));
+
+    // First add settles `<root>/<repo basename>-<digest>/` so the squatter
+    // can be created at the exact target.
+    mgr.add_new(&repo, "feat/first").expect("add first");
+    let repo_dir_in_root = std::fs::read_dir(wt_root.path())
+        .unwrap()
+        .next()
+        .unwrap()
+        .unwrap()
+        .path();
+    let squatter = repo_dir_in_root.join("feat").join("collide");
+    std::fs::create_dir_all(&squatter).unwrap();
+
+    let path = mgr.add_new(&repo, "feat/collide").expect("sidesteps");
+    assert_eq!(path, squatter.with_file_name("collide-2"), "{path:?}");
+}

crates/maestro-e2e/Cargo.toml

@@ -13,8 +13,8 @@ path = "src/lib.rs"
 [dependencies]
 chrono.workspace = true
 futures-util.workspace = true
-maestro-protocol.workspace = true
-reqwest.workspace = true
+maestro-protocol = { workspace = true, features = ["client"] }
+maestro-testing.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 tempfile.workspace = true

crates/maestro-e2e/src/client.rs

@@ -1,4 +1,9 @@
-//! Thin HTTP+WS client used by tests to drive a daemon's `/api/*` surface.
+//! Thin test harness over [`maestro_protocol::DaemonClient`].
+//!
+//! HTTP calls delegate to the shared client so the harness exercises the same
+//! request building, timeouts and error decoding the CLI and TUI use. Only the
+//! WebSocket helpers are test-specific: they hand back a raw stream, or a
+//! handle that accumulates events in the background.
 
 #![allow(clippy::result_large_err)]
 
@@ -6,8 +11,9 @@ use std::sync::Arc;
 use std::time::Duration;
 
 use futures_util::{SinkExt, StreamExt};
-use maestro_protocol::{CatalogEvent, CreateSessionRequest, Session};
-use reqwest::Client as HttpClient;
+use maestro_protocol::{
+    BranchInfo, CatalogEvent, CreateSessionRequest, DaemonClient, Project, Session,
+};
 use tokio_tungstenite::tungstenite::client::IntoClientRequest;
 use tokio_tungstenite::tungstenite::Message as WsMessage;
 use tokio_tungstenite::{connect_async, MaybeTlsStream, WebSocketStream};
@@ -16,73 +22,60 @@ use uuid::Uuid;
 #[derive(Debug, thiserror::Error)]
 #[allow(clippy::result_large_err)]
 pub enum ClientError {
-    #[error("http: {0}")]
-    Http(#[from] reqwest::Error),
+    #[error(transparent)]
+    Api(#[from] maestro_protocol::ClientError),
     #[error("ws: {0}")]
     Ws(#[from] tokio_tungstenite::tungstenite::Error),
     #[error("json: {0}")]
     Json(#[from] serde_json::Error),
-    #[error("unexpected status {status}: {body}")]
-    Status { status: u16, body: String },
 }
 
-/// HTTP client plus a few WS-aware helpers, bound to one daemon.
+/// Daemon client plus a few WS-aware helpers, bound to one daemon.
 #[derive(Debug, Clone)]
 pub struct TestClient {
-    http_base: String,
-    ws_base: String,
-    http: HttpClient,
+    daemon: DaemonClient,
 }
 
+/// Per-request budget. Well below the client default: a hung daemon should fail
+/// the test, not stall the suite for 30s.
+const TEST_TIMEOUT: Duration = Duration::from_secs(5);
+
 impl TestClient {
-    pub fn new(http_base: &str, ws_base: &str) -> Self {
-        let http = HttpClient::builder()
-            .timeout(Duration::from_secs(5))
-            .build()
-            .expect("reqwest client");
+    pub fn new(http_base: &str) -> Self {
         Self {
-            http_base: http_base.trim_end_matches('/').to_string(),
-            ws_base: ws_base.trim_end_matches('/').to_string(),
-            http,
+            daemon: DaemonClient::with_timeouts(http_base, TEST_TIMEOUT, TEST_TIMEOUT),
         }
     }
 
+    /// The shared client underneath, for calls this harness doesn't wrap.
+    pub fn daemon(&self) -> &DaemonClient {
+        &self.daemon
+    }
+
     pub async fn list_sessions(&self) -> Result<Vec<Session>, ClientError> {
-        let r = self
-            .http
-            .get(format!("{}/api/sessions", self.http_base))
-            .send()
-            .await?;
-        check_ok(&r)?;
-        Ok(r.json().await?)
+        Ok(self.daemon.list_sessions().await?)
     }
 
     pub async fn spawn_session(&self, req: &CreateSessionRequest) -> Result<Session, ClientError> {
-        let r = self
-            .http
-            .post(format!("{}/api/sessions", self.http_base))
-            .json(req)
-            .send()
-            .await?;
-        let status = r.status();
-        if !status.is_success() {
-            let body = r.text().await.unwrap_or_default();
-            return Err(ClientError::Status {
-                status: status.as_u16(),
-                body,
-            });
-        }
-        Ok(r.json().await?)
+        Ok(self.daemon.create_session(req).await?)
     }
 
     pub async fn kill_session(&self, id: Uuid) -> Result<(), ClientError> {
-        let r = self
-            .http
-            .delete(format!("{}/api/sessions/{id}", self.http_base))
-            .send()
-            .await?;
-        check_ok(&r)?;
-        Ok(())
+        Ok(self.daemon.kill_session(id, false).await.map(|_| ())?)
+    }
+
+    /// Kill with `force=true`: overrides a kill refusal and leaves the
+    /// guarded worktree on disk (#81).
+    pub async fn kill_session_forced(&self, id: Uuid) -> Result<(), ClientError> {
+        Ok(self.daemon.kill_session(id, true).await?)
+    }
+
+    pub async fn list_projects(&self) -> Result<Vec<Project>, ClientError> {
+        Ok(self.daemon.list_projects().await?)
+    }
+
+    pub async fn list_branches(&self, path: &str) -> Result<Vec<BranchInfo>, ClientError> {
+        Ok(self.daemon.list_branches(path).await?)
     }
 
     /// Connect to the daemon's per-session WS and return the stream. The
@@ -91,8 +84,7 @@ impl TestClient {
         &self,
         id: Uuid,
     ) -> Result<WebSocketStream<MaybeTlsStream<tokio::net::TcpStream>>, ClientError> {
-        let url = format!("{}/api/attach/{id}", self.ws_base);
-        let request = url.into_client_request()?;
+        let request = self.daemon.attach_url(id)?.into_client_request()?;
         let (ws, _resp) = connect_async(request).await?;
         Ok(ws)
     }
@@ -100,7 +92,7 @@ impl TestClient {
     /// Subscribe to the daemon's `/api/events` WS. Returns a handle whose
     /// background task pushes parsed events into a shared vector.
     pub async fn subscribe_events(&self) -> EventStream {
-        let url = format!("{}/api/events", self.ws_base);
+        let url = self.daemon.events_url().expect("events url");
         let request = url.into_client_request().expect("ws req");
         let (ws, _resp) = connect_async(request).await.expect("events ws");
 
@@ -125,17 +117,6 @@ impl TestClient {
     }
 }
 
-fn check_ok(r: &reqwest::Response) -> Result<(), ClientError> {
-    let status = r.status();
-    if !status.is_success() {
-        return Err(ClientError::Status {
-            status: status.as_u16(),
-            body: format!("HTTP {status}"),
-        });
-    }
-    Ok(())
-}
-
 /// Handle to a background task draining the events WS into a vector.
 #[derive(Debug)]
 pub struct EventStream {

crates/maestro-e2e/src/daemon.rs

@@ -29,11 +29,32 @@ impl Daemon {
         Self::spawn_at(SocketAddr::from((Ipv4Addr::LOCALHOST, free_port()))).await
     }
 
+    /// Spawn with a config file pre-seeded at the daemon's expected path
+    /// (`$XDG_CONFIG_HOME/maestro/config.toml`).
+    pub async fn spawn_with_config(toml: &str) -> Self {
+        Self::spawn_config_at(
+            SocketAddr::from((Ipv4Addr::LOCALHOST, free_port())),
+            Some(toml),
+        )
+        .await
+    }
+
     /// Spawn on a caller-supplied bind address.
     pub async fn spawn_at(bind: SocketAddr) -> Self {
+        Self::spawn_config_at(bind, None).await
+    }
+
+    /// Spawn on a caller-supplied bind address, with an optional config file.
+    async fn spawn_config_at(bind: SocketAddr, config: impl Into<Option<&str>>) -> Self {
         let home = TempDir::new().expect("home tmpdir");
         let tmux = TempDir::new().expect("tmux tmpdir");
 
+        if let Some(toml) = config.into() {
+            let dir = home.path().join(".config").join("maestro");
+            std::fs::create_dir_all(&dir).expect("config dir");
+            std::fs::write(dir.join("config.toml"), toml).expect("write config.toml");
+        }
+
         let child = launch(bind, home.path(), tmux.path());
         let me = Self {
             bind_addr: bind,
@@ -50,9 +71,11 @@ impl Daemon {
         format!("http://{}", self.bind_addr)
     }
 
-    /// WS base URL of this daemon's API.
-    pub fn ws_base(&self) -> String {
-        format!("ws://{}", self.bind_addr)
+    /// Shared client bound to this daemon, with the harness's tighter budget.
+    pub fn client(&self) -> maestro_protocol::DaemonClient {
+        crate::client::TestClient::new(&self.http_base())
+            .daemon()
+            .clone()
     }
 
     /// Stop the underlying process, but keep its state dirs around so we can

crates/maestro-e2e/src/lib.rs

@@ -14,5 +14,5 @@ pub mod daemon;
 pub mod util;
 
 pub use build::workspace_target_bin;
-pub use client::TestClient;
+pub use client::{ClientError, TestClient};
 pub use daemon::Daemon;

crates/maestro-e2e/tests/e2e.rs

@@ -21,7 +21,7 @@ use tokio_tungstenite::tungstenite::Message as WsMessage;
 
 async fn bring_up() -> (Daemon, TestClient) {
     let daemon = Daemon::spawn().await;
-    let client = TestClient::new(&daemon.http_base(), &daemon.ws_base());
+    let client = TestClient::new(&daemon.http_base());
     (daemon, client)
 }
 
@@ -35,6 +35,28 @@ fn create_req(cwd: &std::path::Path, command: &str) -> CreateSessionRequest {
     }
 }
 
+/// A worktree spec built through its wire shape. The daemon and clients ship
+/// together (#87 dropped `cleanup_on_kill` from the struct), so the JSON
+/// object carries only the fields the lifecycle actually honours.
+fn worktree_spec(base_repo: &std::path::Path, branch: &str, create_branch: bool) -> WorktreeSpec {
+    WorktreeSpec {
+        base_repo: base_repo.to_path_buf(),
+        branch: branch.into(),
+        create_branch,
+    }
+}
+
+/// Spawn request carrying a worktree spec against `base`.
+fn worktree_req(base: &std::path::Path, branch: &str, create_branch: bool) -> CreateSessionRequest {
+    CreateSessionRequest {
+        cwd: base.to_path_buf(),
+        command: "sleep 30".into(),
+        env: HashMap::new(),
+        metadata: HashMap::new(),
+        worktree: Some(worktree_spec(base, branch, create_branch)),
+    }
+}
+
 #[tokio::test(flavor = "multi_thread")]
 async fn lists_spawned_sessions() {
     let (_daemon, client) = bring_up().await;
@@ -114,7 +136,7 @@ async fn multi_attach_sees_same_output() {
 }
 
 #[tokio::test(flavor = "multi_thread")]
-async fn cleanup_on_kill_removes_worktree() {
+async fn kill_removes_clean_worktree() {
     let (_daemon, client) = bring_up().await;
 
     let base = TempDir::new().unwrap();
@@ -125,24 +147,21 @@ async fn cleanup_on_kill_removes_worktree() {
         command: "sleep 30".into(),
         env: HashMap::new(),
         metadata: HashMap::new(),
-        worktree: Some(WorktreeSpec {
-            base_repo: base.path().to_path_buf(),
-            branch: "feature/e2e".into(),
-            cleanup_on_kill: true,
-        }),
+        worktree: Some(worktree_spec(base.path(), "feature/e2e", true)),
     };
 
     let s = client.spawn_session(&req).await.expect("spawn worktree");
-    // The daemon's WorktreeManager puts new worktrees under
-    // `<state_dir>/worktrees/<branch>`. We can't peek the daemon's state dir
-    // directly from here, but we can verify by asking git: a worktree must
-    // exist that lives outside the original repo.
+    // Worktrees live inside the base repo at `<repo>/worktrees/<branch>`
+    // (#56), so `git worktree list` must show the predictable in-repo path.
     let worktrees = git_worktree_list(base.path());
     assert!(
-        worktrees.iter().any(|w| w.contains("feature/e2e")),
-        "expected a worktree for feature/e2e branch, got: {worktrees:?}"
+        worktrees
+            .iter()
+            .any(|w| w.contains("worktrees/feature/e2e")),
+        "expected a worktree for feature/e2e under <repo>/worktrees, got: {worktrees:?}"
     );
 
+    let _origin = throwaway_origin(base.path());
     client.kill_session(s.id).await.expect("kill");
 
     // Give the daemon a moment to remove the worktree, then verify.
@@ -160,6 +179,727 @@ async fn cleanup_on_kill_removes_worktree() {
     );
 }
 
+/// The kill guard (#79): killing a session whose worktree holds uncommitted
+/// changes is refused outright. Nothing happens — the session keeps running
+/// as the operator's handle on their unfinished work, the tree stays on disk,
+/// and the refusal names what blocked it and how much.
+#[tokio::test(flavor = "multi_thread")]
+async fn kill_refuses_worktree_with_uncommitted_changes() {
+    let (_daemon, client) = bring_up().await;
+
+    let base = TempDir::new().unwrap();
+    init_repo(base.path());
+    let wt_path = base
+        .path()
+        .join("worktrees")
+        .join("feature")
+        .join("unsaved");
+
+    let req = CreateSessionRequest {
+        cwd: base.path().to_path_buf(),
+        command: "sleep 30".into(),
+        env: HashMap::new(),
+        metadata: HashMap::new(),
+        worktree: Some(worktree_spec(base.path(), "feature/unsaved", true)),
+    };
+
+    let s = client.spawn_session(&req).await.expect("spawn worktree");
+    assert!(wt_path.exists());
+    std::fs::write(wt_path.join("README"), b"unsaved edits\n").unwrap();
+
+    let err = client
+        .kill_session(s.id)
+        .await
+        .expect_err("kill must refuse");
+    match err {
+        maestro_e2e::ClientError::Api(maestro_protocol::ClientError::Api { info, .. }) => {
+            assert_eq!(info.code, "kill_guarded", "{info:?}");
+            let breakdown = info.unsaved_work.expect("breakdown on the wire");
+            assert_eq!(breakdown.uncommitted_files, 1);
+        }
+        other => panic!("expected a kill_guarded refusal, got {other:?}"),
+    }
+
+    // The session survives and the dirty worktree stays findable on disk.
+    let sessions = client.list_sessions().await.unwrap_or_default();
+    assert!(
+        sessions.iter().any(|x| x.id == s.id),
+        "a refused kill must keep the session alive"
+    );
+    assert!(
+        wt_path.exists(),
+        "guarded worktree must be left on disk after kill"
+    );
+    // Left findable, not silently half-deleted: git still registers it and
+    // the uncommitted edit survives byte for byte (#66).
+    assert!(
+        git_worktree_list(base.path())
+            .iter()
+            .any(|w| w.contains("feature/unsaved")),
+        "guarded worktree must stay registered in git worktree list"
+    );
+    assert_eq!(
+        std::fs::read(wt_path.join("README")).unwrap(),
+        b"unsaved edits\n",
+        "uncommitted changes must survive the guarded kill"
+    );
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn spawn_on_existing_branch_checks_it_out() {
+    let (_daemon, client) = bring_up().await;
+
+    let base = TempDir::new().unwrap();
+    init_repo(base.path());
+    run_git(&["branch", "feature/existing"], base.path());
+
+    let req = CreateSessionRequest {
+        cwd: base.path().to_path_buf(),
+        command: "sleep 30".into(),
+        env: HashMap::new(),
+        metadata: HashMap::new(),
+        worktree: Some(worktree_spec(base.path(), "feature/existing", false)),
+    };
+
+    let s = client
+        .spawn_session(&req)
+        .await
+        .expect("spawn on existing branch");
+    let worktrees = git_worktree_list(base.path());
+    assert!(
+        worktrees.iter().any(|w| w.contains("feature/existing")),
+        "expected a worktree checked out at feature/existing, got: {worktrees:?}"
+    );
+
+    let _origin = throwaway_origin(base.path());
+    client.kill_session(s.id).await.expect("kill");
+}
+
+/// #66: a fresh branch spawns a worktree at `<repo>/worktrees/<branch>` and
+/// the session actually runs inside it — `current_cwd` comes from tmux's live
+/// pane state, not from the spawn request.
+#[tokio::test(flavor = "multi_thread")]
+async fn spawn_new_branch_creates_worktree_and_runs_in_it() {
+    let (_daemon, client) = bring_up().await;
+
+    let base = TempDir::new().unwrap();
+    init_repo(base.path());
+    let wt_path = base.path().join("worktrees").join("feature").join("fresh");
+
+    let s = client
+        .spawn_session(&worktree_req(base.path(), "feature/fresh", true))
+        .await
+        .expect("spawn new-branch worktree");
+
+    assert_eq!(
+        s.cwd, wt_path,
+        "session must report the worktree as its cwd"
+    );
+    assert!(wt_path.is_dir(), "worktree directory must exist on disk");
+
+    // The activity watcher fills `current_cwd` from tmux's pane_current_path,
+    // so this is the daemon confirming where the process really runs.
+    wait_for_async(
+        "session's live cwd is the worktree",
+        Duration::from_secs(20),
+        || {
+            let client = client.clone();
+            let id = s.id;
+            let want = wt_path.clone();
+            async move {
+                client
+                    .list_sessions()
+                    .await
+                    .ok()
+                    .and_then(|ss| ss.iter().find(|s| s.id == id).cloned())
+                    .map(|s| s.current_cwd == Some(want.clone()))
+                    .unwrap_or(false)
+            }
+        },
+    )
+    .await;
+
+    let _origin = throwaway_origin(base.path());
+    client.kill_session(s.id).await.expect("kill");
+}
+
+/// #66: a second spawn onto a branch that already has a worktree is rejected
+/// with a structured worktree error; the first worktree stays intact.
+#[tokio::test(flavor = "multi_thread")]
+async fn second_spawn_on_same_branch_is_rejected() {
+    let (_daemon, client) = bring_up().await;
+
+    let base = TempDir::new().unwrap();
+    init_repo(base.path());
+
+    let first = client
+        .spawn_session(&worktree_req(base.path(), "feature/dup", true))
+        .await
+        .expect("first spawn");
+    let dup = client
+        .spawn_session(&worktree_req(base.path(), "feature/dup", true))
+        .await;
+    match dup {
+        Err(maestro_e2e::ClientError::Api(maestro_protocol::ClientError::Api { info, .. })) => {
+            assert_eq!(
+                info.code, "worktree_failed",
+                "expected worktree error: {info:?}"
+            );
+        }
+        other => panic!("expected rejection for duplicate branch, got {other:?}"),
+    }
+
+    // Exactly one registration, one directory, still usable.
+    // Count branch records only: the worktree path now contains the branch
+    // name too (`worktrees/feature/dup`), so a substring match over every line
+    // would count the same tree twice.
+    let holders = git_worktree_list(base.path())
+        .iter()
+        .filter(|w| w.as_str() == "branch refs/heads/feature/dup")
+        .count();
+    assert_eq!(holders, 1, "duplicate spawn must not register another tree");
+    assert!(
+        base.path()
+            .join("worktrees")
+            .join("feature")
+            .join("dup")
+            .is_dir(),
+        "original worktree must be untouched"
+    );
+
+    let _origin = throwaway_origin(base.path());
+    client.kill_session(first.id).await.expect("kill");
+}
+
+/// #66/#56: when the client picks a *linked worktree* as base_repo, placement
+/// resolves through `--git-common-dir` to the main checkout, so the new tree
+/// lands at `<main>/worktrees/<branch>` instead of nesting inside another
+/// worktree.
+#[tokio::test(flavor = "multi_thread")]
+async fn spawn_from_linked_worktree_places_in_main_checkout() {
+    let (_daemon, client) = bring_up().await;
+
+    let base = TempDir::new().unwrap();
+    init_repo(base.path());
+    let linked = base.path().join("linked");
+    run_git(
+        &[
+            "worktree",
+            "add",
+            "-q",
+            "-b",
+            "other",
+            &linked.to_string_lossy(),
+        ],
+        base.path(),
+    );
+
+    let s = client
+        .spawn_session(&worktree_req(&linked, "feature/nested", true))
+        .await
+        .expect("spawn from linked worktree");
+
+    let want = base.path().join("worktrees").join("feature").join("nested");
+    assert_eq!(
+        s.cwd, want,
+        "worktree must be placed under the main checkout"
+    );
+    assert!(want.is_dir());
+    assert!(
+        !s.cwd.starts_with(&linked),
+        "worktrees must never nest inside another worktree"
+    );
+
+    let _origin = throwaway_origin(base.path());
+    client.kill_session(s.id).await.expect("kill");
+}
+
+// ---------------------------------------------------------------------------
+// Worktree lifecycle: collisions, guards, settling (#88)
+// ---------------------------------------------------------------------------
+
+/// #77/#88: the target path `<repo>/worktrees/<branch>` is occupied by a real
+/// registered worktree the operator made by hand. The daemon sidesteps to the
+/// suffixed directory and never touches the occupant — and both trees keep
+/// working: two registered worktrees, two sessions, each running in its own.
+#[tokio::test(flavor = "multi_thread")]
+async fn occupied_path_gets_suffixed_directory_and_both_worktrees_work() {
+    let (_daemon, client) = bring_up().await;
+
+    let base = TempDir::new().unwrap();
+    init_repo(base.path());
+
+    // An operator-made worktree sits exactly where `feature/collide` would go.
+    // Its branch is a different one, so the requested branch stays creatable.
+    let squatter = base
+        .path()
+        .join("worktrees")
+        .join("feature")
+        .join("collide");
+    run_git(
+        &[
+            "worktree",
+            "add",
+            "-q",
+            "-b",
+            "operator/manual",
+            &squatter.to_string_lossy(),
+        ],
+        base.path(),
+    );
+
+    let s = client
+        .spawn_session(&worktree_req(base.path(), "feature/collide", true))
+        .await
+        .expect("spawn onto occupied path");
+
+    let suffixed = base
+        .path()
+        .join("worktrees")
+        .join("feature")
+        .join("collide-2");
+    assert_eq!(
+        s.cwd, suffixed,
+        "the daemon must take the suffixed directory, not the occupied one"
+    );
+    assert!(suffixed.is_dir(), "suffixed worktree must exist on disk");
+
+    // Both trees are registered, distinct, and the squatter is byte-intact.
+    let registrations = git_worktree_list(base.path());
+    assert!(
+        registrations
+            .iter()
+            .any(|l| l == &format!("worktree {}", squatter.canonicalize().unwrap().display())),
+        "operator's worktree must stay registered: {registrations:?}"
+    );
+    assert!(
+        registrations.iter().any(|l| l.contains("collide-2")),
+        "suffixed worktree must be registered too: {registrations:?}"
+    );
+
+    // Both sessions run inside their own tree at the same time.
+    let sessions = client.list_sessions().await.expect("list");
+    assert!(
+        sessions.iter().any(|x| x.id == s.id && x.cwd == suffixed),
+        "session must keep running in its suffixed tree"
+    );
+
+    let _origin = throwaway_origin(base.path());
+    client.kill_session(s.id).await.expect("kill");
+
+    // Only the daemon-made trees go; the operator's manual one survives.
+    let after = git_worktree_list(base.path());
+    assert!(
+        after
+            .iter()
+            .any(|l| l == &format!("worktree {}", squatter.canonicalize().unwrap().display())),
+        "operator's worktree must outlive the sessions: {after:?}"
+    );
+}
+
+/// #77/#88: the target path holds a plain directory the daemon never made and
+/// git has never heard of. The daemon neither adopts it nor errors — it builds
+/// beside it and leaves every byte of it alone.
+#[tokio::test(flavor = "multi_thread")]
+async fn foreign_directory_is_sidestepped_never_adopted() {
+    let (_daemon, client) = bring_up().await;
+
+    let base = TempDir::new().unwrap();
+    init_repo(base.path());
+
+    let squatter = base
+        .path()
+        .join("worktrees")
+        .join("feature")
+        .join("foreign");
+    std::fs::create_dir_all(&squatter).unwrap();
+    std::fs::write(squatter.join("operator-notes.txt"), b"mine\n").unwrap();
+
+    let s = client
+        .spawn_session(&worktree_req(base.path(), "feature/foreign", true))
+        .await
+        .expect("spawn must sidestep, not adopt or fail");
+
+    let suffixed = base
+        .path()
+        .join("worktrees")
+        .join("feature")
+        .join("foreign-2");
+    assert_eq!(s.cwd, suffixed, "session must run in the suffixed tree");
+    assert_eq!(
+        std::fs::read(squatter.join("operator-notes.txt")).unwrap(),
+        b"mine\n",
+        "the foreign directory must be untouched"
+    );
+    let registrations = git_worktree_list(base.path());
+    let registered_paths: Vec<&str> = registrations
+        .iter()
+        .filter_map(|l| l.strip_prefix("worktree "))
+        .collect();
+    assert!(
+        !registered_paths
+            .iter()
+            .any(|p| *p == squatter.canonicalize().unwrap().display().to_string()),
+        "a plain directory must never be adopted as a worktree: {registered_paths:?}"
+    );
+
+    let _origin = throwaway_origin(base.path());
+    client.kill_session(s.id).await.expect("kill");
+    assert!(squatter.join("operator-notes.txt").exists());
+}
+
+/// #79/#88: killing with uncommitted changes is refused; committing and
+/// pushing that work clears the guard and the very same kill then succeeds
+/// and removes the tree. The session is the handle on the work: while it is
+/// unsaved the session stays, once it is saved the tree goes.
+#[tokio::test(flavor = "multi_thread")]
+async fn guarded_kill_then_commit_and_push_makes_the_same_kill_succeed() {
+    let (_daemon, client) = bring_up().await;
+
+    let base = TempDir::new().unwrap();
+    init_repo(base.path());
+    let _origin = throwaway_origin(base.path());
+
+    let wt = base.path().join("worktrees").join("feature").join("guard");
+    let s = client
+        .spawn_session(&worktree_req(base.path(), "feature/guard", true))
+        .await
+        .expect("spawn");
+    std::fs::write(wt.join("README"), b"work in progress\n").unwrap();
+
+    // Refused: the edit is uncommitted.
+    let err = client
+        .kill_session(s.id)
+        .await
+        .expect_err("kill must refuse");
+    match err {
+        maestro_e2e::ClientError::Api(maestro_protocol::ClientError::Api { info, .. }) => {
+            assert_eq!(info.code, "kill_guarded", "{info:?}");
+            let breakdown = info.unsaved_work.expect("breakdown on the wire");
+            assert_eq!(breakdown.uncommitted_files, 1);
+            assert_eq!(breakdown.unpushed_commits, 0);
+        }
+        other => panic!("expected a kill_guarded refusal, got {other:?}"),
+    }
+    assert!(
+        client
+            .list_sessions()
+            .await
+            .unwrap()
+            .iter()
+            .any(|x| x.id == s.id),
+        "a refused kill keeps the session running"
+    );
+    assert_eq!(
+        std::fs::read(wt.join("README")).unwrap(),
+        b"work in progress\n",
+        "the worktree is untouched by the refusal"
+    );
+
+    // The operator does exactly what the refusal asked for: save and push.
+    commit_all(&wt, "wip");
+    push_all(base.path());
+
+    client.kill_session(s.id).await.expect("kill after saving");
+
+    let deadline = Instant::now() + Duration::from_secs(5);
+    while Instant::now() < deadline {
+        if !wt.exists() {
+            break;
+        }
+        tokio::time::sleep(Duration::from_millis(100)).await;
+    }
+    assert!(
+        !wt.exists(),
+        "a cleared worktree must be removed after kill"
+    );
+    let registrations = git_worktree_list(base.path());
+    assert!(
+        !registrations.iter().any(|l| l.contains("feature/guard")),
+        "removal must deregister the tree: {registrations:?}"
+    );
+}
+
+/// #81/#88: commits that no remote has refuse the kill; `--force` ends the
+/// session anyway but LEAVES the worktree on disk — force never destroys
+/// blocked work.
+#[tokio::test(flavor = "multi_thread")]
+async fn unpushed_commits_block_kill_and_force_keeps_the_tree() {
+    let (_daemon, client) = bring_up().await;
+
+    let base = TempDir::new().unwrap();
+    init_repo(base.path());
+    let _origin = throwaway_origin(base.path());
+
+    let wt = base.path().join("worktrees").join("feature").join("local");
+    let s = client
+        .spawn_session(&worktree_req(base.path(), "feature/local", true))
+        .await
+        .expect("spawn");
+    std::fs::write(wt.join("README"), b"local only\n").unwrap();
+    commit_all(&wt, "not pushed yet");
+
+    // Refused: the commit is on no remote-tracking ref.
+    let err = client
+        .kill_session(s.id)
+        .await
+        .expect_err("kill must refuse");
+    match err {
+        maestro_e2e::ClientError::Api(maestro_protocol::ClientError::Api { info, .. }) => {
+            assert_eq!(info.code, "kill_guarded", "{info:?}");
+            let breakdown = info.unsaved_work.expect("breakdown on the wire");
+            assert_eq!(breakdown.unpushed_commits, 1);
+            assert_eq!(breakdown.uncommitted_files, 0);
+        }
+        other => panic!("expected a kill_guarded refusal, got {other:?}"),
+    }
+
+    // Force overrides the refusal and nothing else: session gone, tree kept.
+    client.kill_session_forced(s.id).await.expect("forced kill");
+
+    assert!(
+        !client
+            .list_sessions()
+            .await
+            .unwrap()
+            .iter()
+            .any(|x| x.id == s.id),
+        "the forced kill ends the session"
+    );
+    assert!(wt.is_dir(), "a guarded worktree must stay on disk");
+    assert!(
+        git_worktree_list(base.path())
+            .iter()
+            .any(|l| l.contains("feature/local")),
+        "the kept tree stays registered in git"
+    );
+}
+
+/// #82/#88: a session that exits on its own never reaches the kill path, but
+/// its worktree follows the same rule. Dirty: left on disk. Pristine:
+/// removed, leaving nothing behind.
+#[tokio::test(flavor = "multi_thread")]
+async fn natural_exit_settles_dirty_and_pristine_worktrees_differently() {
+    let (_daemon, client) = bring_up().await;
+
+    // Two repos so the two cases cannot see each other's state.
+    let dirty_repo = TempDir::new().unwrap();
+    init_repo(dirty_repo.path());
+    let _origin = throwaway_origin(dirty_repo.path());
+    let pristine_repo = TempDir::new().unwrap();
+    init_repo(pristine_repo.path());
+    let _origin_pristine = throwaway_origin(pristine_repo.path());
+
+    let dirty_wt = dirty_repo
+        .path()
+        .join("worktrees")
+        .join("feature")
+        .join("messy");
+    let pristine_wt = pristine_repo
+        .path()
+        .join("worktrees")
+        .join("feature")
+        .join("tidy");
+
+    let _dirty = client
+        .spawn_session(&CreateSessionRequest {
+            cwd: dirty_repo.path().to_path_buf(),
+            command: "sh -c 'echo unsaved > scratch.txt'".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(worktree_spec(dirty_repo.path(), "feature/messy", true)),
+        })
+        .await
+        .expect("spawn dirty");
+    let _pristine = client
+        .spawn_session(&create_req_cmd(
+            pristine_repo.path(),
+            "true",
+            "feature/tidy",
+        ))
+        .await
+        .expect("spawn pristine");
+
+    assert!(dirty_wt.is_dir() && pristine_wt.is_dir());
+
+    // The watcher reaps dead tmux sessions every couple of ticks and settles
+    // each worktree accordingly. Poll for both outcomes.
+    wait_for_async(
+        "pristine exit removes its worktree entirely",
+        Duration::from_secs(20),
+        || {
+            let repo = pristine_repo.path().to_path_buf();
+            let path = pristine_wt.clone();
+            async move {
+                if path.exists() {
+                    return false;
+                }
+                let registered = git_worktree_list(&repo);
+                !registered.iter().any(|l| l.contains("feature/tidy"))
+            }
+        },
+    )
+    .await;
+
+    // The dirty tree is still fully there, file included.
+    assert!(dirty_wt.is_dir());
+    assert_eq!(
+        std::fs::read(dirty_wt.join("scratch.txt")).unwrap(),
+        b"unsaved\n"
+    );
+}
+
+fn create_req_cmd(cwd: &std::path::Path, command: &str, branch: &str) -> CreateSessionRequest {
+    CreateSessionRequest {
+        cwd: cwd.to_path_buf(),
+        command: command.into(),
+        env: HashMap::new(),
+        metadata: HashMap::new(),
+        worktree: Some(worktree_spec(cwd, branch, true)),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// GET /api/projects + /api/branches (#54/#55/#66)
+// ---------------------------------------------------------------------------
+
+/// #66: two repos under a configured `[spawn].project_roots` root are both
+/// discovered by `GET /api/projects`; git activity gives every repo a
+/// `last_activity`, and spawning inside one merges its command into the
+/// project entry via spawn history.
+#[tokio::test(flavor = "multi_thread")]
+async fn projects_endpoint_discovers_roots_and_merges_activity() {
+    let root = TempDir::new().unwrap();
+    let alpha = make_repo(root.path(), "alpha");
+    make_repo(root.path(), "beta");
+
+    let daemon = Daemon::spawn_with_config(&format!(
+        "[spawn]\nproject_roots = [\"{}\"]\nproject_scan_depth = 2\n",
+        root.path().display()
+    ))
+    .await;
+    let client = TestClient::new(&daemon.http_base());
+
+    let projects = client.list_projects().await.expect("list projects");
+    let names: Vec<&str> = projects.iter().map(|p| p.name.as_str()).collect();
+    assert!(
+        names.contains(&"alpha") && names.contains(&"beta"),
+        "both repos must be discovered, got: {names:?}"
+    );
+
+    let find = |name: &str| {
+        projects
+            .iter()
+            .find(|p| p.name == name)
+            .cloned()
+            .expect("project present")
+    };
+    // Both have commits, so git activity alone populates last_activity…
+    assert!(
+        find("alpha").last_activity.is_some(),
+        "git activity must surface"
+    );
+    assert!(
+        find("beta").last_activity.is_some(),
+        "git activity must surface"
+    );
+    // …and neither has been spawned into yet.
+    assert_eq!(find("alpha").last_command, None);
+    assert_eq!(find("beta").last_command, None);
+
+    // Spawning inside alpha writes durable history; /api/projects folds it in.
+    let s = client
+        .spawn_session(&create_req(&alpha, "sleep 30"))
+        .await
+        .expect("spawn in alpha");
+
+    wait_for_async(
+        "alpha's project entry reflects spawn history",
+        Duration::from_secs(5),
+        || {
+            let client = client.clone();
+            async move {
+                client
+                    .list_projects()
+                    .await
+                    .ok()
+                    .map(|ps| {
+                        ps.iter()
+                            .find(|p| p.name == "alpha")
+                            .map(|p| p.last_command.as_deref() == Some("sleep 30"))
+                            .unwrap_or(false)
+                    })
+                    .unwrap_or(false)
+            }
+        },
+    )
+    .await;
+
+    // beta was never spawned into: no command recorded there.
+    let beta_after = client
+        .list_projects()
+        .await
+        .expect("list after spawn")
+        .into_iter()
+        .find(|p| p.name == "beta")
+        .unwrap();
+    assert_eq!(beta_after.last_command, None);
+
+    client.kill_session(s.id).await.expect("kill");
+}
+
+/// #66: `GET /api/branches` lists every local branch, flags the main
+/// checkout's HEAD with `is_head`, and reports which linked worktree holds an
+/// occupied branch.
+#[tokio::test(flavor = "multi_thread")]
+async fn branches_endpoint_lists_branches_and_flags_occupied() {
+    let (_daemon, client) = bring_up().await;
+
+    let base = TempDir::new().unwrap();
+    init_repo(base.path());
+    run_git(&["branch", "feature/taken"], base.path());
+    run_git(&["branch", "feature/free"], base.path());
+    let holder = base.path().join("holder-wt");
+    run_git(
+        &[
+            "worktree",
+            "add",
+            "-q",
+            &holder.to_string_lossy(),
+            "feature/taken",
+        ],
+        base.path(),
+    );
+
+    let branches = client
+        .list_branches(&base.path().to_string_lossy())
+        .await
+        .expect("list branches");
+    let by_name = |name: &str| {
+        branches
+            .iter()
+            .find(|b| b.name == name)
+            .cloned()
+            .unwrap_or_else(|| panic!("branch {name} missing from {branches:?}"))
+    };
+
+    let main = by_name("main");
+    assert!(main.is_head, "main is the main checkout's HEAD");
+    assert_eq!(main.worktree, None);
+
+    let taken = by_name("feature/taken");
+    assert!(!taken.is_head);
+    assert_eq!(
+        taken.worktree.as_deref(),
+        Some(holder.canonicalize().unwrap().as_path()),
+        "occupied branch must report its holding worktree"
+    );
+
+    let free = by_name("feature/free");
+    assert!(!free.is_head);
+    assert_eq!(free.worktree, None, "unoccupied branch must be spawnable");
+}
+
 #[tokio::test(flavor = "multi_thread")]
 async fn daemon_restart_recovers_session() {
     let (mut daemon, client) = bring_up().await;
@@ -230,7 +970,6 @@ async fn spawn_records_history_and_infers_gitroot_for_form() {
     // (#27's recents picker), and gitroot infers the worktree base_repo from the
     // same dir. Exercised end to end against real tmux + git.
     let (daemon, client) = bring_up().await;
-    let daemon_base = daemon.http_base();
 
     // A git repo as the working dir, so gitroot has a repo to infer.
     let repo = TempDir::new().unwrap();
@@ -250,16 +989,11 @@ async fn spawn_records_history_and_infers_gitroot_for_form() {
         "recent-dirs surfaces the spawned cwd",
         Duration::from_secs(5),
         || {
-            let url = format!("{daemon_base}/api/recent-dirs");
+            let client = daemon.client();
             let want = cwd.clone();
             async move {
-                let resp = match reqwest::get(&url).await {
-                    Ok(r) => r,
-                    Err(_) => return false,
-                };
-                let recents: maestro_protocol::RecentDirs = match resp.json().await {
-                    Ok(v) => v,
-                    Err(_) => return false,
+                let Ok(recents) = client.recent_dirs().await else {
+                    return false;
                 };
                 recents
                     .dirs
@@ -272,15 +1006,7 @@ async fn spawn_records_history_and_infers_gitroot_for_form() {
 
     // gitroot infers the worktree base_repo from the same dir (#25/#26): the dir
     // is itself the repo toplevel (it holds `.git`).
-    let gr: maestro_protocol::GitRoot = reqwest::Client::new()
-        .get(format!("{daemon_base}/api/gitroot"))
-        .query(&[("path", cwd.as_str())])
-        .send()
-        .await
-        .expect("gitroot request")
-        .json()
-        .await
-        .expect("gitroot json");
+    let gr = daemon.client().git_root(&cwd).await.expect("gitroot");
     assert_eq!(
         gr.root.as_deref().map(|p| p.to_string_lossy().to_string()),
         Some(cwd.clone()),
@@ -362,6 +1088,15 @@ fn init_repo(dir: &std::path::Path) {
     run_git(&["commit", "-q", "-m", "initial"], dir);
 }
 
+/// Real git repo at `<root>/<name>`, canonicalized (the scanner canonicalizes
+/// discovered paths too, so comparisons must agree on the real path).
+fn make_repo(root: &std::path::Path, name: &str) -> std::path::PathBuf {
+    let dir = root.join(name);
+    std::fs::create_dir_all(&dir).unwrap();
+    init_repo(&dir);
+    dir.canonicalize().unwrap()
+}
+
 fn run_git(args: &[&str], cwd: &std::path::Path) {
     let out = Command::new("git")
         .arg("-C")
@@ -389,6 +1124,36 @@ fn git_worktree_list(dir: &std::path::Path) -> Vec<String> {
         .collect()
 }
 
+/// Bare remote registered as `origin` on `repo`, seeded with every current
+/// branch, so existing commits are reachable from remote-tracking refs.
+/// Without one the kill guard (#79) reads every commit as unpushed, and any
+/// worktree session refuses to die. The caller must keep the `TempDir` alive
+/// while the remote is still needed; later pushes go through [`push_all`].
+fn throwaway_origin(repo: &std::path::Path) -> TempDir {
+    let origin = tempfile::TempDir::new().unwrap();
+    run_git(
+        &["init", "-q", "--bare", origin.path().to_str().unwrap()],
+        repo,
+    );
+    let _ = Command::new("git")
+        .arg("-C")
+        .arg(repo)
+        .args(["remote", "add", "origin", origin.path().to_str().unwrap()])
+        .output()
+        .expect("git remote add");
+    push_all(repo);
+    origin
+}
+
+fn push_all(repo: &std::path::Path) {
+    run_git(&["push", "-q", "--all", "origin"], repo);
+}
+
+fn commit_all(dir: &std::path::Path, message: &str) {
+    run_git(&["add", "-A"], dir);
+    run_git(&["commit", "-q", "-m", message], dir);
+}
+
 #[tokio::test(flavor = "multi_thread")]
 async fn daemon_events_ws_streams_snapshot_then_session_added() {
     // NAP-248: subscribe to the daemon's WS /api/events, expect an initial
@@ -396,7 +1161,7 @@ async fn daemon_events_ws_streams_snapshot_then_session_added() {
     let (daemon, client) = bring_up().await;
     let cwd = TempDir::new().unwrap();
 
-    let ws_url = format!("{}/api/events", daemon.ws_base());
+    let ws_url = daemon.client().events_url().unwrap();
     let (mut ws, _) = tokio_tungstenite::connect_async(ws_url)
         .await
         .expect("events WS handshake");
@@ -459,14 +1224,13 @@ fn run_cli(args: &[&str], envs: &[(&str, &str)]) -> std::process::Output {
 
 #[tokio::test(flavor = "multi_thread")]
 async fn cli_list_reads_from_daemon() {
-    let (daemon, client) = bring_up().await;
-    let cwd = TempDir::new().unwrap();
-    let session = client
-        .spawn_session(&create_req(cwd.path(), "sleep 30"))
-        .await
-        .expect("spawn");
+    // The subject is the shipped `maestro` binary — arg parsing, config
+    // precedence, output. It needs a daemon to talk to, not tmux, so this runs
+    // against an in-memory one.
+    let mock = maestro_testing::MockDaemon::start().await;
+    let id = uuid::Uuid::new_v4();
+    mock.add_session(maestro_testing::session(id, "/home/mock/work", "sleep 30"));
 
-    let daemon_url = daemon.http_base();
     let home = TempDir::new().unwrap();
     let cfg_path = home.path().join("config.toml");
     let out = run_cli(
@@ -474,18 +1238,16 @@ async fn cli_list_reads_from_daemon() {
         &[
             ("HOME", home.path().to_str().unwrap()),
             ("MAESTRO_CONFIG", cfg_path.to_str().unwrap()),
-            ("MAESTRO_DAEMON_URL", &daemon_url),
+            ("MAESTRO_DAEMON_URL", &mock.http_base()),
         ],
     );
     let stdout = String::from_utf8_lossy(&out.stdout);
     let stderr = String::from_utf8_lossy(&out.stderr);
     assert!(out.status.success(), "list failed: {stderr}\n{stdout}");
     assert!(
-        stdout.contains(&session.id.to_string()),
+        stdout.contains(&id.to_string()),
         "session not listed: {stdout}"
     );
-
-    client.kill_session(session.id).await.ok();
 }
 
 #[tokio::test(flavor = "multi_thread")]

crates/maestro-e2e/tests/tui_integration.rs

@@ -1,144 +0,0 @@
-//! TUI integration tests (NAP-282).
-//!
-//! Exercises `CatalogStore` and the per-session `SessionTask` against a real
-//! daemon subprocess. We don't spin the full ratatui frontend
-//! here — those interactions are best tested with `TestBackend` unit tests in
-//! `crates/maestro-tui/src/*.rs`. This file fills the gap between those
-//! and the headless e2e suite by verifying that the TUI's wire layer plays
-//! nicely with a real daemon.
-//!
-//! Requires `tmux` and `git` on `$PATH`.
-
-#![allow(clippy::result_large_err)]
-
-use std::path::PathBuf;
-use std::time::{Duration, Instant};
-
-use maestro_e2e::Daemon;
-use maestro_protocol::CreateSessionRequest;
-use maestro_tui::catalog::CatalogStore;
-
-async fn wait_until<F, Fut>(label: &str, deadline: Duration, mut check: F)
-where
-    F: FnMut() -> Fut,
-    Fut: std::future::Future<Output = bool>,
-{
-    let start = Instant::now();
-    loop {
-        if check().await {
-            return;
-        }
-        if start.elapsed() >= deadline {
-            panic!("timeout waiting for {label}");
-        }
-        tokio::time::sleep(Duration::from_millis(25)).await;
-    }
-}
-
-#[tokio::test(flavor = "multi_thread")]
-async fn catalog_bootstrap_against_real_daemon() {
-    let daemon = Daemon::spawn().await;
-    let ws_url = format!("{}/api/events", daemon.ws_base());
-
-    let store = CatalogStore::default();
-    let bg = store.clone();
-    tokio::spawn(async move { bg.run_events_loop(ws_url).await });
-
-    tokio::time::timeout(Duration::from_secs(3), store.wait_for_initial_snapshot())
-        .await
-        .expect("initial snapshot");
-
-    assert!(store.snapshot().sessions.is_empty());
-}
-
-#[tokio::test(flavor = "multi_thread")]
-async fn post_session_propagates_through_events_ws() {
-    let daemon = Daemon::spawn().await;
-    let ws_url = format!("{}/api/events", daemon.ws_base());
-    let http_base = daemon.http_base();
-
-    let store = CatalogStore::default();
-    let bg = store.clone();
-    tokio::spawn(async move { bg.run_events_loop(ws_url).await });
-
-    tokio::time::timeout(Duration::from_secs(3), store.wait_for_initial_snapshot())
-        .await
-        .expect("initial snapshot");
-
-    let cwd = PathBuf::from(daemon.home());
-    let req = CreateSessionRequest {
-        cwd,
-        command: "bash".into(),
-        env: Default::default(),
-        metadata: Default::default(),
-        worktree: None,
-    };
-    let res = reqwest::Client::new()
-        .post(format!("{http_base}/api/sessions"))
-        .json(&req)
-        .send()
-        .await
-        .expect("post sessions");
-    assert!(res.status().is_success(), "POST /api/sessions: {res:?}");
-
-    wait_until(
-        "session to surface in catalog",
-        Duration::from_secs(2),
-        || async { store.snapshot().sessions.len() == 1 },
-    )
-    .await;
-
-    let snap = store.snapshot();
-    assert_eq!(snap.sessions.len(), 1);
-    assert_eq!(snap.sessions[0].command, "bash");
-}
-
-#[tokio::test(flavor = "multi_thread")]
-async fn delete_session_propagates_removal() {
-    let daemon = Daemon::spawn().await;
-    let ws_url = format!("{}/api/events", daemon.ws_base());
-    let http_base = daemon.http_base();
-
-    let store = CatalogStore::default();
-    let bg = store.clone();
-    tokio::spawn(async move { bg.run_events_loop(ws_url).await });
-
-    tokio::time::timeout(Duration::from_secs(3), store.wait_for_initial_snapshot())
-        .await
-        .expect("initial snapshot");
-
-    let cwd = PathBuf::from(daemon.home());
-    let req = CreateSessionRequest {
-        cwd,
-        command: "bash".into(),
-        env: Default::default(),
-        metadata: Default::default(),
-        worktree: None,
-    };
-    let client = reqwest::Client::new();
-    let res = client
-        .post(format!("{http_base}/api/sessions"))
-        .json(&req)
-        .send()
-        .await
-        .unwrap();
-    assert!(res.status().is_success());
-
-    wait_until("creation", Duration::from_secs(2), || async {
-        store.snapshot().sessions.len() == 1
-    })
-    .await;
-
-    let sid = store.snapshot().sessions[0].id;
-    let res = client
-        .delete(format!("{http_base}/api/sessions/{sid}"))
-        .send()
-        .await
-        .unwrap();
-    assert!(res.status().is_success(), "DELETE /api/sessions: {res:?}");
-
-    wait_until("removal", Duration::from_secs(2), || async {
-        store.snapshot().sessions.is_empty()
-    })
-    .await;
-}

crates/maestro-hooks/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "maestro-hooks"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+publish.workspace = true
+description = "Agent activity hooks (#106): shipped script + idempotent settings.json installer"
+
+[dependencies]
+serde_json.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true

crates/maestro-hooks/src/lib.rs

@@ -0,0 +1,261 @@
+//! Claude Code activity hook (#106).
+//!
+//! Two halves, both shared by the `maestro hooks install` CLI subcommand and
+//! the daemon's first-start auto-install:
+//!
+//! * [`HOOK_SCRIPT`] — the hook itself, written to disk at install time. It
+//!   posts an [`ActivityState`](maestro-protocol) to
+//!   `$MAESTRO_URL/api/sessions/$MAESTRO_SESSION_ID/activity` (#105). The same
+//!   global hook runs in every Claude Code session on the machine, so it exits
+//!   0 and silently when either #103 env var is unset, and it never lets a
+//!   daemon failure escape (short curl timeout, status ignored).
+//! * [`install`] — idempotent registration of that script in
+//!   `~/.claude/settings.json`. Only entries maestro itself wrote (identified
+//!   by [`HOOK_MARKER`]) are touched; every other hook and every other field
+//!   in the file is preserved verbatim.
+
+use std::path::Path;
+
+/// Marker substring every maestro-installed hook command carries. The
+/// installer rewrites or removes exactly these entries — nothing else in the
+/// user's settings file.
+pub const HOOK_MARKER: &str = "maestro-claude-hook";
+
+/// File name of the installed script (carries [`HOOK_MARKER`]).
+pub const SCRIPT_FILE_NAME: &str = "maestro-claude-hook.sh";
+
+/// Claude Code hook event → `ActivityState` spelling posted to the daemon.
+///
+/// `PreToolUse` is what makes a session `Active` *during* a long tool call —
+/// `PostToolUse` alone only fires once it ends (#114). `StopFailure` is
+/// Claude Code's own name for "the turn ended on an API error"; there is no
+/// failure signal in `Stop` or `SessionEnd` payloads, so those never report
+/// `Error`.
+pub const HOOK_EVENTS: [(&str, &str); 5] = [
+    // Tool starting: the agent is demonstrably producing work, even if the
+    // tool itself runs for minutes.
+    ("PreToolUse", "Active"),
+    // Tool finished successfully.
+    ("PostToolUse", "Active"),
+    // Permission / idle notices: Claude is blocked on the user.
+    ("Notification", "AwaitingInput"),
+    // Turn ended: waiting on the user again.
+    ("Stop", "AwaitingInput"),
+    // Turn ended on an API error; the payload's `error` field is forwarded
+    // as the report's `detail` (#114).
+    ("StopFailure", "Error"),
+];
+
+/// The shipped hook script. POSIX sh so any `/bin/sh` works.
+pub const HOOK_SCRIPT: &str = r#"#!/bin/sh
+# Installed by maestro (#106): report Claude Code activity to its daemon.
+# Exits silently unless running inside a session maestro spawned (#103 env).
+# Event -> ActivityState mapping:
+#   PreToolUse    -> Active         (tool started; agent is working)
+#   PostToolUse   -> Active         (tool finished)
+#   Notification  -> AwaitingInput  (permission / idle notice)
+#   Stop          -> AwaitingInput  (turn ended; waiting on the user)
+#   StopFailure   -> Error          (turn ended on an API error)
+state="$1"
+[ -n "$MAESTRO_SESSION_ID" ] || exit 0
+[ -n "$MAESTRO_URL" ] || exit 0
+payload=$(cat 2>/dev/null) || true
+body="{\"state\":\"$state\"}"
+# StopFailure payloads carry the outcome in "error". Only a plain enum
+# spelling is reported as the detail — anything else (quotes, backslashes,
+# prose) would risk breaking the JSON body, and the spelling already names
+# the failure.
+detail=$(printf '%s' "$payload" | sed -n 's/.*"error"[[:space:]]*:[[:space:]]*"\([a-z_]*\)".*/\1/p')
+if [ -n "$detail" ]; then
+    body="{\"state\":\"$state\",\"detail\":\"$detail\"}"
+fi
+curl -fsS --connect-timeout 1 --max-time 2 \
+    -H 'Content-Type: application/json' \
+    -d "$body" \
+    "$MAESTRO_URL/api/sessions/$MAESTRO_SESSION_ID/activity" \
+    >/dev/null 2>&1 || true
+exit 0
+"#;
+
+#[derive(Debug, thiserror::Error)]
+pub enum HooksError {
+    #[error("io: {0}")]
+    Io(#[from] std::io::Error),
+    #[error("json: {0}")]
+    Json(#[from] serde_json::Error),
+}
+
+/// Where the script is written for a given home directory:
+/// `<home>/.local/share/maestro/maestro-claude-hook.sh`.
+pub fn script_path(home: &Path) -> std::path::PathBuf {
+    home.join(".local/share/maestro").join(SCRIPT_FILE_NAME)
+}
+
+/// The user-level Claude Code settings file for a given home directory.
+pub fn settings_path(home: &Path) -> std::path::PathBuf {
+    home.join(".claude/settings.json")
+}
+
+/// Whether `settings_path` already carries a maestro hook (#106).
+pub fn is_installed(settings_path: &Path) -> bool {
+    settings_json(settings_path)
+        .map(|root| find_maestro_commands(&root).next().is_some())
+        .unwrap_or(false)
+}
+
+/// Write [`HOOK_SCRIPT`] to `path`, executable. Parent directories are
+/// created as needed — this is always under the caller's chosen data dir,
+/// never inside a repository.
+pub fn write_script(path: &Path) -> Result<(), HooksError> {
+    if let Some(dir) = path.parent() {
+        std::fs::create_dir_all(dir)?;
+    }
+    std::fs::write(path, HOOK_SCRIPT)?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let mut perms = std::fs::metadata(path)?.permissions();
+        perms.set_mode(0o755);
+        std::fs::set_permissions(path, perms)?;
+    }
+    Ok(())
+}
+
+/// Install the full hook setup for `home`: write the script under
+/// `.local/share/maestro/` and register it in `.claude/settings.json`.
+/// Idempotent; returns whether anything changed on disk.
+pub fn install_for_home(home: &Path) -> Result<bool, HooksError> {
+    let script = script_path(home);
+    let settings = settings_path(home);
+    let before = std::fs::read_to_string(&settings).unwrap_or_default();
+    write_script(&script)?;
+    install(&settings, &script)?;
+    let after = std::fs::read_to_string(&settings).unwrap_or_default();
+    Ok(before != after)
+}
+
+/// Register the hook command for every event in [`HOOK_EVENTS`] in the
+/// settings file at `settings_path`. Idempotent: existing maestro entries are
+/// updated in place wherever they sit, stale ones removed, duplicates folded;
+/// every non-maestro entry and every unrelated top-level field survives.
+///
+/// Never inspects or writes anywhere but `settings_path` — callers pass the
+/// user's real home or a temp one in tests, never a repository.
+pub fn install(settings_path: &Path, script_path: &Path) -> Result<(), HooksError> {
+    let mut root = settings_json(settings_path)?;
+
+    // Strip every maestro entry wherever it currently sits, so an older
+    // install under different events is replaced rather than duplicated.
+    strip_maestro_entries(&mut root);
+
+    let hooks = ensure_object(&mut root, "hooks");
+    for (event, state) in HOOK_EVENTS {
+        let groups = ensure_array(hooks, event);
+        let mut group = serde_json::Map::new();
+        group.insert(
+            "hooks".into(),
+            serde_json::json!([{
+                "type": "command",
+                "command": format!("{} {state}", script_path.display()),
+            }]),
+        );
+        groups.push(serde_json::Value::Object(group));
+    }
+
+    write_atomic(settings_path, &root)
+}
+
+fn settings_json(path: &Path) -> Result<serde_json::Value, HooksError> {
+    match std::fs::read_to_string(path) {
+        Ok(s) => Ok(serde_json::from_str(&s)?),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+            Ok(serde_json::Value::Object(Default::default()))
+        }
+        Err(e) => Err(e.into()),
+    }
+}
+
+/// Every command string in the file belonging to a maestro hook.
+fn find_maestro_commands(root: &serde_json::Value) -> impl Iterator<Item = &str> {
+    root.get("hooks")
+        .and_then(|h| h.as_object())
+        .into_iter()
+        .flat_map(|events| events.values())
+        .filter_map(|groups| groups.as_array())
+        .flatten()
+        .filter_map(|group| group.get("hooks"))
+        .filter_map(|inner| inner.as_array())
+        .flatten()
+        .filter_map(|hook| hook.get("command"))
+        .filter_map(|cmd| cmd.as_str())
+        .filter(|cmd| cmd.contains(HOOK_MARKER))
+}
+
+/// Remove all maestro inner-hook entries from every event group, dropping
+/// groups left empty. Non-maestro siblings survive untouched.
+fn strip_maestro_entries(root: &mut serde_json::Value) {
+    let Some(events) = root.get_mut("hooks").and_then(|h| h.as_object_mut()) else {
+        return;
+    };
+    for (_, groups) in events.iter_mut() {
+        let Some(list) = groups.as_array_mut() else {
+            continue;
+        };
+        for group in list.iter_mut() {
+            let Some(inner) = group.get_mut("hooks").and_then(|h| h.as_array_mut()) else {
+                continue;
+            };
+            inner.retain(|hook| {
+                !hook
+                    .get("command")
+                    .and_then(|c| c.as_str())
+                    .is_some_and(|c| c.contains(HOOK_MARKER))
+            });
+        }
+        list.retain(|group| {
+            group
+                .get("hooks")
+                .and_then(|h| h.as_array())
+                .is_some_and(|h| !h.is_empty())
+        });
+    }
+    // An event left with no groups at all (ours emptied it, or the user's
+    // file carried an empty list) reads better gone.
+    events.retain(|_, groups| groups.as_array().is_some_and(|g| !g.is_empty()));
+}
+
+fn ensure_object<'a>(
+    root: &'a mut serde_json::Value,
+    key: &str,
+) -> &'a mut serde_json::Map<String, serde_json::Value> {
+    if !root.get(key).map(|v| v.is_object()).unwrap_or(false) {
+        root[key] = serde_json::json!({});
+    }
+    root.get_mut(key).unwrap().as_object_mut().unwrap()
+}
+
+fn ensure_array<'a>(
+    parent: &'a mut serde_json::Map<String, serde_json::Value>,
+    key: &str,
+) -> &'a mut Vec<serde_json::Value> {
+    let v = parent
+        .entry(key.to_string())
+        .or_insert_with(|| serde_json::json!([]));
+    if !v.is_array() {
+        *v = serde_json::json!([]);
+    }
+    v.as_array_mut().unwrap()
+}
+
+fn write_atomic(path: &Path, value: &serde_json::Value) -> Result<(), HooksError> {
+    if let Some(dir) = path.parent() {
+        std::fs::create_dir_all(dir)?;
+    }
+    let tmp = path.with_extension("json.maestro-tmp");
+    std::fs::write(&tmp, serde_json::to_string_pretty(value)? + "\n")?;
+    std::fs::rename(&tmp, path)?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests;

crates/maestro-hooks/src/tests.rs

@@ -0,0 +1,340 @@
+//! Tests for the shipped hook script (run as a real `/bin/sh` subprocess)
+//! and the settings-file installer. Everything happens under a temp `$HOME`;
+//! the developer's own `~/.claude/settings.json` is never touched.
+
+use std::io::{Read, Write};
+use std::process::{Command, Stdio};
+
+use super::*;
+
+fn sh(script: &str, args: &[&str], envs: &[(&str, &str)], payload: &[u8]) -> std::process::Output {
+    let mut cmd = Command::new("/bin/sh");
+    // `sh -c CMD NAME ARGS…`: NAME fills $0, so the real arguments start at $1.
+    let mut argv = vec!["-c", script, HOOK_MARKER];
+    argv.extend(args.iter().copied());
+    cmd.args(&argv);
+    // A clean env: only what the test passes, plus PATH so curl can spawn.
+    cmd.env_clear();
+    cmd.env("PATH", std::env::var("PATH").unwrap_or_default());
+    for (k, v) in envs {
+        cmd.env(k, v);
+    }
+    let mut child = cmd
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .expect("spawn /bin/sh");
+    // Feed a Claude-Code-style payload on stdin; the script must drain it.
+    child.stdin.take().unwrap().write_all(payload).ok();
+    child.wait_with_output().expect("wait")
+}
+
+const SESSION: &str = "01234567-89ab-cdef-0123-456789abcdef";
+
+/// Accept exactly one HTTP request on a throwaway listener, answer 204, and
+/// hand back the raw request text. Runs `run` with the base URL once the
+/// acceptor thread is in place.
+fn capture_request(run: impl FnOnce(String) -> std::process::Output) -> String {
+    let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+    let addr = listener.local_addr().unwrap();
+    let handle = std::thread::spawn(move || {
+        let (mut sock, _) = listener.accept().unwrap();
+        let mut buf = [0u8; 4096];
+        let n = sock.read(&mut buf).unwrap();
+        sock.write_all(b"HTTP/1.1 204 No Content\r\nContent-Length: 0\r\n\r\n")
+            .unwrap();
+        String::from_utf8_lossy(&buf[..n]).to_string()
+    });
+    let out = run(format!("http://{addr}"));
+    assert!(out.status.success(), "{:?}", out.stderr);
+    handle.join().unwrap()
+}
+
+fn session_envs(url: &str) -> Vec<(&'static str, String)> {
+    vec![
+        ("MAESTRO_URL", url.to_string()),
+        ("MAESTRO_SESSION_ID", SESSION.to_string()),
+    ]
+}
+
+fn owned_envs<'a>(envs: &'a [(&'static str, String)]) -> Vec<(&'static str, &'a str)> {
+    envs.iter().map(|(k, v)| (*k, v.as_str())).collect()
+}
+
+/// The hook must be invisible outside maestro: no env vars (#103 unset) ⇒
+/// exit 0, no output, stdin drained.
+#[test]
+fn script_exits_silently_without_maestro_env() {
+    for (event, _) in HOOK_EVENTS {
+        let out = sh(HOOK_SCRIPT, &[event], &[], br#"{"session_id":"x"}"#);
+        assert!(out.status.success(), "{event:?}: {:?}", out.stderr);
+        assert!(out.stdout.is_empty(), "{event:?}: {:?}", out.stdout);
+        assert!(out.stderr.is_empty(), "{event:?}: {:?}", out.stderr);
+    }
+}
+
+/// With both env vars set the script POSTs the mapped state to the daemon's
+/// activity endpoint and still exits 0.
+#[test]
+fn script_posts_mapped_state_to_the_activity_endpoint() {
+    // The installer bakes the mapped state into the command's argv; the
+    // script relays whatever it is given.
+    let request = capture_request(|url| {
+        sh(
+            HOOK_SCRIPT,
+            &["Active"],
+            &owned_envs(&session_envs(&url)),
+            br#"{"session_id":"x"}"#,
+        )
+    });
+    assert!(request.starts_with("POST "), "{request}");
+    assert!(
+        request.contains(&format!("/api/sessions/{SESSION}/activity")),
+        "{request}"
+    );
+    assert!(request.contains(r#""state":"Active""#), "{request}");
+}
+
+/// Every event maps to the state the contract specifies.
+#[test]
+fn event_state_mapping_matches_the_contract() {
+    let map: std::collections::HashMap<&str, &str> = HOOK_EVENTS.into_iter().collect();
+    assert_eq!(map["PreToolUse"], "Active");
+    assert_eq!(map["PostToolUse"], "Active");
+    assert_eq!(map["Notification"], "AwaitingInput");
+    assert_eq!(map["Stop"], "AwaitingInput");
+    assert_eq!(map["StopFailure"], "Error");
+}
+
+/// A `StopFailure` payload names the API error that ended the turn; the
+/// script reports its `error` spelling as the report's `detail` so a card
+/// can show why (#114).
+#[test]
+fn script_reports_the_error_spelling_as_detail() {
+    let request = capture_request(|url| {
+        sh(
+            HOOK_SCRIPT,
+            &["Error"],
+            &owned_envs(&session_envs(&url)),
+            br#"{"session_id":"abc","hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"}"#,
+        )
+    });
+    assert!(request.contains(r#""state":"Error""#), "{request}");
+    assert!(request.contains(r#""detail":"rate_limit""#), "{request}");
+}
+
+/// An `error` value that is not a plain enum spelling (or a payload without
+/// one at all) must never produce a broken body — no detail is posted.
+#[test]
+fn script_posts_no_detail_for_an_unexpected_error_value() {
+    let request = capture_request(|url| {
+        sh(
+            HOOK_SCRIPT,
+            &["Error"],
+            &owned_envs(&session_envs(&url)),
+            br#"{"hook_event_name":"StopFailure","error":"429 \"Too Many\" \\ requests"}"#,
+        )
+    });
+    assert!(request.contains(r#""state":"Error""#), "{request}");
+    assert!(!request.contains("detail"), "{request}");
+}
+
+/// Events whose payload carries no error fields post a bare body — never an
+/// empty or stale detail.
+#[test]
+fn script_posts_no_detail_for_events_without_an_error() {
+    let request = capture_request(|url| {
+        sh(
+            HOOK_SCRIPT,
+            &["AwaitingInput"],
+            &owned_envs(&session_envs(&url)),
+            br#"{"hook_event_name":"Stop","stop_hook_active":false}"#,
+        )
+    });
+    assert!(request.contains(r#""state":"AwaitingInput""#), "{request}");
+    assert!(!request.contains("detail"), "{request}");
+}
+
+/// A dead or unreachable daemon must never fail — or slow down — a session.
+#[test]
+fn script_ignores_daemon_failure() {
+    // Port 1 on localhost is closed in practice; curl fails fast.
+    let out = sh(
+        HOOK_SCRIPT,
+        &["Stop"],
+        &[
+            ("MAESTRO_URL", "http://127.0.0.1:1"),
+            ("MAESTRO_SESSION_ID", "00000000-0000-0000-0000-000000000000"),
+        ],
+        br#"{"session_id":"x"}"#,
+    );
+    assert!(out.status.success());
+}
+
+// --- installer -------------------------------------------------------------
+
+fn installed_commands(settings: &Path) -> Vec<String> {
+    serde_json::from_str::<serde_json::Value>(&std::fs::read_to_string(settings).unwrap())
+        .unwrap()
+        .get("hooks")
+        .and_then(|h| h.as_object())
+        .into_iter()
+        .flat_map(|events| events.values())
+        .filter_map(|g| g.as_array())
+        .flatten()
+        .filter_map(|g| g.get("hooks"))
+        .filter_map(|h| h.as_array())
+        .flatten()
+        .filter_map(|h| h.get("command"))
+        .filter_map(|c| c.as_str())
+        .map(str::to_string)
+        .collect()
+}
+
+/// Fresh install registers exactly one command per event, all pointing at the
+/// script with the right state argument.
+#[test]
+fn fresh_install_registers_every_event() {
+    let dir = tempfile::tempdir().unwrap();
+    let home = dir.path();
+    write_script(&script_path(home)).unwrap();
+    install(&settings_path(home), &script_path(home)).unwrap();
+
+    let cmds = installed_commands(&settings_path(home));
+    assert_eq!(cmds.len(), HOOK_EVENTS.len());
+    let joined = cmds.join("\n");
+    assert_eq!(joined.matches("Active").count(), 2);
+    assert!(joined.contains("Error"));
+    assert_eq!(joined.matches("AwaitingInput").count(), 2);
+    for cmd in &cmds {
+        assert!(cmd.contains(SCRIPT_FILE_NAME));
+    }
+}
+
+/// Running install twice changes nothing further — no duplicates.
+#[test]
+fn install_is_idempotent() {
+    let dir = tempfile::tempdir().unwrap();
+    let home = dir.path();
+    install(&settings_path(home), &script_path(home)).unwrap();
+    let once = std::fs::read_to_string(settings_path(home)).unwrap();
+
+    install(&settings_path(home), &script_path(home)).unwrap();
+    let twice = std::fs::read_to_string(settings_path(home)).unwrap();
+    assert_eq!(once, twice);
+    assert_eq!(
+        installed_commands(&settings_path(home)).len(),
+        HOOK_EVENTS.len()
+    );
+}
+
+/// An older maestro entry under the same events is updated in place, not
+/// duplicated next to the new one.
+#[test]
+fn install_updates_an_older_maestro_hook_in_place() {
+    let dir = tempfile::tempdir().unwrap();
+    let settings = dir.path().join(".claude/settings.json");
+    std::fs::create_dir_all(settings.parent().unwrap()).unwrap();
+    let old_script = "/old/location/maestro-claude-hook.sh Active";
+    std::fs::write(
+        &settings,
+        serde_json::json!({
+            "model": "sonnet",
+            "hooks": {
+                "Stop": [{"hooks": [{"type": "command", "command": old_script}]}],
+            },
+        })
+        .to_string(),
+    )
+    .unwrap();
+
+    let new_script = dir
+        .path()
+        .join(".local/share/maestro")
+        .join(SCRIPT_FILE_NAME);
+    install(&settings, &new_script).unwrap();
+
+    let cmds = installed_commands(&settings);
+    assert_eq!(
+        cmds.len(),
+        HOOK_EVENTS.len(),
+        "old entry replaced, not kept: {cmds:?}"
+    );
+    assert!(!cmds.iter().any(|c| c == old_script));
+    let root: serde_json::Value =
+        serde_json::from_str(&std::fs::read_to_string(&settings).unwrap()).unwrap();
+    assert_eq!(root["model"], "sonnet", "unrelated fields survive");
+}
+
+/// A stale maestro entry under an event we no longer use is cleaned up too;
+/// the user's own hooks are never touched.
+#[test]
+fn install_preserves_foreign_hooks_and_removes_stale_maestro_ones() {
+    let dir = tempfile::tempdir().unwrap();
+    let settings = dir.path().join(".claude/settings.json");
+    std::fs::create_dir_all(settings.parent().unwrap()).unwrap();
+    std::fs::write(
+        &settings,
+        serde_json::json!({
+            "hooks": {
+                "PreToolUse": [{"matcher": "Bash", "hooks": [
+                    {"type": "command", "command": "my-own-linter.sh"},
+                ]}],
+                "UserPromptSubmit": [{"hooks": [
+                    {"type": "command", "command": "/old/maestro-claude-hook.sh Active"},
+                ]}],
+            },
+        })
+        .to_string(),
+    )
+    .unwrap();
+
+    let new_script = dir
+        .path()
+        .join(".local/share/maestro")
+        .join(SCRIPT_FILE_NAME);
+    install(&settings, &new_script).unwrap();
+
+    let root: serde_json::Value =
+        serde_json::from_str(&std::fs::read_to_string(&settings).unwrap()).unwrap();
+    // Foreign hook untouched.
+    let pre = root["hooks"]["PreToolUse"].as_array().unwrap();
+    assert_eq!(pre[0]["hooks"][0]["command"], "my-own-linter.sh");
+    // Stale maestro event gone.
+    assert!(root["hooks"].get("UserPromptSubmit").is_none());
+    // Our events present, nothing else maestro-related anywhere.
+    let cmds = installed_commands(&settings);
+    assert_eq!(
+        cmds.iter().filter(|c| c.contains(HOOK_MARKER)).count(),
+        HOOK_EVENTS.len(),
+        "{cmds:?}"
+    );
+}
+
+/// `is_installed` flips only once a maestro entry exists.
+#[test]
+fn is_installed_tracks_reality() {
+    let dir = tempfile::tempdir().unwrap();
+    let home = dir.path();
+    assert!(!is_installed(&settings_path(home)));
+    install_for_home(home).unwrap();
+    assert!(is_installed(&settings_path(home)));
+}
+
+/// The full home-level install leaves the script executable.
+#[test]
+fn install_for_home_writes_an_executable_script() {
+    let dir = tempfile::tempdir().unwrap();
+    let home = dir.path();
+    install_for_home(home).unwrap();
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let mode = std::fs::metadata(script_path(home))
+            .unwrap()
+            .permissions()
+            .mode();
+        assert_eq!(mode & 0o111, 0o111);
+    }
+}

crates/maestro-names/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "maestro-names"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+publish.workspace = true
+description = "Session-handle generator: musical adjective-noun wordlists"
+
+[dependencies]
+rand.workspace = true

crates/maestro-names/src/lib.rs

@@ -0,0 +1,300 @@
+//! The one home of the session-handle wordlist (#53).
+//!
+//! Previously duplicated in `web/src/names.ts`; every client now gets handles
+//! from here, served by `GET /api/names`.
+
+/// Every word a handle can be: instruments, forms, and the vocabulary of
+/// tempo, dynamics, notation and theory. One word per handle — the list is
+/// wide enough that a single word still reads as distinct.
+pub const WORDS: &[&str] = &[
+    // Instruments
+    "cello",
+    "violin",
+    "viola",
+    "oboe",
+    "flute",
+    "piccolo",
+    "clarinet",
+    "bassoon",
+    "trumpet",
+    "trombone",
+    "tuba",
+    "horn",
+    "cornet",
+    "bugle",
+    "flugelhorn",
+    "euphonium",
+    "saxophone",
+    "recorder",
+    "timpani",
+    "harp",
+    "piano",
+    "organ",
+    "lyre",
+    "lute",
+    "mandolin",
+    "banjo",
+    "ukulele",
+    "guitar",
+    "sitar",
+    "koto",
+    "shamisen",
+    "balalaika",
+    "zither",
+    "dulcimer",
+    "kantele",
+    "erhu",
+    "guzheng",
+    "pipa",
+    "duduk",
+    "ocarina",
+    "kalimba",
+    "harmonica",
+    "accordion",
+    "bandoneon",
+    "bagpipe",
+    "harpsichord",
+    "clavichord",
+    "celesta",
+    "theremin",
+    "marimba",
+    "xylophone",
+    "vibraphone",
+    "glockenspiel",
+    "snare",
+    "cymbal",
+    "tambourine",
+    "castanet",
+    "djembe",
+    "tabla",
+    "bodhran",
+    "gong",
+    "chimes",
+    "contrabass",
+    "shawm",
+    "crumhorn",
+    "sackbut",
+    "didgeridoo",
+    // Forms and pieces
+    "sonata",
+    "fugue",
+    "canon",
+    "prelude",
+    "overture",
+    "rondo",
+    "nocturne",
+    "scherzo",
+    "etude",
+    "ballade",
+    "barcarolle",
+    "bagatelle",
+    "caprice",
+    "chaconne",
+    "passacaglia",
+    "toccata",
+    "intermezzo",
+    "interlude",
+    "minuet",
+    "gavotte",
+    "sarabande",
+    "gigue",
+    "allemande",
+    "courante",
+    "mazurka",
+    "polonaise",
+    "waltz",
+    "bolero",
+    "habanera",
+    "tarantella",
+    "fandango",
+    "serenade",
+    "aubade",
+    "requiem",
+    "cantata",
+    "oratorio",
+    "madrigal",
+    "motet",
+    "chorale",
+    "hymn",
+    "anthem",
+    "lullaby",
+    "elegy",
+    "rhapsody",
+    "symphony",
+    "concerto",
+    "fantasia",
+    "divertimento",
+    "quartet",
+    "quintet",
+    "sextet",
+    "septet",
+    "octet",
+    "trio",
+    // Structure, notation and theory
+    "octave",
+    "chord",
+    "cadence",
+    "cadenza",
+    "coda",
+    "motif",
+    "refrain",
+    "verse",
+    "chorus",
+    "bridge",
+    "finale",
+    "arpeggio",
+    "glissando",
+    "ostinato",
+    "counterpoint",
+    "descant",
+    "harmony",
+    "melody",
+    "rhythm",
+    "tempo",
+    "timbre",
+    "treble",
+    "clef",
+    "staff",
+    "quaver",
+    "crotchet",
+    "semibreve",
+    "fermata",
+    "trill",
+    "mordent",
+    "appoggiatura",
+    "portamento",
+    "vibrato",
+    "triplet",
+    "tuplet",
+    "downbeat",
+    "upbeat",
+    "anacrusis",
+    "syncopation",
+    "modulation",
+    "transposition",
+    "unison",
+    "semitone",
+    "tritone",
+    "diapason",
+    "tonic",
+    "dominant",
+    "mediant",
+    "ionian",
+    "dorian",
+    "phrygian",
+    "lydian",
+    "mixolydian",
+    "aeolian",
+    "locrian",
+    "pentatonic",
+    "chromatic",
+    "diatonic",
+    // Tempo, dynamics and articulation
+    "allegro",
+    "andante",
+    "adagio",
+    "presto",
+    "vivace",
+    "largo",
+    "grave",
+    "lento",
+    "moderato",
+    "crescendo",
+    "diminuendo",
+    "staccato",
+    "legato",
+    "forte",
+    "dolce",
+    "agitato",
+    "cantabile",
+    "sostenuto",
+    "tremolo",
+    "rubato",
+    "marcato",
+    "brillante",
+    "maestoso",
+    "grazioso",
+    "espressivo",
+    "tranquillo",
+    "animato",
+    "spirito",
+    "sotto",
+    "vivo",
+    "feroce",
+    "giocoso",
+    "affettuoso",
+    "risoluto",
+    "leggiero",
+    "pesante",
+    "morendo",
+    "accelerando",
+    "ritardando",
+];
+
+/// Upper bound for a `GET /api/names?count=N` batch.
+pub const MAX_BATCH: usize = 100;
+
+/// A fresh one-word handle, e.g. `nocturne`.
+pub fn generate() -> String {
+    use rand::seq::SliceRandom;
+    let mut rng = rand::thread_rng();
+    (*WORDS.choose(&mut rng).unwrap()).to_string()
+}
+
+/// `count` fresh handles, distinct while the wordlist lasts (the caller
+/// clamps; this only trusts its input).
+pub fn generate_batch(count: usize) -> Vec<String> {
+    use rand::seq::SliceRandom;
+    let mut rng = rand::thread_rng();
+    let mut pool: Vec<&str> = WORDS.to_vec();
+    pool.shuffle(&mut rng);
+    (0..count)
+        .map(|i| match pool.get(i) {
+            // Past the wordlist a batch has to repeat itself.
+            Some(word) => (*word).to_string(),
+            None => generate(),
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::HashSet;
+
+    #[test]
+    fn generated_name_is_a_single_known_word() {
+        let name = generate();
+        assert!(!name.contains('-'), "{name} is not one word");
+        assert!(WORDS.contains(&name.as_str()), "{name} not in WORDS");
+    }
+
+    #[test]
+    fn the_wordlist_has_no_duplicates_and_covers_a_full_batch() {
+        let unique: HashSet<&&str> = WORDS.iter().collect();
+        assert_eq!(unique.len(), WORDS.len(), "WORDS has duplicates");
+        assert!(
+            WORDS.len() >= MAX_BATCH,
+            "a full batch would have to repeat"
+        );
+    }
+
+    #[test]
+    fn batch_returns_the_requested_count_without_repeats() {
+        assert_eq!(generate_batch(1).len(), 1);
+        let batch = generate_batch(MAX_BATCH);
+        assert_eq!(batch.len(), MAX_BATCH);
+        for name in &batch {
+            assert!(WORDS.contains(&name.as_str()), "{name} not in WORDS");
+        }
+        let unique: HashSet<&String> = batch.iter().collect();
+        assert_eq!(unique.len(), batch.len(), "batch repeated a handle");
+    }
+
+    #[test]
+    fn rerolls_can_differ() {
+        let first = generate();
+        let differs = (0..20).any(|_| generate() != first);
+        assert!(differs);
+    }
+}

crates/maestro-protocol/Cargo.toml

@@ -7,11 +7,20 @@ repository.workspace = true
 publish.workspace = true
 description = "Shared wire types for Maestro daemon/client communication"
 
+[features]
+default = []
+# Opt-in `reqwest`-backed client. Off by default so `maestro-web`, which only
+# needs the wire types and route paths, does not pull an HTTP stack it has its
+# own copy of.
+client = ["dep:reqwest"]
+
 [dependencies]
 chrono.workspace = true
 serde.workspace = true
 serde_json.workspace = true
+thiserror.workspace = true
 uuid.workspace = true
+reqwest = { workspace = true, optional = true }
 
 [dev-dependencies]
 serde_json.workspace = true

crates/maestro-protocol/src/client.rs

@@ -0,0 +1,245 @@
+//! Typed client for the daemon's `/api/*` surface.
+//!
+//! Behind the `client` feature so consumers that only need the wire types and
+//! route paths — `maestro-web`, `maestro-config` — don't pull an HTTP stack.
+//!
+//! This is the one place that knows how to call the daemon: the CLI, the TUI and
+//! the end-to-end harness all go through it.
+
+use std::time::Duration;
+
+use reqwest::{Method, Response, StatusCode};
+use serde::de::DeserializeOwned;
+use serde::Serialize;
+use uuid::Uuid;
+
+use crate::routes::{self, UrlError};
+use crate::{
+    ApiError, BranchInfo, CreateSessionRequest, DaemonInfo, DirListing, ErrorInfo, GitRoot,
+    Project, RecentDirs, RenameSessionRequest, ReportActivityRequest, Session,
+};
+
+/// Time budget for establishing a TCP connection to the daemon.
+pub const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(5);
+/// Total budget for a single request. Bounds the case where the daemon is
+/// TCP-alive but never makes forward progress.
+pub const DEFAULT_REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
+
+#[derive(Debug, thiserror::Error)]
+pub enum ClientError {
+    #[error("http: {0}")]
+    Http(#[from] reqwest::Error),
+    /// The daemon answered with a structured [`ApiError`] envelope.
+    #[error("daemon returned {status} ({}): {}", .info.code, .info.message)]
+    Api { status: StatusCode, info: ErrorInfo },
+    /// A non-success response whose body was not an [`ApiError`].
+    #[error("daemon returned {status}: {body}")]
+    Status { status: StatusCode, body: String },
+    #[error("decode: {0}")]
+    Json(#[from] serde_json::Error),
+    #[error(transparent)]
+    Url(#[from] UrlError),
+}
+
+impl ClientError {
+    /// True when the daemon could not be reached at all, rather than reaching it
+    /// and being refused. Drives "is the daemon running?" messaging.
+    pub fn is_unreachable(&self) -> bool {
+        matches!(self, ClientError::Http(e) if e.is_connect())
+    }
+
+    /// The daemon's own message when it sent one, so callers can render the
+    /// reason rather than a bare status code.
+    pub fn daemon_message(&self) -> Option<&str> {
+        match self {
+            ClientError::Api { info, .. } => Some(&info.message),
+            _ => None,
+        }
+    }
+}
+
+/// HTTP client bound to one daemon's base URL.
+///
+/// The daemon's surface needs no auth — reaching its bind address is the
+/// authorization, same trust model as tmux itself.
+#[derive(Debug, Clone)]
+pub struct DaemonClient {
+    base: String,
+    http: reqwest::Client,
+}
+
+impl DaemonClient {
+    /// Client with the standard timeouts.
+    pub fn new(base: impl Into<String>) -> Self {
+        Self::with_timeouts(base, DEFAULT_CONNECT_TIMEOUT, DEFAULT_REQUEST_TIMEOUT)
+    }
+
+    /// Client with explicit timeouts, for callers with a tighter budget than the
+    /// default — the TUI's startup health probe wants to fail fast rather than
+    /// hold the terminal for 30 seconds.
+    pub fn with_timeouts(base: impl Into<String>, connect: Duration, request: Duration) -> Self {
+        let http = reqwest::Client::builder()
+            .user_agent(concat!("maestro/", env!("CARGO_PKG_VERSION")))
+            .connect_timeout(connect)
+            .timeout(request)
+            .build()
+            .expect("build reqwest client");
+        Self {
+            base: routes::normalize_base(&base.into()).to_string(),
+            http,
+        }
+    }
+
+    pub fn base(&self) -> &str {
+        &self.base
+    }
+
+    /// `WS /api/events` URL for this daemon.
+    pub fn events_url(&self) -> Result<String, ClientError> {
+        Ok(routes::events_url(&self.base)?)
+    }
+
+    /// `WS /api/attach/:id` URL for this daemon.
+    pub fn attach_url(&self, id: Uuid) -> Result<String, ClientError> {
+        Ok(routes::attach_url(&self.base, id)?)
+    }
+
+    // -- typed calls --------------------------------------------------------
+
+    pub async fn list_sessions(&self) -> Result<Vec<Session>, ClientError> {
+        self.get(routes::SESSIONS, &[]).await
+    }
+
+    pub async fn create_session(&self, req: &CreateSessionRequest) -> Result<Session, ClientError> {
+        self.post(routes::SESSIONS, req).await
+    }
+
+    /// Kill a session. With `force`, the daemon overrides the kill refusal
+    /// (#79) and leaves the worktree on disk instead of removing it (#81).
+    pub async fn kill_session(&self, id: Uuid, force: bool) -> Result<(), ClientError> {
+        let query: &[(&str, &str)] = if force {
+            &[(routes::FORCE_QUERY, "true")]
+        } else {
+            &[]
+        };
+        let resp = self
+            .send(Method::DELETE, &routes::session(id), query, None::<&()>)
+            .await?;
+        check(resp).await?;
+        Ok(())
+    }
+
+    /// `PATCH /api/sessions/:id` (#125): rename a live session. A blank name
+    /// clears the custom one, so the session falls back to its command. The
+    /// daemon trims and caps the name and answers with the updated session.
+    pub async fn rename_session(&self, id: Uuid, name: &str) -> Result<Session, ClientError> {
+        let req = RenameSessionRequest { name: name.into() };
+        let resp = self
+            .send(Method::PATCH, &routes::session(id), &[], Some(&req))
+            .await?;
+        json(check(resp).await?).await
+    }
+
+    /// `POST /api/sessions/:id/activity` (#105): report an agent-observed
+    /// state. The daemon holds it above its own inference for a TTL, then
+    /// resumes inference. Answers `204 No Content`.
+    pub async fn report_activity(
+        &self,
+        id: Uuid,
+        req: &ReportActivityRequest,
+    ) -> Result<(), ClientError> {
+        let resp = self
+            .send(Method::POST, &routes::session_activity(id), &[], Some(req))
+            .await?;
+        check(resp).await?;
+        Ok(())
+    }
+
+    pub async fn daemon_info(&self) -> Result<DaemonInfo, ClientError> {
+        self.get(routes::INFO, &[]).await
+    }
+
+    pub async fn list_dir(&self, path: &str) -> Result<DirListing, ClientError> {
+        self.get(routes::DIRS, &[(routes::PATH_QUERY, path)]).await
+    }
+
+    pub async fn recent_dirs(&self) -> Result<RecentDirs, ClientError> {
+        self.get(routes::RECENT_DIRS, &[]).await
+    }
+
+    pub async fn git_root(&self, path: &str) -> Result<GitRoot, ClientError> {
+        self.get(routes::GITROOT, &[(routes::PATH_QUERY, path)])
+            .await
+    }
+
+    pub async fn list_projects(&self) -> Result<Vec<Project>, ClientError> {
+        self.get(routes::PROJECTS, &[]).await
+    }
+
+    pub async fn list_branches(&self, path: &str) -> Result<Vec<BranchInfo>, ClientError> {
+        self.get(routes::BRANCHES, &[(routes::PATH_QUERY, path)])
+            .await
+    }
+
+    // -- plumbing -----------------------------------------------------------
+
+    async fn get<T: DeserializeOwned>(
+        &self,
+        path: &str,
+        query: &[(&str, &str)],
+    ) -> Result<T, ClientError> {
+        let resp = self.send(Method::GET, path, query, None::<&()>).await?;
+        json(check(resp).await?).await
+    }
+
+    async fn post<B: Serialize, T: DeserializeOwned>(
+        &self,
+        path: &str,
+        body: &B,
+    ) -> Result<T, ClientError> {
+        let resp = self.send(Method::POST, path, &[], Some(body)).await?;
+        json(check(resp).await?).await
+    }
+
+    async fn send<B: Serialize>(
+        &self,
+        method: Method,
+        path: &str,
+        query: &[(&str, &str)],
+        body: Option<&B>,
+    ) -> Result<Response, ClientError> {
+        let mut req = self
+            .http
+            .request(method, routes::http_url(&self.base, path));
+        if !query.is_empty() {
+            req = req.query(query);
+        }
+        if let Some(b) = body {
+            req = req.json(b);
+        }
+        Ok(req.send().await?)
+    }
+}
+
+/// Turn a non-success response into the richest error its body supports: the
+/// daemon's [`ApiError`] envelope when present, the raw body otherwise.
+async fn check(resp: Response) -> Result<Response, ClientError> {
+    let status = resp.status();
+    if status.is_success() {
+        return Ok(resp);
+    }
+    let body = resp.text().await.unwrap_or_default();
+    match serde_json::from_str::<ApiError>(&body) {
+        Ok(api) => Err(ClientError::Api {
+            status,
+            info: api.error,
+        }),
+        Err(_) => Err(ClientError::Status { status, body }),
+    }
+}
+
+async fn json<T: DeserializeOwned>(resp: Response) -> Result<T, ClientError> {
+    // `204 No Content` is a valid success for the calls that return `()`; the
+    // typed getters never hit it.
+    Ok(resp.json::<T>().await?)
+}

crates/maestro-protocol/src/display.rs

@@ -0,0 +1,321 @@
+//! Path-abbreviation helpers shared by every client that renders a session's
+//! directory (CLI, TUI, web (#117)). Ports of `web/src/types.ts` and
+//! `web/src/tree.ts`'s `abbreviateCwd`, `abbreviateFolderName`, `mergeLinear`,
+//! and `sessionTreePath` — keep them in sync.
+
+use std::path::{Path, PathBuf};
+
+use crate::Session;
+
+/// Collapse a daemon's home dir to `~`. `home` empty leaves the path
+/// untouched. Mirrors the web's `abbreviateCwd`.
+pub fn abbreviate_dir(path: &Path, home: &str) -> String {
+    let p = path.to_string_lossy();
+    if !home.is_empty() {
+        if p == home {
+            return "~".into();
+        }
+        if let Some(rest) = p.strip_prefix(&format!("{home}/")) {
+            return format!("~/{rest}");
+        }
+    }
+    p.into_owned()
+}
+
+/// Result of [`abbreviate_folder_name`]: the last path segment kept verbatim,
+/// and — when there was something to collapse — the shortened lead-in a
+/// caller can render dimmed (the web's `.folder-stem`).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AbbreviatedFolderName {
+    /// The collapsed earlier segments, joined by `/`, with no trailing
+    /// slash. `None` when `name` had two or fewer segments — nothing to
+    /// gain from collapsing, so `last` carries the name unabbreviated.
+    pub stem: Option<String>,
+    pub last: String,
+}
+
+/// `~/git.naps.pt/naps62/maestro` → stem `~/g/n`, last `maestro`: keep the
+/// last segment verbatim, collapse every earlier one to its first character.
+/// Two-or-fewer segments are left alone. Mirrors the web's
+/// `abbreviateFolderName`, minus the HTML escaping/wrapping — a ratatui
+/// caller styles `stem` dim itself rather than parsing markup out of it.
+pub fn abbreviate_folder_name(name: &str) -> AbbreviatedFolderName {
+    let parts: Vec<&str> = name.split('/').collect();
+    if parts.len() <= 2 {
+        return AbbreviatedFolderName {
+            stem: None,
+            last: name.to_string(),
+        };
+    }
+    let last = parts[parts.len() - 1].to_string();
+    let stem = parts[..parts.len() - 1]
+        .iter()
+        .map(|p| {
+            if *p == "~" {
+                "~".to_string()
+            } else {
+                p.chars().next().map(String::from).unwrap_or_default()
+            }
+        })
+        .collect::<Vec<_>>()
+        .join("/");
+    AbbreviatedFolderName {
+        stem: Some(stem),
+        last,
+    }
+}
+
+/// The directory a session lives in: its live `current_cwd` if the daemon
+/// has observed one, else the spawn `cwd`. Mirrors the web's `sessionCwd`.
+fn session_cwd(s: &Session) -> Option<PathBuf> {
+    if let Some(cur) = &s.current_cwd {
+        if !cur.as_os_str().is_empty() {
+            return Some(cur.clone());
+        }
+    }
+    if !s.cwd.as_os_str().is_empty() {
+        return Some(s.cwd.clone());
+    }
+    None
+}
+
+/// Where a session sits in the directory tree. A worktree session belongs to
+/// its repository, not to the worktree (#99): otherwise `~/tea/agent-skills`
+/// grows a `~/tea/agent-skills/worktrees/largo-clarinet` folder holding one
+/// session of the same name, and the repository stops being where you look
+/// for the work. Mirrors the web's `sessionTreePath`.
+pub fn session_tree_path(s: &Session) -> Option<PathBuf> {
+    if let Some(wt) = &s.worktree {
+        return Some(wt.base_repo.clone());
+    }
+    session_cwd(s)
+}
+
+/// One node of a directory tree grouping sessions by path, generic over the
+/// leaf payload since building the tree itself (grouping key, sort order,
+/// filtering) is not this crate's job — only [`merge_linear`] is.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum TreeNode<T> {
+    Folder(TreeFolder<T>),
+    Leaf(T),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TreeFolder<T> {
+    pub name: String,
+    pub path: String,
+    pub children: Vec<TreeNode<T>>,
+}
+
+/// Fold a folder with a single folder-child into one node (`a` + `b` →
+/// `a/b`), repeating down the chain, then recurse into the surviving
+/// branches. The merged node keeps the deepest path so collapse/expand state
+/// stays stable as it grows. Mirrors the web's `mergeLinear`.
+pub fn merge_linear<T>(folder: TreeFolder<T>) -> TreeFolder<T> {
+    let mut cur = folder;
+    loop {
+        let single_folder_child =
+            cur.children.len() == 1 && matches!(cur.children[0], TreeNode::Folder(_));
+        if !single_folder_child {
+            break;
+        }
+        let child = match cur.children.pop().expect("checked len == 1 above") {
+            TreeNode::Folder(f) => f,
+            TreeNode::Leaf(_) => unreachable!("checked matches! above"),
+        };
+        cur = TreeFolder {
+            name: format!("{}/{}", cur.name, child.name),
+            path: child.path,
+            children: child.children,
+        };
+    }
+    cur.children = cur
+        .children
+        .into_iter()
+        .map(|c| match c {
+            TreeNode::Folder(f) => TreeNode::Folder(merge_linear(f)),
+            leaf => leaf,
+        })
+        .collect();
+    cur
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{SessionStatus, SessionWorktree};
+    use chrono::{TimeZone, Utc};
+    use std::collections::HashMap;
+    use uuid::Uuid;
+
+    fn session(cwd: &str) -> Session {
+        Session {
+            id: Uuid::from_u128(1),
+            cwd: PathBuf::from(cwd),
+            command: "bash".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: None,
+            status: SessionStatus::Running,
+            created_at: Utc.with_ymd_and_hms(2026, 8, 25, 12, 0, 0).unwrap(),
+            foreground: None,
+            activity: Default::default(),
+            activity_detail: None,
+            last_activity_at: Utc::now(),
+            activity_since: Utc::now(),
+            current_cwd: None,
+            blocked_work: None,
+        }
+    }
+
+    #[test]
+    fn abbreviate_dir_collapses_home() {
+        assert_eq!(
+            abbreviate_dir(Path::new("/home/naps/maestro"), "/home/naps"),
+            "~/maestro"
+        );
+        assert_eq!(abbreviate_dir(Path::new("/home/naps"), "/home/naps"), "~");
+    }
+
+    #[test]
+    fn abbreviate_dir_leaves_paths_outside_home_untouched() {
+        assert_eq!(
+            abbreviate_dir(Path::new("/srv/work/api"), "/home/naps"),
+            "/srv/work/api"
+        );
+        assert_eq!(
+            abbreviate_dir(Path::new("/srv/work/api"), ""),
+            "/srv/work/api"
+        );
+    }
+
+    #[test]
+    fn abbreviate_folder_name_collapses_the_stem() {
+        let got = abbreviate_folder_name("~/git.naps.pt/naps62/maestro");
+        assert_eq!(
+            got,
+            AbbreviatedFolderName {
+                stem: Some("~/g/n".into()),
+                last: "maestro".into(),
+            }
+        );
+    }
+
+    /// Two-or-fewer segments are left alone — nothing to gain from collapsing.
+    #[test]
+    fn abbreviate_folder_name_two_segment_no_op() {
+        assert_eq!(
+            abbreviate_folder_name("~/work"),
+            AbbreviatedFolderName {
+                stem: None,
+                last: "~/work".into(),
+            }
+        );
+        assert_eq!(
+            abbreviate_folder_name("work"),
+            AbbreviatedFolderName {
+                stem: None,
+                last: "work".into(),
+            }
+        );
+    }
+
+    #[test]
+    fn session_tree_path_prefers_worktree_base_repo() {
+        let mut s = session("/home/n/tea/agent-skills/worktrees/largo-clarinet");
+        s.worktree = Some(SessionWorktree {
+            path: PathBuf::from("/home/n/tea/agent-skills/worktrees/largo-clarinet"),
+            base_repo: PathBuf::from("/home/n/tea/agent-skills"),
+        });
+        assert_eq!(
+            session_tree_path(&s),
+            Some(PathBuf::from("/home/n/tea/agent-skills"))
+        );
+    }
+
+    #[test]
+    fn session_tree_path_falls_back_to_cwd_without_a_worktree() {
+        let s = session("/home/n/tea/arr");
+        assert_eq!(
+            session_tree_path(&s),
+            Some(PathBuf::from("/home/n/tea/arr"))
+        );
+    }
+
+    #[test]
+    fn session_tree_path_prefers_live_current_cwd_over_spawn_cwd() {
+        let mut s = session("/home/n/tea/arr");
+        s.current_cwd = Some(PathBuf::from("/home/n/tea/arr/crates"));
+        assert_eq!(
+            session_tree_path(&s),
+            Some(PathBuf::from("/home/n/tea/arr/crates"))
+        );
+    }
+
+    fn leaf(name: &str) -> TreeNode<String> {
+        TreeNode::Leaf(name.into())
+    }
+
+    fn folder(name: &str, path: &str, children: Vec<TreeNode<String>>) -> TreeFolder<String> {
+        TreeFolder {
+            name: name.into(),
+            path: path.into(),
+            children,
+        }
+    }
+
+    /// The web's mergeLinear test: keeps the deepest path so collapse state
+    /// survives growth.
+    #[test]
+    fn merge_linear_folds_a_chain_and_keeps_the_deepest_path() {
+        let tree = folder("a", "a", vec![TreeNode::Folder(folder("b", "a/b", vec![]))]);
+        let merged = merge_linear(tree);
+        assert_eq!(merged.name, "a/b");
+        assert_eq!(merged.path, "a/b");
+    }
+
+    #[test]
+    fn merge_linear_stops_where_a_directory_branches() {
+        let tree = folder(
+            "git",
+            "git",
+            vec![
+                TreeNode::Folder(folder("one", "git/one", vec![])),
+                TreeNode::Folder(folder("two", "git/two", vec![])),
+            ],
+        );
+        let merged = merge_linear(tree);
+        assert_eq!(merged.name, "git");
+        assert_eq!(merged.children.len(), 2);
+    }
+
+    #[test]
+    fn merge_linear_stops_at_a_leaf() {
+        let tree = folder("a", "a", vec![leaf("session")]);
+        let merged = merge_linear(tree);
+        assert_eq!(merged.name, "a");
+        assert_eq!(merged.children, vec![leaf("session")]);
+    }
+
+    #[test]
+    fn merge_linear_recurses_into_surviving_branches() {
+        let tree = folder(
+            "root",
+            "root",
+            vec![
+                TreeNode::Folder(folder(
+                    "a",
+                    "root/a",
+                    vec![TreeNode::Folder(folder("b", "root/a/b", vec![leaf("s")]))],
+                )),
+                leaf("other"),
+            ],
+        );
+        let merged = merge_linear(tree);
+        assert_eq!(merged.children.len(), 2);
+        let TreeNode::Folder(nested) = &merged.children[0] else {
+            panic!("expected folder")
+        };
+        assert_eq!(nested.name, "a/b");
+    }
+}

crates/maestro-protocol/src/lib.rs

@@ -7,6 +7,14 @@
 
 #![deny(missing_debug_implementations)]
 
+#[cfg(feature = "client")]
+pub mod client;
+pub mod display;
+pub mod routes;
+
+#[cfg(feature = "client")]
+pub use client::{ClientError, DaemonClient};
+
 use std::collections::HashMap;
 use std::path::PathBuf;
 
@@ -18,6 +26,24 @@ use uuid::Uuid;
 /// The protocol version this crate implements. Advertised in `GET /api/info`.
 pub const PROTOCOL_VERSION: &str = env!("CARGO_PKG_VERSION");
 
+/// True when a daemon advertising `daemon_version` speaks the same protocol as
+/// this build.
+///
+/// Compared on the major component only, per semver: within a major, added
+/// fields are `#[serde(default)]` and so are forward-compatible. An empty or
+/// unparseable version is treated as compatible — daemons that predate the
+/// field should not trip a warning.
+pub fn is_compatible(daemon_version: &str) -> bool {
+    fn major(v: &str) -> Option<&str> {
+        let m = v.split('.').next()?;
+        (!m.is_empty() && m.bytes().all(|b| b.is_ascii_digit())).then_some(m)
+    }
+    match (major(daemon_version), major(PROTOCOL_VERSION)) {
+        (Some(theirs), Some(ours)) => theirs == ours,
+        _ => true,
+    }
+}
+
 /// A live or recently-dead tmux session managed by the daemon.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct Session {
@@ -28,6 +54,14 @@ pub struct Session {
     pub env: HashMap<String, String>,
     #[serde(default)]
     pub metadata: HashMap<String, Value>,
+    /// The worktree this session owns, when it was spawned with one.
+    ///
+    /// Persisted rather than kept in memory only: after a daemon restart the
+    /// recovered session must still know what to clean up, and with
+    /// deterministic worktree paths a forgotten association leaves a directory
+    /// that blocks that branch from ever being spawned again (#54 review).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub worktree: Option<SessionWorktree>,
     pub status: SessionStatus,
     pub created_at: DateTime<Utc>,
     /// Current foreground command in the session's pane (e.g. `claude`,
@@ -42,11 +76,24 @@ pub struct Session {
     /// byte stream.
     #[serde(default)]
     pub activity: ActivityState,
+    /// Short human-readable string an agent reported alongside its activity
+    /// (#105) — e.g. why it is in `Error`. Shown on a sidebar card's meta line
+    /// while the report is in force; cleared when the report lapses or is
+    /// replaced. `None` unless an agent reported one.
+    #[serde(default)]
+    pub activity_detail: Option<String>,
     /// Wall-clock time of the session's most recent observed PTY output.
     /// Drives "idle for Ns" displays. Defaults to the Unix epoch on payloads
     /// from daemons that predate the field.
     #[serde(default = "epoch")]
     pub last_activity_at: DateTime<Utc>,
+    /// Wall-clock time at which the session entered its current
+    /// [`ActivityState`] (#102) — how long it has been `Active`, `Idle` or
+    /// `AwaitingInput`. Distinct from [`Self::last_activity_at`], which only
+    /// tracks the last observed PTY output. Populated by #104; defaults to the
+    /// Unix epoch on payloads from daemons that predate the field.
+    #[serde(default = "epoch")]
+    pub activity_since: DateTime<Utc>,
     /// The pane's *current* working directory (`#{pane_current_path}`) — distinct
     /// from [`Session::cwd`], the directory it was spawned in. The activity
     /// watcher refreshes it as the user `cd`s around; it drives the web UI's
@@ -54,6 +101,13 @@ pub struct Session {
     /// from daemons that predate the field.
     #[serde(default)]
     pub current_cwd: Option<PathBuf>,
+    /// Whether the session's worktree currently holds anything that would
+    /// block an unforced kill (#83), summarised by [`InTheWay`]'s `Display`.
+    /// Refreshed by the daemon's watcher; `None` for sessions without a
+    /// worktree and until the first probe. Defaults on the wire so payloads
+    /// from daemons that predate the field stay forward-compatible.
+    #[serde(default)]
+    pub blocked_work: Option<InTheWay>,
 }
 
 /// Default for [`Session::last_activity_at`] when an older payload omits it.
@@ -70,7 +124,12 @@ pub enum SessionStatus {
 /// Inferred session activity, orthogonal to [`SessionStatus`] (NAP-340). The
 /// daemon derives this from tmux pane state, PTY quiescence, and `/proc`
 /// inspection — never by parsing the terminal byte stream.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+///
+/// Deserializes leniently (#110, SIDEBAR.md Precedence): an unknown variant
+/// from a newer daemon becomes [`ActivityState::Idle`] instead of failing the
+/// whole `Session`. Non-string values still error — only variant names are
+/// forgiven.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Default)]
 pub enum ActivityState {
     /// Producing output, or the foreground process is busy.
     Active,
@@ -79,6 +138,64 @@ pub enum ActivityState {
     Idle,
     /// Blocked on a `read()` from the pty — waiting on the user.
     AwaitingInput,
+    /// The agent running in the session reported a failure (#102). Never
+    /// inferred by the daemon; only set when an agent reports it (#105).
+    Error,
+}
+
+impl<'de> Deserialize<'de> for ActivityState {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let s = String::deserialize(deserializer)?;
+        Ok(match s.as_str() {
+            "Active" => Self::Active,
+            "AwaitingInput" => Self::AwaitingInput,
+            "Error" => Self::Error,
+            // Known or not, any other spelling degrades to the neutral default
+            _ => Self::Idle,
+        })
+    }
+}
+
+/// HTTP `POST /api/sessions/:id/activity` body (#105): an agent's report of
+/// its own state. The daemon holds the reported state above its own inference
+/// for a fixed TTL, then resumes inference.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ReportActivityRequest {
+    /// Parsed strictly, unlike [`ActivityState`]'s own lenient `Deserialize`
+    /// (#110). Leniency exists so a client reading a *newer* daemon's snapshot
+    /// degrades an unrecognised state to `Idle` instead of dropping the whole
+    /// session. A report travelling the other way has no such excuse: an agent
+    /// posting a state this daemon does not know is a bug in the agent, and
+    /// silently recording it as `Idle` would hide that behind a 204.
+    #[serde(deserialize_with = "strict_activity_state")]
+    pub state: ActivityState,
+    /// Short human string shown next to the state (e.g. an error message).
+    /// The daemon caps its length server-side.
+    #[serde(default)]
+    pub detail: Option<String>,
+}
+
+/// Reject an unknown [`ActivityState`] spelling instead of degrading it to
+/// `Idle`. Used only by [`ReportActivityRequest`]; see the note there.
+fn strict_activity_state<'de, D>(deserializer: D) -> Result<ActivityState, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    use serde::de::Error as _;
+    let s = String::deserialize(deserializer)?;
+    match s.as_str() {
+        "Active" => Ok(ActivityState::Active),
+        "Idle" => Ok(ActivityState::Idle),
+        "AwaitingInput" => Ok(ActivityState::AwaitingInput),
+        "Error" => Ok(ActivityState::Error),
+        other => Err(D::Error::unknown_variant(
+            other,
+            &["Active", "Idle", "AwaitingInput", "Error"],
+        )),
+    }
 }
 
 /// Optional worktree request attached to a `CreateSessionRequest`.
@@ -86,8 +203,134 @@ pub enum ActivityState {
 pub struct WorktreeSpec {
     pub base_repo: PathBuf,
     pub branch: String,
+    /// When false, `branch` must already exist and is checked out as-is
+    /// (#56); when true (the default, and what every payload meant before
+    /// the field existed) the daemon creates it with `worktree add -b`.
+    #[serde(default = "default_true")]
+    pub create_branch: bool,
+}
+
+fn default_true() -> bool {
+    true
+}
+
+/// The worktree a running session owns, carried on [`Session`] so it survives
+/// a daemon restart.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SessionWorktree {
+    pub path: PathBuf,
+    pub base_repo: PathBuf,
+}
+
+/// What a kill refusal reports about a worktree (#80) — the breakdown that
+/// blocks an unforced kill, recomputed on every probe so it reflects the tree
+/// now.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct InTheWay {
+    /// Tracked files with uncommitted modifications.
     #[serde(default)]
-    pub cleanup_on_kill: bool,
+    pub uncommitted_files: usize,
+    /// Untracked files that are not ignored (ignored files never block).
+    #[serde(default)]
+    pub untracked_files: usize,
+    /// Commits on the branch reachable from no remote-tracking ref.
+    #[serde(default)]
+    pub unpushed_commits: usize,
+    /// Lines added across the tracked changes — staged and unstaged alike,
+    /// measured against `HEAD`. Untracked files contribute nothing: counting
+    /// their lines means reading every one off disk, and they already have
+    /// their own count above (docs/SIDEBAR.md).
+    #[serde(default)]
+    pub insertions: usize,
+    /// Lines removed across the same tracked changes.
+    #[serde(default)]
+    pub deletions: usize,
+}
+
+impl InTheWay {
+    /// Nothing blocks any more — the work has since been committed and pushed.
+    ///
+    /// The line counts are not consulted: they describe the same tracked
+    /// changes `uncommitted_files` counts, and a change with no line delta —
+    /// a mode change, a rename — still blocks.
+    pub fn is_clear(&self) -> bool {
+        self.uncommitted_files == 0 && self.untracked_files == 0 && self.unpushed_commits == 0
+    }
+}
+
+/// Which fragment of the compact blocked-work stat a value is, and so which
+/// colour the client paints it (docs/SIDEBAR.md).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum StatKind {
+    /// Lines added.
+    Added,
+    /// Lines removed.
+    Removed,
+    /// Changed tracked files, when the change carries no line delta.
+    Files,
+    /// Untracked files.
+    Untracked,
+    /// Unpushed commits.
+    Unpushed,
+}
+
+impl InTheWay {
+    /// The breakdown as diff notation: `+124`, `-18`, `?3`, `↑2`.
+    ///
+    /// The line counts cover tracked changes only, so a tree whose only
+    /// tracked change carries no line delta — a mode change, a rename —
+    /// reports the file count (`~2`) rather than claiming `+0 -0`. Both
+    /// sidebars render exactly these fragments; [`Display`](std::fmt::Display)
+    /// remains the spelled-out phrasing for the kill refusal and the tooltip.
+    pub fn stats(&self) -> Vec<(StatKind, String)> {
+        let mut out = Vec::new();
+        if self.insertions > 0 || self.deletions > 0 {
+            if self.insertions > 0 {
+                out.push((StatKind::Added, format!("+{}", self.insertions)));
+            }
+            if self.deletions > 0 {
+                out.push((StatKind::Removed, format!("-{}", self.deletions)));
+            }
+        } else if self.uncommitted_files > 0 {
+            out.push((StatKind::Files, format!("~{}", self.uncommitted_files)));
+        }
+        if self.untracked_files > 0 {
+            out.push((StatKind::Untracked, format!("?{}", self.untracked_files)));
+        }
+        if self.unpushed_commits > 0 {
+            out.push((StatKind::Unpushed, format!("↑{}", self.unpushed_commits)));
+        }
+        out
+    }
+}
+
+impl std::fmt::Display for InTheWay {
+    /// "3 uncommitted files, 2 unpushed commits" — zero parts are omitted;
+    /// all-zero renders "no unsaved work". This is the phrasing every client
+    /// uses for both the kill refusal and the retained list, so the two
+    /// cannot describe the same tree differently.
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let parts = [
+            (self.uncommitted_files, "uncommitted file"),
+            (self.untracked_files, "untracked file"),
+            (self.unpushed_commits, "unpushed commit"),
+        ];
+        let said: Vec<String> = parts
+            .into_iter()
+            .filter(|(n, _)| *n > 0)
+            .map(|(n, unit)| {
+                if n == 1 {
+                    format!("1 {unit}")
+                } else {
+                    format!("{n} {unit}s")
+                }
+            })
+            .collect();
+        if said.is_empty() {
+            return write!(f, "no unsaved work");
+        }
+        write!(f, "{}", said.join(", "))
+    }
 }
 
 /// HTTP `POST /api/sessions` body.
@@ -151,11 +394,147 @@ pub struct GitRoot {
     pub root: Option<PathBuf>,
 }
 
+/// One discovered git repository (or linked worktree) for `GET /api/projects`
+/// (#54). The daemon reports the timestamp; clients decide what "stale" means
+/// (the web UI dims entries older than 7 days).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Project {
+    /// Absolute path of the repository/worktree toplevel.
+    pub path: PathBuf,
+    /// Basename of `path`.
+    pub name: String,
+    #[serde(default)]
+    pub is_worktree: bool,
+    /// The main checkout this worktree belongs to. Set only when
+    /// [`Self::is_worktree`].
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub base_repo: Option<PathBuf>,
+    /// Later of the repo's git HEAD mtime and the newest spawn-history use of
+    /// any directory inside it. `None` when neither is known.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub last_activity: Option<DateTime<Utc>>,
+    /// Command last spawned in this project, from spawn history.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub last_command: Option<String>,
+}
+
+/// One local branch of a repository for `GET /api/branches` (#55). A client
+/// disables the entry when `is_head` is set or `worktree` is present — git
+/// refuses to check the same branch out in two worktrees at once.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct BranchInfo {
+    /// Short branch name (`main`, `feature/foo`).
+    pub name: String,
+    /// Whether this branch is the main checkout's current HEAD. The main
+    /// checkout's occupancy reports here rather than through `worktree`.
+    pub is_head: bool,
+    /// Toplevel path of the linked worktree holding this branch, if any.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub worktree: Option<PathBuf>,
+}
+
 /// Structured failure used everywhere we don't want to leak a string-only error.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct ErrorInfo {
     pub code: String,
     pub message: String,
+    /// Set only by the kill guard (#79): the unsaved work that blocked
+    /// `DELETE /api/sessions/:id`, so a client can render counts directly.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub unsaved_work: Option<InTheWay>,
+}
+
+/// The envelope every `/api/*` failure is wrapped in: `{"error": {…}}`.
+///
+/// The daemon builds it, the CLI and TUI decode it to surface the daemon's own
+/// message, and `maestro-web` uses it both to report proxy failures and to
+/// recover the rejection reason from an upstream WebSocket handshake. Before it
+/// lived here that shape was hand-rolled in four places, one of them by
+/// escaping quotes into a format string.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ApiError {
+    pub error: ErrorInfo,
+}
+
+impl ApiError {
+    pub fn new(code: impl Into<String>, message: impl Into<String>) -> Self {
+        Self {
+            error: ErrorInfo {
+                code: code.into(),
+                message: message.into(),
+                unsaved_work: None,
+            },
+        }
+    }
+
+    /// The daemon's human-readable reason, for clients that only render text.
+    pub fn message(&self) -> &str {
+        &self.error.message
+    }
+}
+
+/// One command tile offered by the spawn form.
+///
+/// Lives here rather than in `maestro-config` because it is on the wire inside
+/// [`DaemonInfo`]; `maestro-config` re-exports it so the on-disk `[spawn]`
+/// schema and the payload stay one type.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SpawnPreset {
+    pub id: String,
+    pub label: String,
+    pub command: String,
+}
+
+/// Payload of `GET /api/info` — daemon identity, protocol version, and the
+/// spawn presets clients render as one-click tiles.
+///
+/// Previously declared three times (daemon, CLI, TypeScript), and the CLI's
+/// copy silently dropped `version` and `presets`.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DaemonInfo {
+    #[serde(default)]
+    pub hostname: String,
+    /// The `PROTOCOL_VERSION` the daemon implements.
+    #[serde(default)]
+    pub version: String,
+    /// Home directory of the OS user the daemon runs as, so clients can prefill
+    /// a spawn form's working directory. Empty if unresolved.
+    #[serde(default)]
+    pub home_dir: String,
+    #[serde(default)]
+    pub presets: Vec<SpawnPreset>,
+}
+
+/// Payload of `GET /api/names?count=N` (#53) — a batch of fresh
+/// one-word session handles generated by the `maestro-names` crate.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct NameBatch {
+    pub names: Vec<String>,
+}
+
+/// Longest session name the daemon stores (#125), in characters. A name is a
+/// sidebar card's line 1; past this it only truncates on every client anyway.
+pub const MAX_SESSION_NAME_LEN: usize = 64;
+
+/// HTTP `PATCH /api/sessions/:id` body (#125): rename a live session.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct RenameSessionRequest {
+    pub name: String,
+}
+
+/// Trim a requested session name and cap it at [`MAX_SESSION_NAME_LEN`]
+/// characters. `None` when nothing is left — that clears `metadata.name` and
+/// the card falls back to the command, the same rule the spawn form uses when
+/// its name field is blank.
+///
+/// Shared so the daemon and every Rust client agree on what a name becomes;
+/// `web/src/types.ts` carries the same function for the browser.
+pub fn normalize_session_name(name: &str) -> Option<String> {
+    let trimmed = name.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    Some(trimmed.chars().take(MAX_SESSION_NAME_LEN).collect())
 }
 
 // ---------------------------------------------------------------------------
@@ -208,6 +587,66 @@ pub enum ClientControl {
 mod tests {
     use super::*;
 
+    #[test]
+    fn version_compatibility_is_major_only() {
+        assert!(is_compatible(PROTOCOL_VERSION));
+        let ours_major = PROTOCOL_VERSION.split('.').next().unwrap();
+        assert!(is_compatible(&format!("{ours_major}.99.99")));
+        assert!(!is_compatible("99.0.0"));
+    }
+
+    /// A daemon predating the field sends nothing; that must not read as a
+    /// mismatch.
+    #[test]
+    fn version_compatibility_tolerates_unknown_versions() {
+        assert!(is_compatible(""));
+        assert!(is_compatible("unknown"));
+    }
+
+    /// docs/SIDEBAR.md: the sidebars render the breakdown as diff notation.
+    #[test]
+    fn stats_read_as_a_diff() {
+        let w = InTheWay {
+            uncommitted_files: 3,
+            untracked_files: 2,
+            unpushed_commits: 1,
+            insertions: 124,
+            deletions: 18,
+        };
+        let text: Vec<String> = w.stats().into_iter().map(|(_, t)| t).collect();
+        assert_eq!(text, ["+124", "-18", "?2", "↑1"]);
+        let kinds: Vec<StatKind> = w.stats().into_iter().map(|(k, _)| k).collect();
+        assert_eq!(
+            kinds,
+            [
+                StatKind::Added,
+                StatKind::Removed,
+                StatKind::Untracked,
+                StatKind::Unpushed
+            ]
+        );
+    }
+
+    /// A change with no line delta — a mode change — still has to say
+    /// something, and `+0 -0` would be a lie about the tree.
+    #[test]
+    fn stats_fall_back_to_the_file_count_without_a_line_delta() {
+        let w = InTheWay {
+            uncommitted_files: 2,
+            ..InTheWay::default()
+        };
+        let text: Vec<String> = w.stats().into_iter().map(|(_, t)| t).collect();
+        assert_eq!(text, ["~2"]);
+        assert!(!w.is_clear());
+    }
+
+    /// A clear tree says nothing at all — the fragment is omitted, not empty.
+    #[test]
+    fn a_clear_tree_has_no_stats() {
+        assert!(InTheWay::default().stats().is_empty());
+        assert!(InTheWay::default().is_clear());
+    }
+
     fn round_trip<T>(value: &T) -> T
     where
         T: Serialize + for<'de> Deserialize<'de>,
@@ -216,6 +655,34 @@ mod tests {
         serde_json::from_str(&json).expect("deserialize")
     }
 
+    #[test]
+    fn project_round_trips_and_defaults_on_legacy_payload() {
+        let full = Project {
+            path: PathBuf::from("/home/u/tea/maestro"),
+            name: "maestro".into(),
+            is_worktree: true,
+            base_repo: Some(PathBuf::from("/home/u/tea/maestro-main")),
+            last_activity: Some(
+                DateTime::parse_from_rfc3339("2026-08-23T12:00:00Z")
+                    .unwrap()
+                    .with_timezone(&Utc),
+            ),
+            last_command: Some("claude".into()),
+        };
+        assert_eq!(full, round_trip(&full));
+
+        // A payload from a daemon predating the optional fields still decodes.
+        let legacy = serde_json::json!({
+            "path": "/home/u/proj",
+            "name": "proj",
+        });
+        let p: Project = serde_json::from_value(legacy).unwrap();
+        assert!(!p.is_worktree);
+        assert_eq!(p.base_repo, None);
+        assert_eq!(p.last_activity, None);
+        assert_eq!(p.last_command, None);
+    }
+
     fn sample_session() -> Session {
         Session {
             id: Uuid::from_u128(0x0123_4567_89ab_cdef_0123_4567_89ab_cdef),
@@ -223,16 +690,22 @@ mod tests {
             command: "claude".into(),
             env: HashMap::from([("FOO".into(), "bar".into())]),
             metadata: HashMap::from([("name".into(), Value::String("maestro-impl".into()))]),
+            worktree: None,
             status: SessionStatus::Running,
             created_at: DateTime::parse_from_rfc3339("2026-05-24T12:00:00Z")
                 .unwrap()
                 .with_timezone(&Utc),
             foreground: Some("claude".into()),
             activity: ActivityState::Active,
+            activity_detail: None,
             last_activity_at: DateTime::parse_from_rfc3339("2026-05-24T12:05:00Z")
                 .unwrap()
                 .with_timezone(&Utc),
+            activity_since: DateTime::parse_from_rfc3339("2026-05-24T12:04:30Z")
+                .unwrap()
+                .with_timezone(&Utc),
             current_cwd: Some(PathBuf::from("/home/naps62/projects/maestro/crates")),
+            blocked_work: None,
         }
     }
 
@@ -252,6 +725,63 @@ mod tests {
         assert_eq!(s.activity, ActivityState::Idle);
         assert_eq!(s.last_activity_at, epoch());
         assert!(s.current_cwd.is_none());
+        assert!(s.blocked_work.is_none());
+    }
+
+    #[test]
+    fn blocked_work_defaults_to_none_on_legacy_payload() {
+        // A pre-#83 daemon omits the indicator; it must deserialize to `None`
+        // rather than failing, and a present value round-trips.
+        let json = serde_json::json!({
+            "id": Uuid::from_u128(1),
+            "cwd": "/tmp",
+            "command": "bash",
+            "status": "Running",
+            "created_at": "2026-05-24T12:00:00Z"
+        });
+        let s: Session = serde_json::from_value(json).unwrap();
+        assert_eq!(s.blocked_work, None);
+
+        let mut with_blocker = sample_session();
+        with_blocker.blocked_work = Some(InTheWay {
+            uncommitted_files: 3,
+            ..InTheWay::default()
+        });
+        assert_eq!(
+            with_blocker.clone().blocked_work,
+            serde_json::from_value::<Session>(serde_json::to_value(&with_blocker).unwrap())
+                .unwrap()
+                .blocked_work
+        );
+    }
+
+    #[test]
+    fn activity_since_defaults_to_epoch_on_legacy_payload() {
+        // A daemon predating #102 omits `activity_since`; it must deserialize
+        // to the forward-compat default rather than failing, and a present
+        // value round-trips.
+        let json = serde_json::json!({
+            "id": Uuid::from_u128(1),
+            "cwd": "/tmp",
+            "command": "bash",
+            "status": "Running",
+            "created_at": "2026-05-24T12:00:00Z"
+        });
+        let s: Session = serde_json::from_value(json).unwrap();
+        assert_eq!(s.activity_since, epoch());
+
+        let full = sample_session();
+        assert_eq!(full, round_trip(&full));
+    }
+
+    // #102: nothing infers `Error`; only #105's agent-reported failure sets it.
+    #[test]
+    fn error_activity_state_serializes_pascal_case_and_idle_stays_default() {
+        assert_eq!(
+            serde_json::to_value(ActivityState::Error).unwrap(),
+            serde_json::json!("Error")
+        );
+        assert_eq!(ActivityState::default(), ActivityState::Idle);
     }
 
     #[test]
@@ -263,6 +793,78 @@ mod tests {
         assert_eq!(ActivityState::default(), ActivityState::Idle);
     }
 
+    // #110 / SIDEBAR.md Precedence: a future daemon may send an
+    // `ActivityState` variant this client does not know; it must degrade to
+    // the neutral default instead of failing the whole `Session`.
+    #[test]
+    fn unknown_activity_state_variant_deserializes_to_idle() {
+        assert_eq!(
+            serde_json::from_value::<ActivityState>(serde_json::json!("Teleported")).unwrap(),
+            ActivityState::Idle
+        );
+
+        let mut future = serde_json::to_value(sample_session()).unwrap();
+        future["activity"] = serde_json::json!("QuantumEntangled");
+        let s: Session = serde_json::from_value(future).unwrap();
+        assert_eq!(s.activity, ActivityState::Idle);
+    }
+
+    #[test]
+    fn non_string_activity_payload_still_fails_deserialization() {
+        let json = serde_json::json!({
+            "id": Uuid::from_u128(1),
+            "cwd": "/tmp",
+            "command": "bash",
+            "status": "Running",
+            "created_at": "2026-05-24T12:00:00Z",
+            "activity": 42,
+        });
+        assert!(serde_json::from_value::<Session>(json).is_err());
+    }
+
+    #[test]
+    fn activity_detail_defaults_to_none_on_legacy_payload() {
+        // #105: a daemon predating the detail field omits it; it must
+        // deserialize to `None` rather than failing, and a present value
+        // round-trips.
+        let json = serde_json::json!({
+            "id": Uuid::from_u128(1),
+            "cwd": "/tmp",
+            "command": "bash",
+            "status": "Running",
+            "created_at": "2026-05-24T12:00:00Z"
+        });
+        let s: Session = serde_json::from_value(json).unwrap();
+        assert_eq!(s.activity_detail, None);
+
+        let mut reported = sample_session();
+        reported.activity = ActivityState::Error;
+        reported.activity_detail = Some("build failed".into());
+        assert_eq!(reported.clone(), round_trip(&reported));
+    }
+
+    #[test]
+    fn report_activity_request_defaults_detail_and_rejects_unknown_state() {
+        let bare: ReportActivityRequest =
+            serde_json::from_value(serde_json::json!({ "state": "Error" })).unwrap();
+        assert_eq!(bare.state, ActivityState::Error);
+        assert_eq!(bare.detail, None);
+
+        let full = ReportActivityRequest {
+            state: ActivityState::AwaitingInput,
+            detail: Some("waiting on permission".into()),
+        };
+        assert_eq!(full, round_trip(&full));
+
+        // Unknown state values are rejected rather than coerced (#105).
+        assert!(
+            serde_json::from_value::<ReportActivityRequest>(serde_json::json!({
+                "state": "Teleported"
+            }))
+            .is_err()
+        );
+    }
+
     #[test]
     fn session_round_trips() {
         let s = sample_session();
@@ -291,7 +893,7 @@ mod tests {
             worktree: Some(WorktreeSpec {
                 base_repo: PathBuf::from("/home/naps62/projects/maestro"),
                 branch: "feat/foo".into(),
-                cleanup_on_kill: true,
+                create_branch: true,
             }),
         };
         assert_eq!(req, round_trip(&req));
@@ -309,6 +911,29 @@ mod tests {
         assert!(req.metadata.is_empty());
     }
 
+    /// A client that predates the new/existing discriminator sends no
+    /// `create_branch`; the daemon must read that as "create a new branch" —
+    /// exactly what every payload meant before the field existed (#56).
+    #[test]
+    fn worktree_spec_defaults_on_legacy_payload() {
+        let json = serde_json::json!({
+            "base_repo": "/home/naps62/projects/maestro",
+            "branch": "feat/foo",
+        });
+        let spec: WorktreeSpec = serde_json::from_value(json).unwrap();
+        assert!(spec.create_branch);
+    }
+
+    #[test]
+    fn worktree_spec_round_trips_existing_branch_mode() {
+        let spec = WorktreeSpec {
+            base_repo: PathBuf::from("/work"),
+            branch: "feat/foo".into(),
+            create_branch: false,
+        };
+        assert_eq!(spec, round_trip(&spec));
+    }
+
     #[test]
     fn catalog_event_round_trips_and_tags() {
         let session = sample_session();
@@ -348,10 +973,49 @@ mod tests {
             ClientControl::Error(ErrorInfo {
                 code: "bad_frame".into(),
                 message: "decode failed".into(),
+                unsaved_work: None,
             }),
             resize,
         ] {
             assert_eq!(c, round_trip(&c));
         }
     }
+
+    /// #125: a rename request is trimmed and capped; a blank one clears the
+    /// name so the card falls back to the command.
+    #[test]
+    fn session_names_are_trimmed_capped_and_blankable() {
+        assert_eq!(
+            normalize_session_name("  amber-falcon  "),
+            Some("amber-falcon".into())
+        );
+        assert_eq!(normalize_session_name(""), None);
+        assert_eq!(normalize_session_name("   \t "), None);
+        let long = "x".repeat(MAX_SESSION_NAME_LEN + 10);
+        assert_eq!(
+            normalize_session_name(&long).unwrap().chars().count(),
+            MAX_SESSION_NAME_LEN
+        );
+    }
+
+    /// The cap counts characters, not bytes — a multi-byte name must not be
+    /// sliced mid-codepoint.
+    #[test]
+    fn session_name_cap_counts_characters() {
+        let name = "é".repeat(MAX_SESSION_NAME_LEN + 5);
+        let capped = normalize_session_name(&name).unwrap();
+        assert_eq!(capped.chars().count(), MAX_SESSION_NAME_LEN);
+    }
+
+    #[test]
+    fn rename_request_round_trips() {
+        let req = RenameSessionRequest {
+            name: "amber-falcon".into(),
+        };
+        assert_eq!(req, round_trip(&req));
+        assert_eq!(
+            serde_json::to_value(&req).unwrap(),
+            serde_json::json!({"name": "amber-falcon"})
+        );
+    }
 }

crates/maestro-protocol/src/routes.rs

@@ -0,0 +1,218 @@
+//! The daemon's `/api/*` surface: paths, and the scheme swap every client
+//! needs to reach the WebSocket endpoints.
+//!
+//! Everything that knows what the daemon's URLs look like lives here.
+
+use uuid::Uuid;
+
+/// Prefix every daemon route shares. `maestro-web` uses it to decide whether a
+/// request is proxied to the daemon or served from the SPA bundle.
+pub const API_PREFIX: &str = "/api";
+
+/// `GET` list / `POST` spawn.
+pub const SESSIONS: &str = "/api/sessions";
+/// `GET` daemon identity, version, and spawn presets.
+pub const INFO: &str = "/api/info";
+/// `GET` one directory's immediate subdirectories. Takes a `path` query param.
+pub const DIRS: &str = "/api/dirs";
+/// `GET` spawn history.
+pub const RECENT_DIRS: &str = "/api/recent-dirs";
+/// `GET` discovered git repositories and worktrees, newest activity first.
+pub const PROJECTS: &str = "/api/projects";
+/// `GET` the enclosing repository of a path. Takes a `path` query param.
+pub const GITROOT: &str = "/api/gitroot";
+/// `GET` one repository's local branches. Takes a `path` query param.
+pub const BRANCHES: &str = "/api/branches";
+/// `GET` a batch of generated session handles (#53). Takes a `count` query
+/// param (default 1, capped at [`maestro_names`]' batch cap).
+pub const NAMES: &str = "/api/names";
+/// `WS` catalog snapshot + session deltas.
+pub const EVENTS: &str = "/api/events";
+
+/// Name of the query parameter [`DIRS`], [`GITROOT`], and [`BRANCHES`] take.
+pub const PATH_QUERY: &str = "path";
+
+/// Name of the query parameter [`NAMES`] takes.
+pub const COUNT_QUERY: &str = "count";
+
+/// Name of the boolean query parameter `DELETE /api/sessions/:id` takes (#81).
+/// `force=true` overrides the kill refusal and leaves the worktree on disk.
+pub const FORCE_QUERY: &str = "force";
+
+/// `DELETE /api/sessions/:id`.
+pub fn session(id: Uuid) -> String {
+    format!("{SESSIONS}/{id}")
+}
+
+/// `POST /api/sessions/:id/activity` (#105): an agent reports its own state.
+pub fn session_activity(id: Uuid) -> String {
+    format!("{SESSIONS}/{id}/activity")
+}
+
+/// `WS /api/attach/:id` — raw PTY bytes.
+pub fn attach(id: Uuid) -> String {
+    format!("{API_PREFIX}/attach/{id}")
+}
+
+/// Axum-style patterns for the two parameterised routes, so the server
+/// registers the same paths [`session`] and [`attach`] build.
+pub mod patterns {
+    pub const SESSION: &str = "/api/sessions/:id";
+    pub const SESSION_ACTIVITY: &str = "/api/sessions/:id/activity";
+    pub const ATTACH: &str = "/api/attach/:id";
+}
+
+/// A daemon base URL that could not be turned into a WebSocket base.
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+pub enum UrlError {
+    #[error("daemon url has no supported scheme (want http/https/ws/wss): {0}")]
+    UnsupportedScheme(String),
+}
+
+/// Strip a trailing slash so `{base}{path}` never doubles up.
+pub fn normalize_base(base: &str) -> &str {
+    base.trim_end_matches('/')
+}
+
+/// Join a daemon base URL and one of this module's paths.
+pub fn http_url(base: &str, path: &str) -> String {
+    format!("{}{}", normalize_base(base), path)
+}
+
+/// Swap an HTTP base URL for its WebSocket equivalent.
+///
+/// `http://` becomes `ws://`, `https://` becomes `wss://`, and a base that is
+/// already `ws://`/`wss://` passes through. Anything else is an error — a
+/// scheme-less base would otherwise produce a URL that fails much later, at
+/// connect time, with nothing pointing back at the configuration that caused
+/// it.
+pub fn ws_base(http_base: &str) -> Result<String, UrlError> {
+    let base = normalize_base(http_base);
+    if let Some(rest) = base.strip_prefix("https://") {
+        Ok(format!("wss://{rest}"))
+    } else if let Some(rest) = base.strip_prefix("http://") {
+        Ok(format!("ws://{rest}"))
+    } else if base.starts_with("wss://") || base.starts_with("ws://") {
+        Ok(base.to_string())
+    } else {
+        Err(UrlError::UnsupportedScheme(http_base.to_string()))
+    }
+}
+
+/// Full `WS /api/events` URL for a daemon reachable at `http_base`.
+pub fn events_url(http_base: &str) -> Result<String, UrlError> {
+    Ok(format!("{}{}", ws_base(http_base)?, EVENTS))
+}
+
+/// Full `WS /api/attach/:id` URL for a daemon reachable at `http_base`.
+pub fn attach_url(http_base: &str, id: Uuid) -> Result<String, UrlError> {
+    Ok(format!("{}{}", ws_base(http_base)?, attach(id)))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn id() -> Uuid {
+        Uuid::parse_str("6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50").unwrap()
+    }
+
+    #[test]
+    fn ws_base_swaps_http_and_https() {
+        assert_eq!(
+            ws_base("http://127.0.0.1:7070").unwrap(),
+            "ws://127.0.0.1:7070"
+        );
+        assert_eq!(
+            ws_base("https://laptop.lan:7070").unwrap(),
+            "wss://laptop.lan:7070"
+        );
+    }
+
+    #[test]
+    fn ws_base_passes_through_websocket_schemes() {
+        assert_eq!(ws_base("ws://10.0.0.1:7070").unwrap(), "ws://10.0.0.1:7070");
+        assert_eq!(
+            ws_base("wss://10.0.0.1:7070").unwrap(),
+            "wss://10.0.0.1:7070"
+        );
+    }
+
+    #[test]
+    fn ws_base_rejects_an_unknown_scheme() {
+        assert_eq!(
+            ws_base("127.0.0.1:7070"),
+            Err(UrlError::UnsupportedScheme("127.0.0.1:7070".into()))
+        );
+        assert!(ws_base("ftp://host:7070").is_err());
+    }
+
+    #[test]
+    fn trailing_slashes_never_double_up() {
+        assert_eq!(ws_base("http://host:7070/").unwrap(), "ws://host:7070");
+        assert_eq!(
+            http_url("http://host:7070/", SESSIONS),
+            "http://host:7070/api/sessions"
+        );
+        assert_eq!(
+            events_url("http://host:7070/").unwrap(),
+            "ws://host:7070/api/events"
+        );
+    }
+
+    #[test]
+    fn builds_per_session_paths() {
+        assert_eq!(
+            session(id()),
+            "/api/sessions/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50"
+        );
+        assert_eq!(
+            session_activity(id()),
+            "/api/sessions/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50/activity"
+        );
+        assert_eq!(
+            attach(id()),
+            "/api/attach/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50"
+        );
+        assert_eq!(
+            attach_url("https://laptop.lan:7070", id()).unwrap(),
+            "wss://laptop.lan:7070/api/attach/6f1a7c0e-0f5e-4a2b-9a3d-6b1c2d3e4f50"
+        );
+    }
+
+    /// The server registers `patterns::*` while clients call `session`/`attach`;
+    /// nothing but this test keeps the two spellings in step.
+    #[test]
+    fn patterns_and_builders_agree() {
+        assert_eq!(
+            patterns::SESSION.trim_end_matches(":id"),
+            session(id()).trim_end_matches(&id().to_string())
+        );
+        assert_eq!(
+            patterns::SESSION_ACTIVITY.trim_end_matches(":id/activity"),
+            session(id()).trim_end_matches(&id().to_string())
+        );
+        assert_eq!(
+            patterns::ATTACH.trim_end_matches(":id"),
+            attach(id()).trim_end_matches(&id().to_string())
+        );
+    }
+
+    #[test]
+    fn every_route_sits_under_the_api_prefix() {
+        for path in [
+            SESSIONS,
+            INFO,
+            DIRS,
+            RECENT_DIRS,
+            PROJECTS,
+            GITROOT,
+            BRANCHES,
+            NAMES,
+            EVENTS,
+        ] {
+            assert!(path.starts_with(API_PREFIX), "{path} escapes {API_PREFIX}");
+        }
+        assert!(attach(id()).starts_with(API_PREFIX));
+    }
+}

crates/maestro-testing/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "maestro-testing"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+publish.workspace = true
+description = "In-memory Maestro daemon for tests: the real /api/* surface without tmux"
+
+[dependencies]
+axum.workspace = true
+chrono.workspace = true
+futures-util.workspace = true
+maestro-protocol = { workspace = true, features = ["client"] }
+serde.workspace = true
+serde_json.workspace = true
+tokio.workspace = true
+uuid.workspace = true

crates/maestro-testing/src/lib.rs

@@ -0,0 +1,368 @@
+//! An in-memory Maestro daemon for tests.
+//!
+//! Serves the real `/api/*` surface from `maestro-protocol` types, backed by a
+//! `Vec<Session>` instead of tmux. Use it whenever the subject under test is a
+//! client — request building, error decoding, the catalog reducer, the proxy —
+//! rather than session management itself. Tests that genuinely need tmux belong
+//! in `maestro-e2e` against a real daemon.
+
+#![deny(missing_debug_implementations)]
+
+use std::collections::HashMap;
+use std::net::{Ipv4Addr, SocketAddr};
+use std::sync::{Arc, Mutex};
+
+use axum::extract::ws::{Message, WebSocket, WebSocketUpgrade};
+use axum::extract::{Path, Query, State};
+use axum::http::StatusCode;
+use axum::response::{IntoResponse, Response};
+use axum::routing::{any, delete, get};
+use axum::{Json, Router};
+use chrono::Utc;
+use futures_util::{SinkExt, StreamExt};
+use maestro_protocol::{
+    routes, ApiError, CatalogEvent, CreateSessionRequest, DaemonClient, DaemonInfo, DirListing,
+    GitRoot, RecentDirs, Session, SessionStatus, PROTOCOL_VERSION,
+};
+use tokio::net::TcpListener;
+use tokio::sync::{broadcast, oneshot};
+use uuid::Uuid;
+
+/// Build a plausible `Session` for a test to hand to [`MockDaemon::add_session`].
+pub fn session(id: Uuid, cwd: &str, command: &str) -> Session {
+    Session {
+        id,
+        cwd: cwd.into(),
+        command: command.into(),
+        env: HashMap::new(),
+        metadata: HashMap::new(),
+        worktree: None,
+        status: SessionStatus::Running,
+        created_at: Utc::now(),
+        foreground: None,
+        activity: Default::default(),
+        activity_detail: None,
+        last_activity_at: Utc::now(),
+        activity_since: chrono::Utc::now(),
+        current_cwd: None,
+        blocked_work: None,
+    }
+}
+
+#[derive(Debug, Default)]
+struct Inner {
+    sessions: Vec<Session>,
+    info: Option<DaemonInfo>,
+    /// When set, every route answers with this instead of its normal response.
+    forced_error: Option<(u16, ApiError)>,
+}
+
+#[derive(Clone)]
+struct AppState {
+    inner: Arc<Mutex<Inner>>,
+    events: broadcast::Sender<CatalogEvent>,
+}
+
+impl std::fmt::Debug for AppState {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("AppState").finish_non_exhaustive()
+    }
+}
+
+/// A running mock daemon. Shuts down when dropped.
+#[derive(Debug)]
+pub struct MockDaemon {
+    addr: SocketAddr,
+    state: AppState,
+    _shutdown: oneshot::Sender<()>,
+}
+
+impl MockDaemon {
+    pub async fn start() -> Self {
+        let state = AppState {
+            inner: Arc::new(Mutex::new(Inner::default())),
+            events: broadcast::channel(64).0,
+        };
+        let app = Router::new()
+            .route(routes::SESSIONS, get(list_sessions).post(create_session))
+            .route(routes::patterns::SESSION, delete(kill_session))
+            .route(routes::INFO, get(daemon_info))
+            .route(routes::DIRS, get(list_dir))
+            .route(routes::RECENT_DIRS, get(recent_dirs))
+            .route(routes::GITROOT, get(git_root))
+            .route(routes::EVENTS, any(events_ws))
+            .route(routes::patterns::ATTACH, any(attach_ws))
+            .with_state(state.clone());
+
+        let listener = TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, 0)))
+            .await
+            .expect("bind");
+        let addr = listener.local_addr().expect("local_addr");
+        let (tx, rx) = oneshot::channel::<()>();
+        tokio::spawn(async move {
+            let _ = axum::serve(listener, app)
+                .with_graceful_shutdown(async move {
+                    let _ = rx.await;
+                })
+                .await;
+        });
+
+        Self {
+            addr,
+            state,
+            _shutdown: tx,
+        }
+    }
+
+    pub fn addr(&self) -> SocketAddr {
+        self.addr
+    }
+
+    pub fn http_base(&self) -> String {
+        format!("http://{}", self.addr)
+    }
+
+    /// A client bound to this daemon.
+    pub fn client(&self) -> DaemonClient {
+        DaemonClient::new(self.http_base())
+    }
+
+    /// Add a session and announce it, as a real spawn would.
+    pub fn add_session(&self, session: Session) {
+        self.state
+            .inner
+            .lock()
+            .expect("poisoned")
+            .sessions
+            .push(session.clone());
+        let _ = self
+            .state
+            .events
+            .send(CatalogEvent::SessionAdded { session });
+    }
+
+    /// Remove a session and announce it.
+    pub fn remove_session(&self, id: Uuid) {
+        self.state
+            .inner
+            .lock()
+            .expect("poisoned")
+            .sessions
+            .retain(|s| s.id != id);
+        let _ = self.state.events.send(CatalogEvent::SessionRemoved { id });
+    }
+
+    pub fn set_info(&self, info: DaemonInfo) {
+        self.state.inner.lock().expect("poisoned").info = Some(info);
+    }
+
+    /// Make every route answer with this error, so clients' failure paths — and
+    /// their [`ApiError`] decoding — can be exercised.
+    pub fn force_error(&self, status: u16, code: &str, message: &str) {
+        self.state.inner.lock().expect("poisoned").forced_error =
+            Some((status, ApiError::new(code, message)));
+    }
+
+    pub fn clear_error(&self) {
+        self.state.inner.lock().expect("poisoned").forced_error = None;
+    }
+
+    pub fn session_count(&self) -> usize {
+        self.state.inner.lock().expect("poisoned").sessions.len()
+    }
+}
+
+fn forced(state: &AppState) -> Option<Response> {
+    let guard = state.inner.lock().expect("poisoned");
+    guard.forced_error.as_ref().map(|(status, body)| {
+        (
+            StatusCode::from_u16(*status).expect("valid status"),
+            Json(body.clone()),
+        )
+            .into_response()
+    })
+}
+
+async fn list_sessions(State(s): State<AppState>) -> Response {
+    if let Some(r) = forced(&s) {
+        return r;
+    }
+    let sessions = s.inner.lock().expect("poisoned").sessions.clone();
+    Json(sessions).into_response()
+}
+
+async fn create_session(
+    State(s): State<AppState>,
+    Json(req): Json<CreateSessionRequest>,
+) -> Response {
+    if let Some(r) = forced(&s) {
+        return r;
+    }
+    let mut created = session(Uuid::new_v4(), &req.cwd.to_string_lossy(), &req.command);
+    created.env = req.env;
+    created.metadata = req.metadata;
+    s.inner
+        .lock()
+        .expect("poisoned")
+        .sessions
+        .push(created.clone());
+    let _ = s.events.send(CatalogEvent::SessionAdded {
+        session: created.clone(),
+    });
+    Json(created).into_response()
+}
+
+async fn kill_session(State(s): State<AppState>, Path(id): Path<Uuid>) -> Response {
+    if let Some(r) = forced(&s) {
+        return r;
+    }
+    let existed = {
+        let mut guard = s.inner.lock().expect("poisoned");
+        let before = guard.sessions.len();
+        guard.sessions.retain(|x| x.id != id);
+        guard.sessions.len() != before
+    };
+    if !existed {
+        return (
+            StatusCode::NOT_FOUND,
+            Json(ApiError::new("not_found", "no such session on this daemon")),
+        )
+            .into_response();
+    }
+    let _ = s.events.send(CatalogEvent::SessionRemoved { id });
+    StatusCode::NO_CONTENT.into_response()
+}
+
+async fn daemon_info(State(s): State<AppState>) -> Response {
+    if let Some(r) = forced(&s) {
+        return r;
+    }
+    let info = s
+        .inner
+        .lock()
+        .expect("poisoned")
+        .info
+        .clone()
+        .unwrap_or_else(|| DaemonInfo {
+            hostname: "mock-host".into(),
+            version: PROTOCOL_VERSION.into(),
+            home_dir: "/home/mock".into(),
+            presets: Vec::new(),
+        });
+    Json(info).into_response()
+}
+
+async fn list_dir(State(s): State<AppState>, Query(q): Query<PathQuery>) -> Response {
+    if let Some(r) = forced(&s) {
+        return r;
+    }
+    Json(DirListing {
+        path: q.path.into(),
+        entries: Vec::new(),
+        truncated: false,
+    })
+    .into_response()
+}
+
+async fn recent_dirs(State(s): State<AppState>) -> Response {
+    if let Some(r) = forced(&s) {
+        return r;
+    }
+    Json(RecentDirs {
+        dirs: Vec::new(),
+        truncated: false,
+    })
+    .into_response()
+}
+
+async fn git_root(State(s): State<AppState>, Query(_q): Query<PathQuery>) -> Response {
+    if let Some(r) = forced(&s) {
+        return r;
+    }
+    Json(GitRoot { root: None }).into_response()
+}
+
+/// Snapshot on connect, then live deltas — the same contract the daemon offers.
+async fn events_ws(State(s): State<AppState>, ws: WebSocketUpgrade) -> Response {
+    ws.on_upgrade(move |socket| events_loop(s, socket))
+}
+
+async fn events_loop(s: AppState, socket: WebSocket) {
+    let (mut sink, mut stream) = socket.split();
+    let mut rx = s.events.subscribe();
+    let snapshot = CatalogEvent::Snapshot {
+        sessions: s.inner.lock().expect("poisoned").sessions.clone(),
+    };
+    if sink
+        .send(Message::Text(
+            serde_json::to_string(&snapshot).expect("encode"),
+        ))
+        .await
+        .is_err()
+    {
+        return;
+    }
+    loop {
+        tokio::select! {
+            ev = rx.recv() => {
+                let Ok(ev) = ev else { break };
+                let text = serde_json::to_string(&ev).expect("encode");
+                if sink.send(Message::Text(text)).await.is_err() {
+                    break;
+                }
+            }
+            frame = stream.next() => {
+                match frame {
+                    None | Some(Err(_)) | Some(Ok(Message::Close(_))) => break,
+                    Some(Ok(_)) => {}
+                }
+            }
+        }
+    }
+}
+
+/// Echoes whatever it is sent, so a client's PTY plumbing can be exercised.
+async fn attach_ws(
+    State(s): State<AppState>,
+    Path(id): Path<Uuid>,
+    ws: WebSocketUpgrade,
+) -> Response {
+    let known = s
+        .inner
+        .lock()
+        .expect("poisoned")
+        .sessions
+        .iter()
+        .any(|x| x.id == id);
+    if !known {
+        return (
+            StatusCode::NOT_FOUND,
+            Json(ApiError::new("not_found", "no such session on this daemon")),
+        )
+            .into_response();
+    }
+    ws.on_upgrade(|mut socket| async move {
+        while let Some(Ok(msg)) = socket.next().await {
+            match msg {
+                Message::Binary(b) => {
+                    if socket.send(Message::Binary(b)).await.is_err() {
+                        break;
+                    }
+                }
+                Message::Text(t) => {
+                    if socket.send(Message::Text(t)).await.is_err() {
+                        break;
+                    }
+                }
+                Message::Close(_) => break,
+                _ => {}
+            }
+        }
+    })
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct PathQuery {
+    #[serde(default)]
+    path: String,
+}

crates/maestro-tui/Cargo.toml

@@ -8,11 +8,12 @@ publish.workspace = true
 description = "Terminal UI client over the local maestro daemon's `/api/*` surface."
 
 [dependencies]
+chrono.workspace = true
 clap.workspace = true
 crossterm.workspace = true
 futures-util.workspace = true
 maestro-config.workspace = true
-maestro-protocol.workspace = true
+maestro-protocol = { workspace = true, features = ["client"] }
 ratatui.workspace = true
 reqwest.workspace = true
 serde_json.workspace = true
@@ -24,6 +25,7 @@ uuid.workspace = true
 vt100.workspace = true
 
 [dev-dependencies]
+maestro-testing.workspace = true
 axum.workspace = true
 chrono.workspace = true
 tokio = { workspace = true, features = ["sync", "time", "macros", "rt-multi-thread", "net"] }

crates/maestro-tui/src/action.rs

@@ -31,22 +31,26 @@ pub enum Action {
     FocusSidebar,
     FocusPane(Direction),
 
+    // Session scrollback
+    ScrollPanePageUp,
+    ScrollPanePageDown,
+
     // Sidebar highlight movement
     SidebarNext,
     SidebarPrev,
+    ToggleSidebarGroup,
 
     // Catalog actions on the highlighted sidebar row
     AttachHighlighted,
     ToggleAttachHighlighted,
-    OpenSpawnModal,
+    NewDraftPane,
+    /// Fast-forward spawn (#67): spawn immediately with every default
+    /// resolved; unresolvable defaults open a pre-filled draft instead.
+    FastForwardSpawn,
     KillHighlighted,
-
-    // Tabs
-    NewTab,
-    CloseTab,
-    NextTab,
-    PrevTab,
-    GotoTab(u8),
+    /// Rename the highlighted session (#125): opens a prompt pre-filled with
+    /// its current name.
+    RenameHighlighted,
 
     // Chrome
     ToggleSidebar,
@@ -65,8 +69,39 @@ pub enum ActionParseError {
 }
 
 impl Action {
-    /// Parse a canonical action string like `"EnterInsert"`, `"FocusPane(Left)"`,
-    /// or `"GotoTab(3)"`.
+    /// Plain-language label for the in-app help menu. Configuration keeps the
+    /// stable enum spelling; operators should not have to decode it.
+    pub fn help_label(&self) -> String {
+        match self {
+            Action::Noop => "Do nothing".into(),
+            Action::EnterInsert => "Send keys to session".into(),
+            Action::LeaveInsert => "Return to sidebar".into(),
+            Action::FocusSidebar => "Focus sidebar".into(),
+            Action::FocusPane(direction) => {
+                format!(
+                    "Focus session pane ({})",
+                    format!("{direction:?}").to_lowercase()
+                )
+            }
+            Action::ScrollPanePageUp => "Scroll session up one page".into(),
+            Action::ScrollPanePageDown => "Scroll session down one page".into(),
+            Action::SidebarNext => "Select next sidebar item".into(),
+            Action::SidebarPrev => "Select previous sidebar item".into(),
+            Action::ToggleSidebarGroup => "Expand or collapse directory".into(),
+            Action::AttachHighlighted => "Open selected item".into(),
+            Action::ToggleAttachHighlighted => "Open selected item".into(),
+            Action::NewDraftPane => "Create a session".into(),
+            Action::FastForwardSpawn => "Create session with defaults".into(),
+            Action::KillHighlighted => "Kill selected session".into(),
+            Action::RenameHighlighted => "Rename selected session".into(),
+            Action::ToggleSidebar => "Show or hide sidebar".into(),
+            Action::ShowHelp => "Show help".into(),
+            Action::Quit => "Quit Maestro".into(),
+        }
+    }
+
+    /// Parse a canonical action string like `"EnterInsert"` or
+    /// `"FocusPane(Left)"`.
     pub fn parse(s: &str) -> Result<Self, ActionParseError> {
         let s = s.trim();
         match s {
@@ -74,16 +109,17 @@ impl Action {
             "EnterInsert" => return Ok(Action::EnterInsert),
             "LeaveInsert" => return Ok(Action::LeaveInsert),
             "FocusSidebar" => return Ok(Action::FocusSidebar),
+            "ScrollPanePageUp" => return Ok(Action::ScrollPanePageUp),
+            "ScrollPanePageDown" => return Ok(Action::ScrollPanePageDown),
             "SidebarNext" => return Ok(Action::SidebarNext),
             "SidebarPrev" => return Ok(Action::SidebarPrev),
+            "ToggleSidebarGroup" => return Ok(Action::ToggleSidebarGroup),
             "AttachHighlighted" => return Ok(Action::AttachHighlighted),
             "ToggleAttachHighlighted" => return Ok(Action::ToggleAttachHighlighted),
-            "OpenSpawnModal" => return Ok(Action::OpenSpawnModal),
+            "NewDraftPane" => return Ok(Action::NewDraftPane),
+            "FastForwardSpawn" => return Ok(Action::FastForwardSpawn),
             "KillHighlighted" => return Ok(Action::KillHighlighted),
-            "NewTab" => return Ok(Action::NewTab),
-            "CloseTab" => return Ok(Action::CloseTab),
-            "NextTab" => return Ok(Action::NextTab),
-            "PrevTab" => return Ok(Action::PrevTab),
+            "RenameHighlighted" => return Ok(Action::RenameHighlighted),
             "ToggleSidebar" => return Ok(Action::ToggleSidebar),
             "ShowHelp" => return Ok(Action::ShowHelp),
             "Quit" => return Ok(Action::Quit),
@@ -104,13 +140,6 @@ impl Action {
                 })?;
                 Ok(Action::FocusPane(dir))
             }
-            "GotoTab" => {
-                let n: u8 = arg.parse().map_err(|_| ActionParseError::BadArg {
-                    action: name.to_string(),
-                    detail: format!("expected u8 0..=255, got {arg:?}"),
-                })?;
-                Ok(Action::GotoTab(n))
-            }
             _ => Err(ActionParseError::Unknown(name.to_string())),
         }
     }
@@ -130,7 +159,6 @@ impl fmt::Display for Action {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
             Action::FocusPane(d) => write!(f, "FocusPane({d:?})"),
-            Action::GotoTab(n) => write!(f, "GotoTab({n})"),
             other => write!(f, "{other:?}"),
         }
     }
@@ -147,6 +175,13 @@ mod tests {
         assert_eq!(Action::parse("  Noop  ").unwrap(), Action::Noop);
     }
 
+    #[test]
+    fn help_labels_are_plain_language() {
+        assert_eq!(Action::EnterInsert.help_label(), "Send keys to session");
+        assert_eq!(Action::AttachHighlighted.help_label(), "Open selected item");
+        assert!(!Action::NewDraftPane.help_label().contains("NewDraftPane"));
+    }
+
     #[test]
     fn parses_focus_pane_directions() {
         assert_eq!(
@@ -159,12 +194,6 @@ mod tests {
         );
     }
 
-    #[test]
-    fn parses_goto_tab() {
-        assert_eq!(Action::parse("GotoTab(3)").unwrap(), Action::GotoTab(3));
-        assert_eq!(Action::parse("GotoTab(0)").unwrap(), Action::GotoTab(0));
-    }
-
     #[test]
     fn rejects_unknown_action() {
         let err = Action::parse("Frobnicate").unwrap_err();
@@ -179,34 +208,57 @@ mod tests {
         );
     }
 
-    #[test]
-    fn rejects_non_numeric_tab_arg() {
-        let err = Action::parse("GotoTab(abc)").unwrap_err();
-        assert!(matches!(err, ActionParseError::BadArg { ref action, .. } if action == "GotoTab"));
-    }
-
-    #[test]
-    fn rejects_overflow_tab_arg() {
-        let err = Action::parse("GotoTab(9999)").unwrap_err();
-        assert!(matches!(err, ActionParseError::BadArg { .. }));
-    }
-
     #[test]
     fn rejects_unclosed_paren() {
-        let err = Action::parse("GotoTab(3").unwrap_err();
-        assert_eq!(err, ActionParseError::Malformed("GotoTab(3".into()));
+        let err = Action::parse("FocusPane(Left").unwrap_err();
+        assert_eq!(err, ActionParseError::Malformed("FocusPane(Left".into()));
+    }
+
+    /// The fast-forward pair sits next to the draft-pane key (#67).
+    #[test]
+    fn fast_forward_spawn_round_trips() {
+        assert_eq!(
+            Action::parse("FastForwardSpawn").unwrap(),
+            Action::FastForwardSpawn
+        );
+        assert_eq!(Action::FastForwardSpawn.to_string(), "FastForwardSpawn");
+    }
+
+    #[test]
+    fn rename_action_round_trips() {
+        assert_eq!(
+            Action::parse("RenameHighlighted").unwrap(),
+            Action::RenameHighlighted
+        );
+        assert_eq!(Action::RenameHighlighted.to_string(), "RenameHighlighted");
+        assert_eq!(
+            Action::RenameHighlighted.help_label(),
+            "Rename selected session"
+        );
     }
 
     #[test]
     fn display_round_trips() {
         for a in [
             Action::EnterInsert,
+            Action::RenameHighlighted,
             Action::Quit,
+            Action::NewDraftPane,
+            Action::ScrollPanePageDown,
             Action::FocusPane(Direction::Right),
-            Action::GotoTab(7),
         ] {
             let s = a.to_string();
             assert_eq!(Action::parse(&s).unwrap(), a, "round-trip for {a:?}");
         }
     }
+
+    /// The spawn modal is gone (issue #63); its old action string must not
+    /// resolve to anything.
+    #[test]
+    fn the_removed_spawn_modal_action_no_longer_parses() {
+        assert_eq!(
+            Action::parse("OpenSpawnModal").unwrap_err(),
+            ActionParseError::Unknown("OpenSpawnModal".into())
+        );
+    }
 }

crates/maestro-tui/src/catalog.rs

@@ -188,12 +188,16 @@ mod tests {
             cwd: std::path::PathBuf::from("/tmp"),
             env: Default::default(),
             metadata: Default::default(),
+            worktree: None,
             status: SessionStatus::Running,
             created_at: Utc::now(),
             foreground: None,
             activity: Default::default(),
+            activity_detail: None,
             last_activity_at: chrono::Utc::now(),
+            activity_since: chrono::Utc::now(),
             current_cwd: None,
+            blocked_work: None,
         }
     }
 

crates/maestro-tui/src/config.rs

@@ -8,13 +8,15 @@
 
 use std::time::Duration;
 
-use maestro_config::TuiSection;
+use maestro_config::{TuiSection, TuiTheme};
 
 use crate::input::InputKey;
 use crate::keymap::{Keymap, KeymapError, Mode};
+use crate::palette::Palette;
 
 #[derive(Debug)]
 pub struct TuiConfig {
+    pub palette: Palette,
     pub leader: InputKey,
     pub chord_timeout: Duration,
     pub keymap: Keymap,
@@ -38,28 +40,31 @@ pub enum TuiConfigError {
 const DEFAULT_NORMAL: &[(&str, &str)] = &[
     // Mode
     ("i", "EnterInsert"),
-    // Sidebar nav
+    // Sidebar navigation
     ("j", "SidebarNext"),
     ("k", "SidebarPrev"),
     ("down", "SidebarNext"),
     ("up", "SidebarPrev"),
+    ("c", "ToggleSidebarGroup"),
     // Catalog actions
     ("enter", "AttachHighlighted"),
-    ("s", "OpenSpawnModal"),
+    ("s", "NewDraftPane"),
+    // Fast-forward spawn (#67): the draft-pane key's neighbour does the same
+    // thing with every default resolved and no form.
+    ("S", "FastForwardSpawn"),
     ("x", "KillHighlighted"),
-    // Tabs
-    ("ctrl-t", "NewTab"),
-    ("g t", "NextTab"),
-    ("g T", "PrevTab"),
+    ("r", "RenameHighlighted"),
     // Focus
     ("ctrl-w h", "FocusSidebar"),
+    // Session scrollback
+    ("pageup", "ScrollPanePageUp"),
+    ("pagedown", "ScrollPanePageDown"),
     // Chrome
     ("ctrl-w b", "ToggleSidebar"),
     ("?", "ShowHelp"),
     ("ctrl-w q", "Quit"),
     // Mouse
     ("mouse:dblclick(sidebar-row)", "AttachHighlighted"),
-    ("mouse:click(tab)", "NextTab"),
 ];
 
 /// Default Insert-mode bindings. Empty by default — the only Insert binding
@@ -72,6 +77,20 @@ impl TuiConfig {
     /// field of the loaded `MaestroConfigFile`). The shipped defaults are
     /// applied first, then user overrides on top.
     pub fn load(section: &TuiSection) -> Result<Self, TuiConfigError> {
+        let palette = match section.theme.unwrap_or(TuiTheme::Dark) {
+            TuiTheme::Dark => Palette::DARK,
+            TuiTheme::Light => Palette::LIGHT,
+            TuiTheme::Ansi => Palette::ANSI,
+            TuiTheme::SolarizedDark => Palette::SOLARIZED_DARK,
+            TuiTheme::SolarizedLight => Palette::SOLARIZED_LIGHT,
+            TuiTheme::Catppuccin => Palette::CATPPUCCIN,
+            TuiTheme::GithubDark => Palette::GITHUB_DARK,
+            TuiTheme::GithubLight => Palette::GITHUB_LIGHT,
+            TuiTheme::TokyoNight => Palette::TOKYO_NIGHT,
+            TuiTheme::Gruvbox => Palette::GRUVBOX,
+            TuiTheme::Nord => Palette::NORD,
+            TuiTheme::Dracula => Palette::DRACULA,
+        };
         let leader_str = section.leader.as_deref().unwrap_or("ctrl-a");
         let leader = InputKey::parse(leader_str)
             .map_err(|_| TuiConfigError::BadLeader(leader_str.to_string()))?;
@@ -127,6 +146,7 @@ impl TuiConfig {
         }
 
         Ok(TuiConfig {
+            palette,
             leader,
             chord_timeout,
             keymap,
@@ -139,6 +159,37 @@ impl TuiConfig {
 mod tests {
     use super::*;
     use crate::action::Action;
+    use maestro_config::{TuiSection, TuiTheme};
+
+    #[test]
+    fn absent_theme_selects_the_dark_default() {
+        let cfg = TuiConfig::load(&TuiSection::default()).unwrap();
+        assert_eq!(cfg.palette, Palette::DARK);
+    }
+
+    #[test]
+    fn named_themes_select_the_matching_complete_palette() {
+        for (theme, expected) in [
+            (TuiTheme::Dark, Palette::DARK),
+            (TuiTheme::Light, Palette::LIGHT),
+            (TuiTheme::Ansi, Palette::ANSI),
+            (TuiTheme::SolarizedDark, Palette::SOLARIZED_DARK),
+            (TuiTheme::SolarizedLight, Palette::SOLARIZED_LIGHT),
+            (TuiTheme::Catppuccin, Palette::CATPPUCCIN),
+            (TuiTheme::GithubDark, Palette::GITHUB_DARK),
+            (TuiTheme::GithubLight, Palette::GITHUB_LIGHT),
+            (TuiTheme::TokyoNight, Palette::TOKYO_NIGHT),
+            (TuiTheme::Gruvbox, Palette::GRUVBOX),
+            (TuiTheme::Nord, Palette::NORD),
+            (TuiTheme::Dracula, Palette::DRACULA),
+        ] {
+            let section = TuiSection {
+                theme: Some(theme),
+                ..Default::default()
+            };
+            assert_eq!(TuiConfig::load(&section).unwrap().palette, expected);
+        }
+    }
 
     #[test]
     fn defaults_cover_core_actions() {
@@ -152,8 +203,12 @@ mod tests {
             Some(Action::AttachHighlighted),
         );
         assert_eq!(
-            cfg.keymap.resolve(Mode::Normal, "g t"),
-            Some(Action::NextTab),
+            cfg.keymap.resolve(Mode::Normal, "s"),
+            Some(Action::NewDraftPane),
+        );
+        assert_eq!(
+            cfg.keymap.resolve(Mode::Normal, "S"),
+            Some(Action::FastForwardSpawn),
         );
     }
 
@@ -222,6 +277,26 @@ mod tests {
         assert!(s.contains("ctrl-glorb"), "diagnostic: {s}");
     }
 
+    /// Regression for #70: the previous canonical form of a real Shift+S
+    /// keypress was `"shift-S"`, which the default `"S"` binding never
+    /// matched. Drive the actual crossterm event, not the binding string,
+    /// so the dead-key bug can't come back unnoticed.
+    #[test]
+    fn real_shift_s_keypress_resolves_to_fast_forward_spawn() {
+        use crossterm::event::{Event as CtEvent, KeyCode, KeyEvent, KeyModifiers};
+
+        use crate::input::{canonicalise, Region};
+
+        let cfg = TuiConfig::load(&TuiSection::default()).unwrap();
+        let ev = CtEvent::Key(KeyEvent::new(KeyCode::Char('S'), KeyModifiers::SHIFT));
+        let key = canonicalise(&ev, |_, _| Region::Unknown).expect("key event canonicalises");
+
+        assert_eq!(
+            cfg.keymap.resolve(Mode::Normal, &key.canonical()),
+            Some(Action::FastForwardSpawn),
+        );
+    }
+
     #[test]
     fn custom_chord_timeout_is_applied() {
         let mut section = TuiSection::default();

crates/maestro-tui/src/fast_forward.rs

@@ -0,0 +1,282 @@
+//! Fast-forward spawn (#67): one keystroke, every default resolved, no form.
+//!
+//! The defaults mirror what a draft pane would settle on after the operator
+//! picked the most recent project and kept their hands off everything else:
+//! its last command (or the first non-custom preset), a freshly generated
+//! name, and a worktree with a branch named after that name. Any default
+//! that cannot be resolved — no projects yet, no command, no generated
+//! name — downgrades the keystroke to a draft pane pre-filled with whatever
+//! did resolve ([`FastForwardDefaults::apply_to_draft`]).
+
+use std::path::PathBuf;
+
+use chrono::{DateTime, Utc};
+use maestro_protocol::{CreateSessionRequest, Project, SpawnPreset, WorktreeSpec};
+
+use crate::draft::DraftPane;
+
+/// What one fast-forward keystroke resolved. Every field optional: `None`
+/// anywhere means "open a draft instead of spawning".
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FastForwardDefaults {
+    pub project: Option<Project>,
+    pub command: Option<String>,
+    pub name: Option<String>,
+}
+
+/// Resolve the fast-forward defaults from the daemon's answers. `name` is
+/// `None` when `/api/names` yielded nothing; `presets` may be empty (the
+/// caller falls back to the built-ins it already has).
+pub fn resolve(
+    projects: &[Project],
+    presets: &[SpawnPreset],
+    name: Option<String>,
+    now: DateTime<Utc>,
+) -> FastForwardDefaults {
+    let project = crate::projects::sort_projects(projects.to_vec(), now)
+        .into_iter()
+        .next();
+    let command = project
+        .as_ref()
+        .and_then(|p| p.last_command.clone())
+        .filter(|c| !c.trim().is_empty())
+        .or_else(|| {
+            presets
+                .iter()
+                .find(|p| !p.command.is_empty())
+                .map(|p| p.command.clone())
+        });
+    FastForwardDefaults {
+        project,
+        command,
+        name,
+    }
+}
+
+impl FastForwardDefaults {
+    /// The spawn request when *every* default resolved: worktree on, new
+    /// branch named after the generated session name, base repo from the
+    /// scan (`None` means the project is itself a main checkout).
+    pub fn build_request(&self) -> Option<CreateSessionRequest> {
+        let project = self.project.as_ref()?;
+        let command = self.command.as_deref()?.trim();
+        let name = self.name.as_deref()?;
+        if command.is_empty() || name.is_empty() {
+            return None;
+        }
+        let mut metadata = std::collections::HashMap::new();
+        metadata.insert(
+            "name".to_string(),
+            serde_json::Value::String(name.to_string()),
+        );
+        Some(CreateSessionRequest {
+            cwd: project.path.clone(),
+            command: command.to_string(),
+            env: Default::default(),
+            metadata,
+            worktree: Some(WorktreeSpec {
+                base_repo: project
+                    .base_repo
+                    .clone()
+                    .unwrap_or_else(|| project.path.clone()),
+                branch: name.to_string(),
+                create_branch: true,
+            }),
+        })
+    }
+
+    /// Seed a fresh draft pane with whatever did resolve — the fallback when
+    /// [`Self::build_request`] is `None`. The operator fills in the rest.
+    pub fn apply_to_draft(&self, draft: &mut DraftPane) {
+        if let Some(project) = &self.project {
+            draft.picked_cwd = Some(PathBuf::from(&project.path));
+            // The scan already knows this directory's repo (#61): no probe
+            // round trip needed, exactly like picking the row by hand.
+            draft.base_repo = Some(
+                project
+                    .base_repo
+                    .clone()
+                    .unwrap_or_else(|| project.path.clone()),
+            );
+            draft.probed_cwd = Some(PathBuf::from(&project.path));
+        }
+        if let Some(command) = &self.command {
+            if let Some(idx) = draft.presets.iter().position(|p| &p.command == command) {
+                draft.selected_preset = idx;
+            } else if !command.trim().is_empty() {
+                // A last_command no preset advertises lands in custom free text.
+                draft.selected_preset = draft.presets.len().saturating_sub(1);
+                draft.custom_command = crate::text_input::TextInput::with_value(command);
+            }
+        }
+        if let Some(name) = &self.name {
+            draft.set_name(name.clone());
+            // Seeded, not generated: a later refill must not clobber it.
+            draft.name_touched = true;
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use chrono::TimeDelta;
+
+    fn project(path: &str, days_ago: i64, cmd: Option<&str>) -> Project {
+        Project {
+            path: PathBuf::from(path),
+            name: path.rsplit('/').next().unwrap_or(path).into(),
+            is_worktree: false,
+            base_repo: None,
+            last_activity: Some(Utc::now() - TimeDelta::days(days_ago)),
+            last_command: cmd.map(String::from),
+        }
+    }
+
+    fn repo_project(path: &str, base: &str, days_ago: i64, cmd: Option<&str>) -> Project {
+        Project {
+            base_repo: Some(PathBuf::from(base)),
+            ..project(path, days_ago, cmd)
+        }
+    }
+
+    fn preset(id: &str, command: &str) -> SpawnPreset {
+        SpawnPreset {
+            id: id.into(),
+            label: id.into(),
+            command: command.into(),
+        }
+    }
+
+    #[test]
+    fn resolves_every_default_from_the_most_recent_project() {
+        let projects = vec![
+            project("/repos/old", 30, Some("zsh")),
+            repo_project("/repos/fresh", "/repos/fresh", 0, Some("claude")),
+        ];
+        let presets = vec![preset("aider", "aider"), preset("custom", "")];
+        let r = resolve(&projects, &presets, Some("amber-falcon".into()), Utc::now());
+        assert_eq!(
+            r.project.as_ref().unwrap().path,
+            PathBuf::from("/repos/fresh")
+        );
+        assert_eq!(r.command.as_deref(), Some("claude"));
+        assert_eq!(r.name.as_deref(), Some("amber-falcon"));
+
+        let req = r.build_request().expect("all defaults resolved");
+        assert_eq!(req.cwd, PathBuf::from("/repos/fresh"));
+        assert_eq!(req.command, "claude");
+        assert_eq!(
+            req.metadata.get("name").and_then(|v| v.as_str()),
+            Some("amber-falcon")
+        );
+        let wt = req.worktree.expect("worktree on");
+        assert_eq!(wt.base_repo, PathBuf::from("/repos/fresh"));
+        assert_eq!(wt.branch, "amber-falcon");
+        assert!(wt.create_branch, "fresh branch named after the session");
+    }
+
+    #[test]
+    fn worktree_of_the_most_recent_project_targets_its_base_repo() {
+        let projects = vec![repo_project("/repos/main/wt-x", "/repos/main", 0, None)];
+        let r = resolve(
+            &projects,
+            &[preset("zsh", "zsh")],
+            Some("s".into()),
+            Utc::now(),
+        );
+        let wt = r.build_request().unwrap().worktree.unwrap();
+        assert_eq!(wt.base_repo, PathBuf::from("/repos/main"));
+    }
+
+    #[test]
+    fn missing_last_command_falls_back_to_the_first_non_custom_preset() {
+        let projects = vec![project("/repos/p", 0, None)];
+        let presets = vec![preset("custom", ""), preset("claude", "claude")];
+        let r = resolve(&projects, &presets, Some("n".into()), Utc::now());
+        assert_eq!(r.command.as_deref(), Some("claude"));
+    }
+
+    #[test]
+    fn an_empty_last_command_is_no_command_at_all() {
+        let projects = vec![project("/repos/p", 0, Some(""))];
+        let presets = vec![preset("custom", "")];
+        let r = resolve(&projects, &presets, Some("n".into()), Utc::now());
+        assert_eq!(r.command, None);
+        assert!(r.build_request().is_none());
+    }
+
+    #[test]
+    fn nothing_resolves_when_no_projects_are_known_yet() {
+        let r = resolve(
+            &[],
+            &[preset("claude", "claude")],
+            Some("n".into()),
+            Utc::now(),
+        );
+        assert_eq!(r.project, None);
+        // No project → no directory → no request, even with command + name.
+        assert!(r.build_request().is_none());
+    }
+
+    #[test]
+    fn a_missing_generated_name_downgrades_to_a_draft() {
+        let projects = vec![project("/repos/p", 0, Some("claude"))];
+        let r = resolve(&projects, &[preset("claude", "claude")], None, Utc::now());
+        assert!(r.build_request().is_none(), "no name → no immediate spawn");
+    }
+
+    #[test]
+    fn unresolvable_defaults_still_seed_the_draft_with_what_resolved() {
+        let projects = vec![repo_project("/repos/p", "/repos/p", 0, Some("aider"))];
+        let r = resolve(&projects, &[preset("aider", "aider")], None, Utc::now());
+
+        let mut draft = DraftPane::default();
+        r.apply_to_draft(&mut draft);
+        assert_eq!(draft.cwd(), Some(PathBuf::from("/repos/p")));
+        assert_eq!(draft.base_repo, Some(PathBuf::from("/repos/p")));
+        assert_eq!(draft.command(), "aider");
+        assert!(
+            draft.name.value().is_empty(),
+            "nothing to seed the name with"
+        );
+        assert!(draft.worktree_enabled);
+    }
+
+    #[test]
+    fn a_resolved_name_survives_late_refills_and_tracks_the_branch() {
+        let projects = vec![project("/repos/p", 0, Some("claude"))];
+        let named = resolve(
+            &projects,
+            &[preset("claude", "claude")],
+            Some("amber-falcon".into()),
+            Utc::now(),
+        );
+        let mut draft = DraftPane::default();
+        named.apply_to_draft(&mut draft);
+        // A later batch must not overwrite the name the spawn was seeded with.
+        draft.seed_names(vec!["late-name".into()]);
+        assert_eq!(draft.name.value(), "amber-falcon");
+        assert_eq!(draft.branch.value(), "amber-falcon");
+    }
+
+    #[test]
+    fn an_unresolved_name_still_gets_generated_by_a_later_batch() {
+        let projects = vec![project("/repos/p", 0, Some("claude"))];
+        let r = resolve(&projects, &[preset("claude", "claude")], None, Utc::now());
+        let mut draft = DraftPane::default();
+        r.apply_to_draft(&mut draft);
+        draft.seed_names(vec!["late-name".into()]);
+        assert_eq!(draft.name.value(), "late-name");
+    }
+
+    #[test]
+    fn a_last_command_no_preset_advertises_lands_in_custom_text() {
+        let projects = vec![project("/repos/p", 0, Some("nvim -d"))];
+        let r = resolve(&projects, &[preset("claude", "claude")], None, Utc::now());
+        let mut draft = DraftPane::default();
+        r.apply_to_draft(&mut draft);
+        assert_eq!(draft.command(), "nvim -d");
+        assert!(draft.is_custom());
+    }
+}

crates/maestro-tui/src/input.rs

@@ -27,11 +27,21 @@ pub enum InputKey {
     Esc,
     Enter,
     Tab,
+    /// Shift-Tab. crossterm reports it as its own key code, not a modified Tab.
+    BackTab,
     Backspace,
     Up,
     Down,
     Left,
     Right,
+    Home,
+    End,
+    PageUp,
+    PageDown,
+    Delete,
+    /// Bracketed paste: crossterm delivers the whole payload as one event, so
+    /// text fields can insert it as a single operation.
+    Paste(String),
     Mouse {
         kind: MouseKind,
         region: Region,
@@ -54,11 +64,8 @@ pub enum MouseKind {
 /// NAP-280); for now only the enum is needed.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum Region {
-    Sidebar,
     SidebarRow,
-    Tab,
     Pane,
-    SplitDivider,
     Modal,
     Unknown,
 }
@@ -111,7 +118,9 @@ impl InputKey {
                 if *alt {
                     out.push_str("alt-");
                 }
-                if *shift {
+                // Uppercase already implies shift; crossterm sets the flag
+                // on every such char, so skip the redundant prefix (#70).
+                if *shift && !c.is_uppercase() {
                     out.push_str("shift-");
                 }
                 out.push(*c);
@@ -120,11 +129,20 @@ impl InputKey {
             InputKey::Esc => "esc".into(),
             InputKey::Enter => "enter".into(),
             InputKey::Tab => "tab".into(),
+            InputKey::BackTab => "backtab".into(),
             InputKey::Backspace => "backspace".into(),
             InputKey::Up => "up".into(),
             InputKey::Down => "down".into(),
             InputKey::Left => "left".into(),
             InputKey::Right => "right".into(),
+            InputKey::Home => "home".into(),
+            InputKey::End => "end".into(),
+            InputKey::PageUp => "pageup".into(),
+            InputKey::PageDown => "pagedown".into(),
+            InputKey::Delete => "delete".into(),
+            // Pastes are not bindable; the canonical form exists only to
+            // satisfy exhaustiveness and never round-trips through `parse`.
+            InputKey::Paste(_) => "paste".into(),
             InputKey::Mouse { kind, region, .. } => {
                 let k = match kind {
                     MouseKind::Click => "click",
@@ -134,11 +152,8 @@ impl InputKey {
                     MouseKind::ScrollDown => "scrolldown",
                 };
                 let r = match region {
-                    Region::Sidebar => "sidebar",
                     Region::SidebarRow => "sidebar-row",
-                    Region::Tab => "tab",
                     Region::Pane => "pane",
-                    Region::SplitDivider => "split-divider",
                     Region::Modal => "modal",
                     Region::Unknown => "unknown",
                 };
@@ -168,11 +183,8 @@ impl InputKey {
                 other => return Err(InputParseError::UnknownMouseKind(other.into())),
             };
             let region = match r {
-                "sidebar" => Region::Sidebar,
                 "sidebar-row" => Region::SidebarRow,
-                "tab" => Region::Tab,
                 "pane" => Region::Pane,
-                "split-divider" => Region::SplitDivider,
                 "modal" => Region::Modal,
                 "unknown" => Region::Unknown,
                 other => return Err(InputParseError::UnknownRegion(other.into())),
@@ -188,11 +200,17 @@ impl InputKey {
             "esc" => return Ok(InputKey::Esc),
             "enter" => return Ok(InputKey::Enter),
             "tab" => return Ok(InputKey::Tab),
+            "backtab" => return Ok(InputKey::BackTab),
             "backspace" => return Ok(InputKey::Backspace),
             "up" => return Ok(InputKey::Up),
             "down" => return Ok(InputKey::Down),
             "left" => return Ok(InputKey::Left),
             "right" => return Ok(InputKey::Right),
+            "home" => return Ok(InputKey::Home),
+            "end" => return Ok(InputKey::End),
+            "pageup" => return Ok(InputKey::PageUp),
+            "pagedown" => return Ok(InputKey::PageDown),
+            "delete" => return Ok(InputKey::Delete),
             _ => {}
         }
         // Modifier chain: ctrl-, alt-, shift- prefixes, then a single char.
@@ -258,14 +276,21 @@ where
                 KeyCode::Esc => InputKey::Esc,
                 KeyCode::Enter => InputKey::Enter,
                 KeyCode::Tab => InputKey::Tab,
+                KeyCode::BackTab => InputKey::BackTab,
                 KeyCode::Backspace => InputKey::Backspace,
                 KeyCode::Up => InputKey::Up,
                 KeyCode::Down => InputKey::Down,
                 KeyCode::Left => InputKey::Left,
                 KeyCode::Right => InputKey::Right,
+                KeyCode::Home => InputKey::Home,
+                KeyCode::End => InputKey::End,
+                KeyCode::PageUp => InputKey::PageUp,
+                KeyCode::PageDown => InputKey::PageDown,
+                KeyCode::Delete => InputKey::Delete,
                 _ => return None,
             })
         }
+        CtEvent::Paste(text) => Some(InputKey::Paste(text.clone())),
         CtEvent::Mouse(MouseEvent {
             kind, column, row, ..
         }) => {
@@ -288,6 +313,63 @@ where
     }
 }
 
+/// How long after a click a second click at the same cell counts as a
+/// double-click. Matches the common desktop default.
+pub const DOUBLE_CLICK_WINDOW: Duration = Duration::from_millis(400);
+
+/// Remembers the last click so a second one at the same cell can be promoted to
+/// [`MouseKind::DblClick`].
+///
+/// Kept out of [`canonicalise`], which stays a pure function of one event.
+#[derive(Debug, Default)]
+pub struct ClickTracker {
+    last: Option<(u16, u16, Instant)>,
+}
+
+impl ClickTracker {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Upgrade a `Click` to a `DblClick` when it *immediately* follows another
+    /// click at the same cell inside [`DOUBLE_CLICK_WINDOW`].
+    ///
+    /// Anything else passes through and clears the pending click: two clicks
+    /// with a drag or a keystroke between them are two clicks, however fast.
+    ///
+    /// A promoted click also resets the tracker, so three rapid clicks are a
+    /// click then a double-click, not two double-clicks.
+    pub fn promote(&mut self, key: InputKey, now: Instant) -> InputKey {
+        let InputKey::Mouse {
+            kind: MouseKind::Click,
+            region,
+            col,
+            row,
+        } = key
+        else {
+            self.last = None;
+            return key;
+        };
+
+        let is_double = matches!(
+            self.last,
+            Some((c, r, at))
+                if c == col && r == row && now.duration_since(at) <= DOUBLE_CLICK_WINDOW
+        );
+        if is_double {
+            self.last = None;
+            return InputKey::Mouse {
+                kind: MouseKind::DblClick,
+                region,
+                col,
+                row,
+            };
+        }
+        self.last = Some((col, row, now));
+        key
+    }
+}
+
 /// Result of feeding one key into [`ChordState`]. `Pending` = held because the
 /// current sequence is a strict prefix of some known binding; `Resolved` =
 /// dispatch this canonical string against the keymap.
@@ -358,14 +440,175 @@ impl ChordState {
 mod tests {
     use super::*;
 
+    fn click(col: u16, row: u16) -> InputKey {
+        InputKey::Mouse {
+            kind: MouseKind::Click,
+            region: Region::SidebarRow,
+            col,
+            row,
+        }
+    }
+
+    /// The shipped default binds `mouse:dblclick(sidebar-row)`. Nothing could
+    /// produce a DblClick, so that binding could never fire.
+    #[test]
+    fn a_second_click_at_the_same_cell_becomes_a_double_click() {
+        let mut t = ClickTracker::new();
+        let t0 = Instant::now();
+
+        assert_eq!(t.promote(click(3, 4), t0), click(3, 4));
+        assert_eq!(
+            t.promote(click(3, 4), t0 + Duration::from_millis(100)),
+            InputKey::Mouse {
+                kind: MouseKind::DblClick,
+                region: Region::SidebarRow,
+                col: 3,
+                row: 4,
+            }
+        );
+    }
+
+    #[test]
+    fn a_slow_second_click_stays_a_click() {
+        let mut t = ClickTracker::new();
+        let t0 = Instant::now();
+        t.promote(click(3, 4), t0);
+        let late = t0 + DOUBLE_CLICK_WINDOW + Duration::from_millis(1);
+        assert_eq!(t.promote(click(3, 4), late), click(3, 4));
+    }
+
+    #[test]
+    fn a_second_click_elsewhere_stays_a_click() {
+        let mut t = ClickTracker::new();
+        let t0 = Instant::now();
+        t.promote(click(3, 4), t0);
+        assert_eq!(
+            t.promote(click(9, 4), t0 + Duration::from_millis(10)),
+            click(9, 4)
+        );
+    }
+
+    /// Three fast clicks are click, double-click, click — not two doubles.
+    #[test]
+    fn a_promoted_click_resets_the_tracker() {
+        let mut t = ClickTracker::new();
+        let t0 = Instant::now();
+        t.promote(click(1, 1), t0);
+        let second = t.promote(click(1, 1), t0 + Duration::from_millis(50));
+        assert!(matches!(
+            second,
+            InputKey::Mouse {
+                kind: MouseKind::DblClick,
+                ..
+            }
+        ));
+        let third = t.promote(click(1, 1), t0 + Duration::from_millis(100));
+        assert_eq!(third, click(1, 1));
+    }
+
+    #[test]
+    fn non_click_events_pass_through_untouched() {
+        let mut t = ClickTracker::new();
+        assert_eq!(t.promote(InputKey::Enter, Instant::now()), InputKey::Enter);
+    }
+
+    /// A drag between two clicks means the user dragged, not double-clicked —
+    /// even at the same cell and well inside the window.
+    #[test]
+    fn a_drag_between_two_clicks_breaks_the_double() {
+        let mut t = ClickTracker::new();
+        let t0 = Instant::now();
+        t.promote(click(3, 4), t0);
+
+        let drag = InputKey::Mouse {
+            kind: MouseKind::Drag,
+            region: Region::SidebarRow,
+            col: 3,
+            row: 4,
+        };
+        assert_eq!(
+            t.promote(drag.clone(), t0 + Duration::from_millis(20)),
+            drag
+        );
+
+        assert_eq!(
+            t.promote(click(3, 4), t0 + Duration::from_millis(40)),
+            click(3, 4),
+            "a drag must clear the pending click"
+        );
+    }
+
+    #[test]
+    fn a_keystroke_between_two_clicks_breaks_the_double() {
+        let mut t = ClickTracker::new();
+        let t0 = Instant::now();
+        t.promote(click(3, 4), t0);
+        t.promote(InputKey::Enter, t0 + Duration::from_millis(20));
+
+        assert_eq!(
+            t.promote(click(3, 4), t0 + Duration::from_millis(40)),
+            click(3, 4)
+        );
+    }
+
+    /// A scroll also counts as an intervening event.
+    #[test]
+    fn a_scroll_between_two_clicks_breaks_the_double() {
+        let mut t = ClickTracker::new();
+        let t0 = Instant::now();
+        t.promote(click(3, 4), t0);
+        let scroll = InputKey::Mouse {
+            kind: MouseKind::ScrollUp,
+            region: Region::SidebarRow,
+            col: 3,
+            row: 4,
+        };
+        t.promote(scroll, t0 + Duration::from_millis(20));
+
+        assert_eq!(
+            t.promote(click(3, 4), t0 + Duration::from_millis(40)),
+            click(3, 4)
+        );
+    }
+
+    #[test]
+    fn back_tab_round_trips_through_the_canonical_form() {
+        assert_eq!(InputKey::BackTab.canonical(), "backtab");
+        assert_eq!(InputKey::parse("backtab").unwrap(), InputKey::BackTab);
+    }
+
+    /// The parser must not accept region names the renderer cannot produce.
+    #[test]
+    fn unproducible_region_names_are_rejected() {
+        assert!(InputKey::parse("mouse:click(sidebar)").is_err());
+        assert!(InputKey::parse("mouse:click(split-divider)").is_err());
+        assert!(InputKey::parse("mouse:click(sidebar-row)").is_ok());
+    }
+
     #[test]
     fn canonical_round_trips_simple_chars() {
-        for s in ["a", "ctrl-a", "ctrl-w", "alt-x", "shift-A"] {
+        for s in ["a", "ctrl-a", "ctrl-w", "alt-x"] {
             let k = InputKey::parse(s).unwrap();
             assert_eq!(k.canonical(), s, "round-trip {s:?}");
         }
     }
 
+    /// crossterm 0.28 attaches `KeyModifiers::SHIFT` to any uppercase char,
+    /// so a real Shift+S delivers `Char { c: 'S', shift: true }`. Its
+    /// canonical form must be the bare `"S"` a keymap binds, not `"shift-S"` —
+    /// the uppercase letter already says "shifted"; a redundant prefix would
+    /// make the default `S` binding unreachable from the keyboard (#70).
+    #[test]
+    fn shift_flag_is_redundant_for_an_already_uppercase_char() {
+        let k = InputKey::Char {
+            c: 'S',
+            ctrl: false,
+            alt: false,
+            shift: true,
+        };
+        assert_eq!(k.canonical(), "S");
+    }
+
     #[test]
     fn canonical_round_trips_specials() {
         for s in [
@@ -377,12 +620,27 @@ mod tests {
             "down",
             "left",
             "right",
+            "home",
+            "end",
+            "pageup",
+            "pagedown",
+            "delete",
         ] {
             let k = InputKey::parse(s).unwrap();
             assert_eq!(k.canonical(), s, "round-trip {s:?}");
         }
     }
 
+    /// A bracketed paste must arrive as one key carrying the whole payload,
+    /// not a burst of per-character keys.
+    #[test]
+    fn canonicalise_paste_event_carries_the_whole_payload() {
+        use crossterm::event::Event as CtEvent;
+        let ev = CtEvent::Paste("/srv/work/maestro".into());
+        let k = canonicalise(&ev, |_, _| Region::Unknown).unwrap();
+        assert_eq!(k, InputKey::Paste("/srv/work/maestro".into()));
+    }
+
     #[test]
     fn canonical_round_trips_mouse() {
         let s = "mouse:click(pane)";

crates/maestro-tui/src/keymap.rs

@@ -107,8 +107,8 @@ mod tests {
 
     #[test]
     fn resolves_chord() {
-        let k = build(&[(Mode::Normal, "g t", "NextTab")]);
-        assert_eq!(k.resolve(Mode::Normal, "g t"), Some(Action::NextTab));
+        let k = build(&[(Mode::Normal, "g h", "FocusSidebar")]);
+        assert_eq!(k.resolve(Mode::Normal, "g h"), Some(Action::FocusSidebar));
     }
 
     #[test]
@@ -123,11 +123,11 @@ mod tests {
     #[test]
     fn known_bindings_sees_everything() {
         let k = build(&[
-            (Mode::Normal, "g t", "NextTab"),
+            (Mode::Normal, "g h", "FocusSidebar"),
             (Mode::Normal, "i", "EnterInsert"),
         ]);
         let kb = k.known_bindings(Mode::Normal);
-        assert!(kb.contains("g t"));
+        assert!(kb.contains("g h"));
         assert!(kb.contains("i"));
         assert_eq!(kb.len(), 2);
     }

crates/maestro-tui/src/lib.rs

@@ -7,21 +7,26 @@ pub mod app;
 pub mod catalog;
 pub mod cli;
 pub mod config;
+pub mod draft;
 pub mod emulators;
+pub mod fast_forward;
 pub mod input;
 pub mod keymap;
 pub mod overlays;
+pub mod palette;
 pub mod pane;
+pub mod projects;
 pub mod render;
 pub mod session_task;
 pub mod sidebar;
 pub mod state;
-pub mod tabs;
 pub mod terminal;
+pub mod text_input;
 
 use std::path::PathBuf;
 use std::time::Duration;
 
+use maestro_protocol::DaemonClient;
 use ratatui::backend::CrosstermBackend;
 use ratatui::Terminal;
 
@@ -37,7 +42,7 @@ pub struct RunConfig {
     /// No trailing slash.
     pub daemon_url: String,
     /// Explicit `--config <path>` override from the umbrella binary's global
-    /// flag. When `None`, [`maestro_config::resolve_config_path`] picks the
+    /// flag. When `None`, [`maestro_config::default_config_path`] picks the
     /// default (`$MAESTRO_CONFIG` or `~/.config/maestro/config.toml`).
     pub config_path: Option<PathBuf>,
 }
@@ -62,13 +67,20 @@ pub async fn run(cfg: RunConfig) -> Result<(), TuiError> {
     let base_url = cfg.daemon_url.trim_end_matches('/').to_string();
 
     // Health check — fail fast if no daemon is reachable.
-    health_check(&base_url).await?;
+    health_check(&DaemonClient::with_timeouts(
+        &base_url,
+        HEALTH_TIMEOUT,
+        HEALTH_TIMEOUT,
+    ))
+    .await?;
+
+    let daemon = DaemonClient::with_timeouts(&base_url, REQUEST_TIMEOUT, REQUEST_TIMEOUT);
 
     // Load runtime config: explicit `--config <path>` wins, then
     // `$MAESTRO_CONFIG`, then the platform default. Missing file is fine —
     // we fall back to shipped defaults.
     let cfg_path = cfg.config_path.clone().map(Ok).unwrap_or_else(|| {
-        maestro_config::resolve_config_path().map_err(|e| TuiError::Config(e.to_string()))
+        maestro_config::default_config_path().map_err(|e| TuiError::Config(e.to_string()))
     });
     let cfg_file = match cfg_path {
         Ok(path) => maestro_config::MaestroConfigFile::load(&path)
@@ -76,9 +88,12 @@ pub async fn run(cfg: RunConfig) -> Result<(), TuiError> {
         Err(_) => maestro_config::MaestroConfigFile::default(),
     };
     let tui_cfg = TuiConfig::load(&cfg_file.tui).map_err(|e| TuiError::Config(e.to_string()))?;
+    palette::set_active(tui_cfg.palette);
 
     let catalog = CatalogStore::default();
-    let ws_url = format!("{}/api/events", ws_base(&base_url));
+    let ws_url = daemon
+        .events_url()
+        .map_err(|e| TuiError::Config(e.to_string()))?;
     let bg_catalog = catalog.clone();
     tokio::spawn(async move { bg_catalog.run_events_loop(ws_url).await });
 
@@ -92,33 +107,32 @@ pub async fn run(cfg: RunConfig) -> Result<(), TuiError> {
     let backend = CrosstermBackend::new(std::io::stdout());
     let mut terminal = Terminal::new(backend).map_err(|e| TuiError::Terminal(e.to_string()))?;
 
-    let app = App::new(tui_cfg, catalog, base_url);
+    let app = App::new(tui_cfg, catalog, daemon);
     app.run(&mut terminal).await
 }
 
-async fn health_check(base_url: &str) -> Result<(), TuiError> {
-    let client = reqwest::Client::builder()
-        .timeout(Duration::from_millis(500))
-        .build()
-        .expect("reqwest client");
-    let url = format!("{base_url}/api/info");
-    for _ in 0..3 {
-        if let Ok(res) = client.get(&url).send().await {
-            if res.status().is_success() {
-                return Ok(());
-            }
-        }
-        tokio::time::sleep(Duration::from_millis(500)).await;
-    }
-    Err(TuiError::DaemonUnreachable(base_url.to_string()))
-}
+/// Startup probe budget, applied to connect *and* the whole request: the user is
+/// staring at a terminal, so an unreachable daemon must fail in under a second.
+const HEALTH_TIMEOUT: Duration = Duration::from_millis(500);
 
-fn ws_base(http: &str) -> String {
-    if let Some(rest) = http.strip_prefix("http://") {
-        format!("ws://{rest}")
-    } else if let Some(rest) = http.strip_prefix("https://") {
-        format!("wss://{rest}")
-    } else {
-        http.to_string()
+/// Budget for the TUI's own calls once it is up. Tighter than the client
+/// default — a spawn or kill that stalls should surface as a toast, not hang
+/// the interface.
+const REQUEST_TIMEOUT: Duration = Duration::from_secs(5);
+
+async fn health_check(daemon: &DaemonClient) -> Result<(), TuiError> {
+    for _ in 0..3 {
+        if let Ok(info) = daemon.daemon_info().await {
+            if !maestro_protocol::is_compatible(&info.version) {
+                tracing::warn!(
+                    daemon = %info.version,
+                    client = %maestro_protocol::PROTOCOL_VERSION,
+                    "daemon protocol version differs from this client's",
+                );
+            }
+            return Ok(());
+        }
+        tokio::time::sleep(HEALTH_TIMEOUT).await;
     }
+    Err(TuiError::DaemonUnreachable(daemon.base().to_string()))
 }

crates/maestro-tui/src/overlays.rs

@@ -1,179 +1,87 @@
-//! Overlay widgets: spawn modal, kill-confirm prompt, help overlay,
+//! Overlay widgets: kill-confirm prompt, rename prompt, help overlay,
 //! transient toast.
 //!
+//! The spawn form is no longer an overlay (issue #63) — it lives in draft
+//! panes ([`crate::draft::DraftPane`]).
+//!
 //! All overlays are centered popups drawn over the rest of the UI; the
 //! `Clear` widget wipes the underlying buffer before drawing.
 
-use ratatui::layout::{Constraint, Layout, Rect};
-use ratatui::style::{Modifier, Style};
+use ratatui::layout::Rect;
+use ratatui::style::Style;
 use ratatui::text::Line;
 use ratatui::widgets::{Block, Borders, Clear, List, ListItem, Paragraph};
 use ratatui::Frame;
 
-#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
-pub enum SpawnField {
-    #[default]
-    Cwd,
-    Command,
-    Submit,
-}
-
-#[derive(Debug, Default, Clone)]
-pub struct SpawnModal {
-    pub cwd: String,
-    pub command: String,
-    pub focused_field: SpawnField,
-}
-
-impl SpawnModal {
-    pub fn next_field(&mut self) {
-        self.focused_field = match self.focused_field {
-            SpawnField::Cwd => SpawnField::Command,
-            SpawnField::Command => SpawnField::Submit,
-            SpawnField::Submit => SpawnField::Cwd,
-        };
-    }
-
-    pub fn prev_field(&mut self) {
-        self.focused_field = match self.focused_field {
-            SpawnField::Cwd => SpawnField::Submit,
-            SpawnField::Command => SpawnField::Cwd,
-            SpawnField::Submit => SpawnField::Command,
-        };
-    }
-
-    /// Handle one keystroke while this modal owns input. Returns
-    /// [`SpawnInputResult::Submit`] when the user accepts; the caller fires
-    /// the POST and dismisses the modal.
-    pub fn on_input(&mut self, key: &crate::input::InputKey) -> SpawnInputResult {
-        use crate::input::InputKey;
-        match key {
-            InputKey::Tab => {
-                self.next_field();
-                SpawnInputResult::Consumed
-            }
-            InputKey::Esc => SpawnInputResult::Cancel,
-            InputKey::Enter => match self.focused_field {
-                SpawnField::Submit => SpawnInputResult::Submit,
-                _ => {
-                    self.next_field();
-                    SpawnInputResult::Consumed
-                }
-            },
-            InputKey::Char { c, .. } => {
-                match self.focused_field {
-                    SpawnField::Cwd => self.cwd.push(*c),
-                    SpawnField::Command => self.command.push(*c),
-                    SpawnField::Submit => {}
-                }
-                SpawnInputResult::Consumed
-            }
-            InputKey::Backspace => {
-                match self.focused_field {
-                    SpawnField::Cwd => {
-                        self.cwd.pop();
-                    }
-                    SpawnField::Command => {
-                        self.command.pop();
-                    }
-                    _ => {}
-                }
-                SpawnInputResult::Consumed
-            }
-            _ => SpawnInputResult::Consumed,
-        }
-    }
-
-    pub fn render(&self, f: &mut Frame, parent: Rect) {
-        let area = centered(parent, 60, 10);
-        f.render_widget(Clear, area);
-        let block = Block::default().title(" spawn ").borders(Borders::ALL);
-        let inner = block.inner(area);
-        f.render_widget(block, area);
-        let rows = Layout::vertical([
-            Constraint::Length(2),
-            Constraint::Length(2),
-            Constraint::Length(1),
-        ])
-        .split(inner);
-        let highlight = |field: SpawnField| {
-            if self.focused_field == field {
-                Style::default().add_modifier(Modifier::REVERSED)
-            } else {
-                Style::default()
-            }
-        };
-        let field_row = |label: &str, value: &str, style: Style| {
-            Paragraph::new(Line::from(vec![
-                ratatui::text::Span::raw(format!("{label:8} ")),
-                ratatui::text::Span::styled(value.to_string(), style),
-            ]))
-        };
-        f.render_widget(
-            field_row("cwd:", &self.cwd, highlight(SpawnField::Cwd)),
-            rows[0],
-        );
-        f.render_widget(
-            field_row("command:", &self.command, highlight(SpawnField::Command)),
-            rows[1],
-        );
-        f.render_widget(
-            Paragraph::new(Line::from(vec![ratatui::text::Span::styled(
-                "[ Spawn ]",
-                highlight(SpawnField::Submit),
-            )])),
-            rows[2],
-        );
-
-        // Place the cursor at the end of the currently-focused text field so
-        // the user can see where their typing lands. Label is fixed-width
-        // 8 chars + 1 space = column 9 inside the row.
-        let cursor_col_for = |value: &str| -> u16 {
-            inner
-                .x
-                .saturating_add(9)
-                .saturating_add(value.chars().count() as u16)
-        };
-        match self.focused_field {
-            SpawnField::Cwd => f.set_cursor_position((cursor_col_for(&self.cwd), rows[0].y)),
-            SpawnField::Command => {
-                f.set_cursor_position((cursor_col_for(&self.command), rows[1].y))
-            }
-            SpawnField::Submit => {
-                // The submit button is indicated by the REVERSED style; no
-                // cursor placement.
-            }
-        }
-    }
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum SpawnInputResult {
-    Consumed,
-    Cancel,
-    Submit,
-}
+use crate::text_input::TextInput;
 
 #[derive(Debug, Clone)]
 pub struct KillConfirm {
     pub label: String,
+    /// #83: what the daemon's watcher last saw in the worktree, phrased by
+    /// [`maestro_protocol::InTheWay`]'s Display — so "this will be refused"
+    /// is visible before the attempt. `None` while nothing blocks.
+    pub blockers: Option<String>,
 }
 
 impl KillConfirm {
     pub fn render(&self, f: &mut Frame, parent: Rect) {
-        let area = centered(parent, 50, 5);
+        let area = centered(parent, 60, if self.blockers.is_some() { 6 } else { 5 });
         f.render_widget(Clear, area);
         let block = Block::default().title(" kill ").borders(Borders::ALL);
         let inner = block.inner(area);
         f.render_widget(block, area);
+        let mut lines = vec![Line::from(format!("Kill session {}?", self.label))];
+        if let Some(blockers) = &self.blockers {
+            lines.push(Line::from(format!("Currently in the way: {blockers}")));
+            lines.push(Line::from("The kill will be refused unless forced."));
+        }
+        lines.push(Line::from(""));
+        lines.push(Line::from("[y] yes   [n] no"));
+        f.render_widget(Paragraph::new(lines), inner);
+    }
+}
+
+/// Rename prompt for the highlighted session (#125).
+///
+/// Borrows its text buffer rather than owning it: the buffer lives on `App`,
+/// so [`crate::state::OverlayKind`] stays a plain comparable enum.
+#[derive(Debug)]
+pub struct RenamePrompt<'a> {
+    /// What the card shows today — the session's name, or the command it
+    /// falls back to when it has none.
+    pub current: &'a str,
+    pub input: &'a TextInput,
+}
+
+impl RenamePrompt<'_> {
+    /// Draws the prompt and returns where the terminal cursor belongs.
+    pub fn render(&self, f: &mut Frame, parent: Rect) -> Option<(u16, u16)> {
+        let area = centered(parent, 64, 7);
+        f.render_widget(Clear, area);
+        let block = Block::default().title(" rename ").borders(Borders::ALL);
+        let inner = block.inner(area);
+        f.render_widget(block, area);
+        if inner.height < 4 || inner.width == 0 {
+            return None;
+        }
+        let row = |offset: u16| Rect {
+            x: inner.x,
+            y: inner.y + offset,
+            width: inner.width,
+            height: 1,
+        };
         f.render_widget(
-            Paragraph::new(vec![
-                Line::from(format!("Kill session {}?", self.label)),
-                Line::from(""),
-                Line::from("[y] yes   [n] no"),
-            ]),
-            inner,
+            Paragraph::new(Line::from(format!("Rename {}", self.current))),
+            row(0),
         );
+        let field = row(1);
+        let col = self.input.render(field, f.buffer_mut(), Style::default());
+        f.render_widget(
+            Paragraph::new(Line::from("[enter] save   [esc] cancel")),
+            row(3),
+        );
+        Some((col, field.y))
     }
 }
 
@@ -225,7 +133,7 @@ impl Toast {
     }
 }
 
-fn centered(parent: Rect, w: u16, h: u16) -> Rect {
+pub(crate) fn centered(parent: Rect, w: u16, h: u16) -> Rect {
     let w = w.min(parent.width);
     let h = h.min(parent.height);
     Rect {
@@ -260,37 +168,11 @@ mod tests {
         out
     }
 
-    #[test]
-    fn spawn_modal_renders_field_labels() {
-        let modal = SpawnModal {
-            cwd: "/x".into(),
-            command: "bash".into(),
-            focused_field: SpawnField::Cwd,
-        };
-        let rendered = render_to_string(80, 20, |f| modal.render(f, f.area()));
-        for s in ["cwd", "command", "Spawn", "/x", "bash"] {
-            assert!(rendered.contains(s), "missing {s:?}:\n{rendered}");
-        }
-    }
-
-    #[test]
-    fn spawn_modal_field_rotation() {
-        let mut modal = SpawnModal::default();
-        assert_eq!(modal.focused_field, SpawnField::Cwd);
-        modal.next_field();
-        assert_eq!(modal.focused_field, SpawnField::Command);
-        modal.next_field();
-        assert_eq!(modal.focused_field, SpawnField::Submit);
-        modal.next_field();
-        assert_eq!(modal.focused_field, SpawnField::Cwd);
-        modal.prev_field();
-        assert_eq!(modal.focused_field, SpawnField::Submit);
-    }
-
     #[test]
     fn kill_confirm_renders_prompt() {
         let modal = KillConfirm {
             label: "session-7".into(),
+            blockers: None,
         };
         let rendered = render_to_string(60, 10, |f| modal.render(f, f.area()));
         assert!(rendered.contains("Kill"));
@@ -299,16 +181,48 @@ mod tests {
         assert!(rendered.contains("no"));
     }
 
+    /// #83: when the worktree blocks, the confirm names it before the
+    /// operator commits — in `InTheWay`'s own words.
+    #[test]
+    fn kill_confirm_names_what_blocks() {
+        let modal = KillConfirm {
+            label: "session-7".into(),
+            blockers: Some("2 uncommitted files".into()),
+        };
+        let rendered = render_to_string(70, 10, |f| modal.render(f, f.area()));
+        assert!(
+            rendered.contains("Currently in the way: 2 uncommitted files"),
+            "{rendered}"
+        );
+        assert!(rendered.contains("refused"), "{rendered}");
+    }
+
+    #[test]
+    fn rename_prompt_shows_the_current_name_and_the_edit_buffer() {
+        let input = TextInput::with_value("crimson-otter");
+        let prompt = RenamePrompt {
+            current: "amber-falcon",
+            input: &input,
+        };
+        let rendered = render_to_string(70, 12, |f| {
+            prompt.render(f, f.area());
+        });
+        assert!(rendered.contains("Rename amber-falcon"), "{rendered}");
+        assert!(rendered.contains("crimson-otter"), "{rendered}");
+        assert!(rendered.contains("[enter] save"), "{rendered}");
+        assert!(rendered.contains("[esc] cancel"), "{rendered}");
+    }
+
     #[test]
     fn help_overlay_lists_lines() {
         let help = HelpOverlay {
             lines: vec![
-                "i           EnterInsert".into(),
-                "s           OpenSpawnModal".into(),
+                "i           Send keys to session".into(),
+                "s           Create a session".into(),
             ],
         };
         let rendered = render_to_string(80, 12, |f| help.render(f, f.area()));
-        assert!(rendered.contains("EnterInsert"));
-        assert!(rendered.contains("OpenSpawnModal"));
+        assert!(rendered.contains("Send keys to session"));
+        assert!(rendered.contains("Create a session"));
     }
 }

crates/maestro-tui/src/palette.rs

@@ -0,0 +1,851 @@
+//! Named colour roles for the TUI.
+//!
+//! Every colour the TUI paints on its own chrome comes from here, named for
+//! what it means rather than what it looks like: the card surface, the
+//! selection surface, the panel border in its focused and unfocused forms,
+//! the text weights (`fg` / `muted` / `dim`), and one role per
+//! [`ActivityState`]. Call sites ask the palette for a role; they never spell
+//! a colour out.
+//!
+//! Values are [`Color::Rgb`], so contrast is a property of the palette rather
+//! than of the user's terminal theme — and can therefore be asserted (see
+//! [`contrast_ratio`] and this module's tests).
+//!
+//! Each surface carries its own activity colours. A state colour picked for
+//! the dark card background is not legible on the selection background, so
+//! the selected card uses the selection surface's own state colours; the dot
+//! keeps carrying the state either way (docs/SIDEBAR.md).
+//!
+//! [`Palette::DARK`] is the default. [`Palette::LIGHT`] is its light peer and
+//! [`Palette::ANSI`] uses terminal-provided ANSI colours. The remaining
+//! presets ([`Palette::presets`]) adapt well-known editor themes — Solarized,
+//! Catppuccin, GitHub, Tokyo Night, Gruvbox, Nord, Dracula — with individual
+//! colours lifted or darkened where the originals fall short of the contrast
+//! floors asserted below.
+//!
+//! Out of scope: PTY cell colours. Those belong to the program running in the
+//! pane and pass through `pane::translate_color` verbatim.
+
+use maestro_protocol::ActivityState;
+use ratatui::style::{Color, Modifier, Style};
+
+/// A background and the foreground roles legible on it.
+///
+/// The sidebar has two: the card surface every card sits on, and the
+/// selection surface the highlighted card swaps in.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Surface {
+    /// The surface itself.
+    pub bg: Color,
+    /// Primary text on this surface.
+    pub fg: Color,
+    /// Secondary text — the blocked-work, exited, detail and command
+    /// fragments of a card's meta line.
+    pub muted: Color,
+    /// The quietest legible text on this surface, for decoration that must
+    /// not compete with content.
+    pub dim: Color,
+    /// `ActivityState::Active`.
+    pub active: Color,
+    /// `ActivityState::Idle`.
+    pub idle: Color,
+    /// `ActivityState::AwaitingInput`.
+    pub awaiting: Color,
+    /// `ActivityState::Error`.
+    pub error: Color,
+}
+
+impl Surface {
+    /// The bare surface: a background with no foreground override.
+    pub fn base(&self) -> Style {
+        Style::default().bg(self.bg)
+    }
+
+    /// Primary text on this surface.
+    pub fn text_style(&self) -> Style {
+        Style::default().bg(self.bg).fg(self.fg)
+    }
+
+    /// Secondary text on this surface.
+    pub fn muted_style(&self) -> Style {
+        Style::default().bg(self.bg).fg(self.muted)
+    }
+
+    /// The quietest text on this surface.
+    pub fn dim_style(&self) -> Style {
+        Style::default().bg(self.bg).fg(self.dim)
+    }
+
+    /// The colour carrying `state` on this surface.
+    pub fn activity(&self, state: ActivityState) -> Color {
+        match state {
+            ActivityState::Active => self.active,
+            ActivityState::Idle => self.idle,
+            ActivityState::AwaitingInput => self.awaiting,
+            ActivityState::Error => self.error,
+        }
+    }
+
+    /// Every foreground role on this surface, paired with its role name.
+    /// Used by the contrast tests, and by anything that needs to reason about
+    /// the surface as a whole.
+    pub fn roles(&self) -> [(&'static str, Color); 7] {
+        [
+            ("fg", self.fg),
+            ("muted", self.muted),
+            ("dim", self.dim),
+            ("active", self.active),
+            ("idle", self.idle),
+            ("awaiting", self.awaiting),
+            ("error", self.error),
+        ]
+    }
+}
+
+/// The full set of colour roles the TUI paints with.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Palette {
+    /// The surface an unselected card sits on.
+    pub card: Surface,
+    /// The surface the highlighted card swaps in.
+    pub selection: Surface,
+    /// Background for TUI-owned chrome outside cards. Fixed-RGB chrome must
+    /// paint this background too; otherwise its contrast depends on the
+    /// operator's terminal theme.
+    pub chrome_bg: Color,
+    /// Subtle full-panel background while the sidebar owns focus.
+    pub sidebar_focus_bg: Color,
+    /// Panel border while that panel holds focus.
+    pub border_focused: Color,
+    /// Panel border while it does not.
+    pub border_unfocused: Color,
+    /// Focus affordances that are not the border itself — markers, titles and
+    /// the like on the panel that holds focus.
+    pub focus_accent: Color,
+    /// Sidebar group headings.
+    pub group_row: Color,
+    /// Status-bar mode indicator, normal mode.
+    pub mode_normal_bg: Color,
+    pub mode_normal_fg: Color,
+    /// Status-bar mode indicator, insert mode.
+    pub mode_insert_bg: Color,
+    pub mode_insert_fg: Color,
+    /// Error text outside a card — form errors, failed actions.
+    pub error_text: Color,
+}
+
+impl Palette {
+    /// The dark terminal-native palette and the default preset.
+    pub const DARK: Palette = Palette {
+        card: Surface {
+            bg: Color::Rgb(0x1f, 0x23, 0x2b),
+            fg: Color::Rgb(0xe5, 0xe7, 0xeb),
+            muted: Color::Rgb(0xae, 0xb7, 0xc4),
+            dim: Color::Rgb(0x85, 0x8f, 0x9e),
+            active: Color::Rgb(0x72, 0xd6, 0x87),
+            idle: Color::Rgb(0xae, 0xb7, 0xc4),
+            awaiting: Color::Rgb(0xf2, 0xc9, 0x5c),
+            error: Color::Rgb(0xff, 0x82, 0x7a),
+        },
+        selection: Surface {
+            bg: Color::Rgb(0x3d, 0x51, 0x44),
+            fg: Color::Rgb(0xf3, 0xf7, 0xf4),
+            muted: Color::Rgb(0xd0, 0xd9, 0xd3),
+            dim: Color::Rgb(0xa1, 0xb0, 0xa6),
+            active: Color::Rgb(0x9a, 0xf0, 0xa6),
+            idle: Color::Rgb(0xc4, 0xcf, 0xc7),
+            awaiting: Color::Rgb(0xf6, 0xd9, 0x78),
+            error: Color::Rgb(0xff, 0xa8, 0xa3),
+        },
+        chrome_bg: Color::Rgb(0x1f, 0x23, 0x2b),
+        sidebar_focus_bg: Color::Rgb(0x28, 0x30, 0x2a),
+        border_focused: Color::Rgb(0x72, 0xd6, 0x87),
+        border_unfocused: Color::Rgb(0x68, 0x73, 0x84),
+        focus_accent: Color::Rgb(0x72, 0xd6, 0x87),
+        group_row: Color::Rgb(0xb6, 0xc1, 0xd3),
+        mode_normal_bg: Color::Rgb(0x72, 0xd6, 0x87),
+        mode_normal_fg: Color::Rgb(0x1f, 0x23, 0x2b),
+        mode_insert_bg: Color::Rgb(0xf2, 0xc9, 0x5c),
+        mode_insert_fg: Color::Rgb(0x1f, 0x23, 0x2b),
+        error_text: Color::Rgb(0xff, 0x82, 0x7a),
+    };
+
+    /// A high-contrast light peer to [`Self::DARK`].
+    pub const LIGHT: Palette = Palette {
+        card: Surface {
+            bg: Color::Rgb(0xff, 0xff, 0xff),
+            fg: Color::Rgb(0x27, 0x31, 0x3d),
+            muted: Color::Rgb(0x4c, 0x5b, 0x6b),
+            dim: Color::Rgb(0x68, 0x78, 0x8a),
+            active: Color::Rgb(0x21, 0x7a, 0x3c),
+            idle: Color::Rgb(0x4c, 0x5b, 0x6b),
+            awaiting: Color::Rgb(0x8f, 0x63, 0x00),
+            error: Color::Rgb(0xb4, 0x23, 0x18),
+        },
+        selection: Surface {
+            bg: Color::Rgb(0xb5, 0xcf, 0xba),
+            fg: Color::Rgb(0x1d, 0x2a, 0x24),
+            muted: Color::Rgb(0x3f, 0x55, 0x45),
+            dim: Color::Rgb(0x52, 0x68, 0x5a),
+            active: Color::Rgb(0x15, 0x5b, 0x2e),
+            idle: Color::Rgb(0x3f, 0x55, 0x45),
+            awaiting: Color::Rgb(0x69, 0x46, 0x00),
+            error: Color::Rgb(0xa5, 0x1d, 0x14),
+        },
+        chrome_bg: Color::Rgb(0xff, 0xff, 0xff),
+        sidebar_focus_bg: Color::Rgb(0xee, 0xf5, 0xef),
+        border_focused: Color::Rgb(0x21, 0x7a, 0x3c),
+        border_unfocused: Color::Rgb(0x65, 0x73, 0x6b),
+        focus_accent: Color::Rgb(0x21, 0x7a, 0x3c),
+        group_row: Color::Rgb(0x3f, 0x55, 0x45),
+        mode_normal_bg: Color::Rgb(0x21, 0x7a, 0x3c),
+        mode_normal_fg: Color::Rgb(0xff, 0xff, 0xff),
+        mode_insert_bg: Color::Rgb(0xb6, 0x81, 0x08),
+        mode_insert_fg: Color::Rgb(0x0b, 0x12, 0x0e),
+        error_text: Color::Rgb(0xb4, 0x23, 0x18),
+    };
+
+    /// A palette of named ANSI colours for terminals without truecolour.
+    pub const ANSI: Palette = Palette {
+        card: Surface {
+            bg: Color::Black,
+            fg: Color::White,
+            muted: Color::Gray,
+            dim: Color::DarkGray,
+            active: Color::Green,
+            idle: Color::Gray,
+            awaiting: Color::Yellow,
+            error: Color::Red,
+        },
+        selection: Surface {
+            bg: Color::Blue,
+            fg: Color::White,
+            muted: Color::White,
+            dim: Color::LightBlue,
+            active: Color::LightGreen,
+            idle: Color::White,
+            awaiting: Color::LightYellow,
+            error: Color::LightRed,
+        },
+        chrome_bg: Color::Black,
+        sidebar_focus_bg: Color::DarkGray,
+        border_focused: Color::LightGreen,
+        border_unfocused: Color::DarkGray,
+        focus_accent: Color::LightGreen,
+        group_row: Color::LightCyan,
+        mode_normal_bg: Color::Green,
+        mode_normal_fg: Color::Black,
+        mode_insert_bg: Color::Yellow,
+        mode_insert_fg: Color::Black,
+        error_text: Color::LightRed,
+    };
+
+    /// Solarized Dark — Ethan Schoonover's low-contrast classic,
+    /// accents lifted where the originals fall short of WCAG AA.
+    pub const SOLARIZED_DARK: Palette = Palette {
+        card: Surface {
+            bg: Color::Rgb(0x00, 0x2b, 0x36),
+            fg: Color::Rgb(0x93, 0xa1, 0xa1),
+            muted: Color::Rgb(0x83, 0x94, 0x96),
+            dim: Color::Rgb(0x65, 0x7b, 0x83),
+            active: Color::Rgb(0x85, 0x99, 0x00),
+            idle: Color::Rgb(0x83, 0x94, 0x96),
+            awaiting: Color::Rgb(0xb5, 0x89, 0x00),
+            error: Color::Rgb(0xe5, 0x68, 0x65),
+        },
+        selection: Surface {
+            bg: Color::Rgb(0x10, 0x53, 0x62),
+            fg: Color::Rgb(0xb6, 0xc0, 0xc0),
+            muted: Color::Rgb(0xb5, 0xc0, 0xc1),
+            dim: Color::Rgb(0x8b, 0x9f, 0xa6),
+            active: Color::Rgb(0xaf, 0xca, 0x00),
+            idle: Color::Rgb(0xb5, 0xc0, 0xc1),
+            awaiting: Color::Rgb(0xef, 0xb5, 0x00),
+            error: Color::Rgb(0xf1, 0xad, 0xab),
+        },
+        chrome_bg: Color::Rgb(0x00, 0x2b, 0x36),
+        sidebar_focus_bg: Color::Rgb(0x00, 0x1a, 0x21),
+        border_focused: Color::Rgb(0x2a, 0xa1, 0x98),
+        border_unfocused: Color::Rgb(0x5e, 0x76, 0x7e),
+        focus_accent: Color::Rgb(0x2a, 0xa1, 0x98),
+        group_row: Color::Rgb(0x93, 0xa1, 0xa1),
+        mode_normal_bg: Color::Rgb(0x2a, 0xa1, 0x98),
+        mode_normal_fg: Color::Rgb(0x00, 0x2b, 0x36),
+        mode_insert_bg: Color::Rgb(0xb5, 0x89, 0x00),
+        mode_insert_fg: Color::Rgb(0x00, 0x2b, 0x36),
+        error_text: Color::Rgb(0xe5, 0x68, 0x65),
+    };
+
+    /// Solarized Light — the warm cream-paper peer of Solarized Dark.
+    pub const SOLARIZED_LIGHT: Palette = Palette {
+        card: Surface {
+            bg: Color::Rgb(0xfd, 0xf6, 0xe3),
+            fg: Color::Rgb(0x58, 0x6e, 0x75),
+            muted: Color::Rgb(0x5e, 0x73, 0x7a),
+            dim: Color::Rgb(0x7e, 0x8f, 0x92),
+            active: Color::Rgb(0x67, 0x76, 0x00),
+            idle: Color::Rgb(0x5e, 0x73, 0x7a),
+            awaiting: Color::Rgb(0x8d, 0x6a, 0x00),
+            error: Color::Rgb(0xd7, 0x27, 0x24),
+        },
+        selection: Surface {
+            bg: Color::Rgb(0xcb, 0xbd, 0x93),
+            fg: Color::Rgb(0x3f, 0x4e, 0x53),
+            muted: Color::Rgb(0x40, 0x4e, 0x53),
+            dim: Color::Rgb(0x59, 0x67, 0x69),
+            active: Color::Rgb(0x46, 0x50, 0x00),
+            idle: Color::Rgb(0x40, 0x4e, 0x53),
+            awaiting: Color::Rgb(0x60, 0x48, 0x00),
+            error: Color::Rgb(0x94, 0x1b, 0x19),
+        },
+        chrome_bg: Color::Rgb(0xfd, 0xf6, 0xe3),
+        sidebar_focus_bg: Color::Rgb(0xf7, 0xf4, 0xed),
+        border_focused: Color::Rgb(0x29, 0x9b, 0x93),
+        border_unfocused: Color::Rgb(0x7f, 0x8f, 0x8f),
+        focus_accent: Color::Rgb(0x29, 0x9b, 0x93),
+        group_row: Color::Rgb(0x58, 0x6e, 0x75),
+        mode_normal_bg: Color::Rgb(0x2a, 0xa1, 0x98),
+        mode_normal_fg: Color::Rgb(0x00, 0x2b, 0x36),
+        mode_insert_bg: Color::Rgb(0x8d, 0x6a, 0x00),
+        mode_insert_fg: Color::Rgb(0xfd, 0xf6, 0xe3),
+        error_text: Color::Rgb(0xd7, 0x27, 0x24),
+    };
+
+    /// Catppuccin Mocha — soothing pastels on a soft dark base.
+    pub const CATPPUCCIN: Palette = Palette {
+        card: Surface {
+            bg: Color::Rgb(0x1e, 0x1e, 0x2e),
+            fg: Color::Rgb(0xcd, 0xd6, 0xf4),
+            muted: Color::Rgb(0xa6, 0xad, 0xc8),
+            dim: Color::Rgb(0x7f, 0x84, 0x9c),
+            active: Color::Rgb(0xa6, 0xe3, 0xa1),
+            idle: Color::Rgb(0xa6, 0xad, 0xc8),
+            awaiting: Color::Rgb(0xf9, 0xe2, 0xaf),
+            error: Color::Rgb(0xf3, 0x8b, 0xa8),
+        },
+        selection: Surface {
+            bg: Color::Rgb(0x45, 0x47, 0x5a),
+            fg: Color::Rgb(0xcd, 0xd6, 0xf4),
+            muted: Color::Rgb(0xb2, 0xb8, 0xcf),
+            dim: Color::Rgb(0x92, 0x97, 0xab),
+            active: Color::Rgb(0xb5, 0xe8, 0xb1),
+            idle: Color::Rgb(0xb2, 0xb8, 0xcf),
+            awaiting: Color::Rgb(0xfa, 0xe9, 0xc2),
+            error: Color::Rgb(0xf5, 0xa1, 0xb8),
+        },
+        chrome_bg: Color::Rgb(0x1e, 0x1e, 0x2e),
+        sidebar_focus_bg: Color::Rgb(0x2a, 0x2a, 0x3c),
+        border_focused: Color::Rgb(0xcb, 0xa6, 0xf7),
+        border_unfocused: Color::Rgb(0x6c, 0x70, 0x86),
+        focus_accent: Color::Rgb(0xcb, 0xa6, 0xf7),
+        group_row: Color::Rgb(0xb4, 0xbe, 0xfe),
+        mode_normal_bg: Color::Rgb(0xcb, 0xa6, 0xf7),
+        mode_normal_fg: Color::Rgb(0x1e, 0x1e, 0x2e),
+        mode_insert_bg: Color::Rgb(0xf9, 0xe2, 0xaf),
+        mode_insert_fg: Color::Rgb(0x1e, 0x1e, 0x2e),
+        error_text: Color::Rgb(0xf3, 0x8b, 0xa8),
+    };
+
+    /// GitHub Dark — the github.com dark default.
+    pub const GITHUB_DARK: Palette = Palette {
+        card: Surface {
+            bg: Color::Rgb(0x0d, 0x11, 0x17),
+            fg: Color::Rgb(0xe6, 0xed, 0xf3),
+            muted: Color::Rgb(0x91, 0x98, 0xa1),
+            dim: Color::Rgb(0x6e, 0x76, 0x81),
+            active: Color::Rgb(0x3f, 0xb9, 0x50),
+            idle: Color::Rgb(0x91, 0x98, 0xa1),
+            awaiting: Color::Rgb(0xd2, 0x99, 0x22),
+            error: Color::Rgb(0xf8, 0x51, 0x49),
+        },
+        selection: Surface {
+            bg: Color::Rgb(0x1f, 0x3a, 0x5f),
+            fg: Color::Rgb(0xe6, 0xed, 0xf3),
+            muted: Color::Rgb(0x9f, 0xa5, 0xad),
+            dim: Color::Rgb(0x7e, 0x86, 0x91),
+            active: Color::Rgb(0x40, 0xbc, 0x51),
+            idle: Color::Rgb(0x9f, 0xa5, 0xad),
+            awaiting: Color::Rgb(0xd4, 0x9b, 0x22),
+            error: Color::Rgb(0xfa, 0x81, 0x7b),
+        },
+        chrome_bg: Color::Rgb(0x0d, 0x11, 0x17),
+        sidebar_focus_bg: Color::Rgb(0x16, 0x1b, 0x26),
+        border_focused: Color::Rgb(0x58, 0xa6, 0xff),
+        border_unfocused: Color::Rgb(0x58, 0x64, 0x70),
+        focus_accent: Color::Rgb(0x58, 0xa6, 0xff),
+        group_row: Color::Rgb(0x91, 0x98, 0xa1),
+        mode_normal_bg: Color::Rgb(0x58, 0xa6, 0xff),
+        mode_normal_fg: Color::Rgb(0x0d, 0x11, 0x17),
+        mode_insert_bg: Color::Rgb(0xd2, 0x99, 0x22),
+        mode_insert_fg: Color::Rgb(0x0d, 0x11, 0x17),
+        error_text: Color::Rgb(0xf8, 0x51, 0x49),
+    };
+
+    /// GitHub Light — the github.com light default.
+    pub const GITHUB_LIGHT: Palette = Palette {
+        card: Surface {
+            bg: Color::Rgb(0xff, 0xff, 0xff),
+            fg: Color::Rgb(0x1f, 0x23, 0x28),
+            muted: Color::Rgb(0x59, 0x63, 0x6e),
+            dim: Color::Rgb(0x81, 0x8b, 0x98),
+            active: Color::Rgb(0x1a, 0x7f, 0x37),
+            idle: Color::Rgb(0x59, 0x63, 0x6e),
+            awaiting: Color::Rgb(0x9a, 0x67, 0x00),
+            error: Color::Rgb(0xd1, 0x24, 0x2f),
+        },
+        selection: Surface {
+            bg: Color::Rgb(0xa5, 0xcd, 0xf0),
+            fg: Color::Rgb(0x1f, 0x23, 0x28),
+            muted: Color::Rgb(0x4b, 0x53, 0x5d),
+            dim: Color::Rgb(0x64, 0x6d, 0x7a),
+            active: Color::Rgb(0x14, 0x5f, 0x29),
+            idle: Color::Rgb(0x4b, 0x53, 0x5d),
+            awaiting: Color::Rgb(0x71, 0x4b, 0x00),
+            error: Color::Rgb(0xa1, 0x1c, 0x24),
+        },
+        chrome_bg: Color::Rgb(0xff, 0xff, 0xff),
+        sidebar_focus_bg: Color::Rgb(0xf0, 0xf6, 0xfc),
+        border_focused: Color::Rgb(0x09, 0x69, 0xda),
+        border_unfocused: Color::Rgb(0x89, 0x93, 0x9d),
+        focus_accent: Color::Rgb(0x09, 0x69, 0xda),
+        group_row: Color::Rgb(0x59, 0x63, 0x6e),
+        mode_normal_bg: Color::Rgb(0x09, 0x69, 0xda),
+        mode_normal_fg: Color::Rgb(0xff, 0xff, 0xff),
+        mode_insert_bg: Color::Rgb(0x9a, 0x67, 0x00),
+        mode_insert_fg: Color::Rgb(0xff, 0xff, 0xff),
+        error_text: Color::Rgb(0xd1, 0x24, 0x2f),
+    };
+
+    /// Tokyo Night — neon-tinted blues of the VS Code / vim favourite.
+    pub const TOKYO_NIGHT: Palette = Palette {
+        card: Surface {
+            bg: Color::Rgb(0x1a, 0x1b, 0x26),
+            fg: Color::Rgb(0xc0, 0xca, 0xf5),
+            muted: Color::Rgb(0xa9, 0xb1, 0xd6),
+            dim: Color::Rgb(0x5d, 0x67, 0x95),
+            active: Color::Rgb(0x9e, 0xce, 0x6a),
+            idle: Color::Rgb(0xa9, 0xb1, 0xd6),
+            awaiting: Color::Rgb(0xe0, 0xaf, 0x68),
+            error: Color::Rgb(0xf7, 0x76, 0x8e),
+        },
+        selection: Surface {
+            bg: Color::Rgb(0x33, 0x46, 0x7c),
+            fg: Color::Rgb(0xc0, 0xca, 0xf5),
+            muted: Color::Rgb(0xb0, 0xb8, 0xd9),
+            dim: Color::Rgb(0x8e, 0x96, 0xb8),
+            active: Color::Rgb(0xa8, 0xd3, 0x79),
+            idle: Color::Rgb(0xb0, 0xb8, 0xd9),
+            awaiting: Color::Rgb(0xe1, 0xb1, 0x6b),
+            error: Color::Rgb(0xf9, 0xa0, 0xb0),
+        },
+        chrome_bg: Color::Rgb(0x1a, 0x1b, 0x26),
+        sidebar_focus_bg: Color::Rgb(0x24, 0x28, 0x3b),
+        border_focused: Color::Rgb(0x7a, 0xa2, 0xf7),
+        border_unfocused: Color::Rgb(0x5d, 0x67, 0x95),
+        focus_accent: Color::Rgb(0x7a, 0xa2, 0xf7),
+        group_row: Color::Rgb(0xa9, 0xb1, 0xd6),
+        mode_normal_bg: Color::Rgb(0x7a, 0xa2, 0xf7),
+        mode_normal_fg: Color::Rgb(0x1a, 0x1b, 0x26),
+        mode_insert_bg: Color::Rgb(0xe0, 0xaf, 0x68),
+        mode_insert_fg: Color::Rgb(0x1a, 0x1b, 0x26),
+        error_text: Color::Rgb(0xf7, 0x76, 0x8e),
+    };
+
+    /// Gruvbox Dark — retro warm earth tones.
+    pub const GRUVBOX: Palette = Palette {
+        card: Surface {
+            bg: Color::Rgb(0x28, 0x28, 0x28),
+            fg: Color::Rgb(0xeb, 0xdb, 0xb2),
+            muted: Color::Rgb(0xbd, 0xae, 0x93),
+            dim: Color::Rgb(0x92, 0x83, 0x74),
+            active: Color::Rgb(0xb8, 0xbb, 0x26),
+            idle: Color::Rgb(0xbd, 0xae, 0x93),
+            awaiting: Color::Rgb(0xfa, 0xbd, 0x2f),
+            error: Color::Rgb(0xfb, 0x58, 0x44),
+        },
+        selection: Surface {
+            bg: Color::Rgb(0x50, 0x49, 0x45),
+            fg: Color::Rgb(0xeb, 0xdb, 0xb2),
+            muted: Color::Rgb(0xc7, 0xbb, 0xa4),
+            dim: Color::Rgb(0xa4, 0x98, 0x8b),
+            active: Color::Rgb(0xbf, 0xc3, 0x28),
+            idle: Color::Rgb(0xc7, 0xbb, 0xa4),
+            awaiting: Color::Rgb(0xfa, 0xc3, 0x43),
+            error: Color::Rgb(0xfd, 0xa5, 0x9a),
+        },
+        chrome_bg: Color::Rgb(0x28, 0x28, 0x28),
+        sidebar_focus_bg: Color::Rgb(0x32, 0x30, 0x2f),
+        border_focused: Color::Rgb(0xfe, 0x80, 0x19),
+        border_unfocused: Color::Rgb(0x7e, 0x71, 0x67),
+        focus_accent: Color::Rgb(0xfe, 0x80, 0x19),
+        group_row: Color::Rgb(0xd5, 0xc4, 0xa1),
+        mode_normal_bg: Color::Rgb(0xfe, 0x80, 0x19),
+        mode_normal_fg: Color::Rgb(0x28, 0x28, 0x28),
+        mode_insert_bg: Color::Rgb(0xfa, 0xbd, 0x2f),
+        mode_insert_fg: Color::Rgb(0x28, 0x28, 0x28),
+        error_text: Color::Rgb(0xfb, 0x58, 0x44),
+    };
+
+    /// Nord — arctic, bluish and calm; the red lifted to stay legible.
+    pub const NORD: Palette = Palette {
+        card: Surface {
+            bg: Color::Rgb(0x2e, 0x34, 0x40),
+            fg: Color::Rgb(0xec, 0xef, 0xf4),
+            muted: Color::Rgb(0xd8, 0xde, 0xe9),
+            dim: Color::Rgb(0x9a, 0xa5, 0xb5),
+            active: Color::Rgb(0xa3, 0xbe, 0x8c),
+            idle: Color::Rgb(0xd8, 0xde, 0xe9),
+            awaiting: Color::Rgb(0xeb, 0xcb, 0x8b),
+            error: Color::Rgb(0xd0, 0x8b, 0x91),
+        },
+        selection: Surface {
+            bg: Color::Rgb(0x4c, 0x56, 0x6a),
+            fg: Color::Rgb(0xec, 0xef, 0xf4),
+            muted: Color::Rgb(0xd8, 0xde, 0xe9),
+            dim: Color::Rgb(0x9f, 0xaa, 0xb9),
+            active: Color::Rgb(0xc0, 0xd3, 0xb0),
+            idle: Color::Rgb(0xe5, 0xe9, 0xf0),
+            awaiting: Color::Rgb(0xee, 0xd3, 0x9c),
+            error: Color::Rgb(0xe7, 0xc5, 0xc8),
+        },
+        chrome_bg: Color::Rgb(0x2e, 0x34, 0x40),
+        sidebar_focus_bg: Color::Rgb(0x35, 0x3b, 0x49),
+        border_focused: Color::Rgb(0x88, 0xc0, 0xd0),
+        border_unfocused: Color::Rgb(0x72, 0x80, 0x9a),
+        focus_accent: Color::Rgb(0x88, 0xc0, 0xd0),
+        group_row: Color::Rgb(0xd8, 0xde, 0xe9),
+        mode_normal_bg: Color::Rgb(0x88, 0xc0, 0xd0),
+        mode_normal_fg: Color::Rgb(0x2e, 0x34, 0x40),
+        mode_insert_bg: Color::Rgb(0xeb, 0xcb, 0x8b),
+        mode_insert_fg: Color::Rgb(0x2e, 0x34, 0x40),
+        error_text: Color::Rgb(0xd0, 0x8b, 0x91),
+    };
+
+    /// Dracula — high-saturation accents on a dark violet-grey base.
+    pub const DRACULA: Palette = Palette {
+        card: Surface {
+            bg: Color::Rgb(0x28, 0x2a, 0x36),
+            fg: Color::Rgb(0xf8, 0xf8, 0xf2),
+            muted: Color::Rgb(0xbf, 0xc3, 0xd9),
+            dim: Color::Rgb(0x65, 0x74, 0xa6),
+            active: Color::Rgb(0x50, 0xfa, 0x7b),
+            idle: Color::Rgb(0xbf, 0xc3, 0xd9),
+            awaiting: Color::Rgb(0xf1, 0xfa, 0x8c),
+            error: Color::Rgb(0xff, 0x59, 0x59),
+        },
+        selection: Surface {
+            bg: Color::Rgb(0x4a, 0x4e, 0x62),
+            fg: Color::Rgb(0xf8, 0xf8, 0xf2),
+            muted: Color::Rgb(0xbf, 0xc3, 0xd9),
+            dim: Color::Rgb(0x94, 0x9f, 0xc1),
+            active: Color::Rgb(0x64, 0xfb, 0x8a),
+            idle: Color::Rgb(0xcc, 0xcf, 0xe1),
+            awaiting: Color::Rgb(0xf3, 0xfb, 0xa0),
+            error: Color::Rgb(0xff, 0xad, 0xad),
+        },
+        chrome_bg: Color::Rgb(0x28, 0x2a, 0x36),
+        sidebar_focus_bg: Color::Rgb(0x31, 0x33, 0x42),
+        border_focused: Color::Rgb(0xbd, 0x93, 0xf9),
+        border_unfocused: Color::Rgb(0x65, 0x74, 0xa6),
+        focus_accent: Color::Rgb(0xbd, 0x93, 0xf9),
+        group_row: Color::Rgb(0xbf, 0xc3, 0xd9),
+        mode_normal_bg: Color::Rgb(0xbd, 0x93, 0xf9),
+        mode_normal_fg: Color::Rgb(0x28, 0x2a, 0x36),
+        mode_insert_bg: Color::Rgb(0xf1, 0xfa, 0x8c),
+        mode_insert_fg: Color::Rgb(0x28, 0x2a, 0x36),
+        error_text: Color::Rgb(0xff, 0x59, 0x59),
+    };
+
+    /// The default preset, retained as a named compatibility constant.
+    pub const DEFAULT: Palette = Self::DARK;
+
+    /// All preset names and their complete palettes.
+    pub fn presets() -> [(&'static str, Palette); 12] {
+        [
+            ("dark", Self::DARK),
+            ("light", Self::LIGHT),
+            ("ansi", Self::ANSI),
+            ("solarized-dark", Self::SOLARIZED_DARK),
+            ("solarized-light", Self::SOLARIZED_LIGHT),
+            ("catppuccin", Self::CATPPUCCIN),
+            ("github-dark", Self::GITHUB_DARK),
+            ("github-light", Self::GITHUB_LIGHT),
+            ("tokyo-night", Self::TOKYO_NIGHT),
+            ("gruvbox", Self::GRUVBOX),
+            ("nord", Self::NORD),
+            ("dracula", Self::DRACULA),
+        ]
+    }
+
+    /// Resolve a config name to a palette.
+    pub fn named(name: &str) -> Option<Palette> {
+        Self::presets()
+            .into_iter()
+            .find(|(n, _)| *n == name)
+            .map(|(_, p)| p)
+    }
+
+    /// Every role, including the backgrounds it is painted against.
+    pub fn roles(&self) -> [(&'static str, Color); 27] {
+        [
+            ("card.bg", self.card.bg),
+            ("card.fg", self.card.fg),
+            ("card.muted", self.card.muted),
+            ("card.dim", self.card.dim),
+            ("card.active", self.card.active),
+            ("card.idle", self.card.idle),
+            ("card.awaiting", self.card.awaiting),
+            ("card.error", self.card.error),
+            ("selection.bg", self.selection.bg),
+            ("selection.fg", self.selection.fg),
+            ("selection.muted", self.selection.muted),
+            ("selection.dim", self.selection.dim),
+            ("selection.active", self.selection.active),
+            ("selection.idle", self.selection.idle),
+            ("selection.awaiting", self.selection.awaiting),
+            ("selection.error", self.selection.error),
+            ("chrome_bg", self.chrome_bg),
+            ("sidebar_focus_bg", self.sidebar_focus_bg),
+            ("border_focused", self.border_focused),
+            ("border_unfocused", self.border_unfocused),
+            ("focus_accent", self.focus_accent),
+            ("group_row", self.group_row),
+            ("mode_normal_bg", self.mode_normal_bg),
+            ("mode_normal_fg", self.mode_normal_fg),
+            ("mode_insert_bg", self.mode_insert_bg),
+            ("mode_insert_fg", self.mode_insert_fg),
+            ("error_text", self.error_text),
+        ]
+    }
+
+    /// The surface a card sits on: the selection surface when it is the
+    /// highlighted card, the card surface otherwise.
+    pub fn surface(&self, selected: bool) -> &Surface {
+        if selected {
+            &self.selection
+        } else {
+            &self.card
+        }
+    }
+
+    /// Border style for a panel, by whether it holds focus.
+    pub fn border_style(&self, focused: bool) -> Style {
+        if focused {
+            Style::default().bg(self.chrome_bg).fg(self.border_focused)
+        } else {
+            Style::default()
+                .bg(self.chrome_bg)
+                .fg(self.border_unfocused)
+        }
+    }
+
+    /// Style for a sidebar group heading.
+    pub fn group_row_style(&self) -> Style {
+        Style::default()
+            .bg(self.chrome_bg)
+            .fg(self.group_row)
+            .add_modifier(Modifier::BOLD)
+    }
+
+    /// Style for the status bar's mode indicator.
+    pub fn mode_style(&self, insert: bool) -> Style {
+        if insert {
+            Style::default()
+                .fg(self.mode_insert_fg)
+                .bg(self.mode_insert_bg)
+        } else {
+            Style::default()
+                .fg(self.mode_normal_fg)
+                .bg(self.mode_normal_bg)
+        }
+    }
+
+    /// Style for error text outside a card.
+    pub fn error_style(&self) -> Style {
+        Style::default().bg(self.chrome_bg).fg(self.error_text)
+    }
+}
+
+impl Default for Palette {
+    fn default() -> Self {
+        Self::DEFAULT
+    }
+}
+
+fn active_slot() -> &'static std::sync::RwLock<Palette> {
+    static ACTIVE: std::sync::OnceLock<std::sync::RwLock<Palette>> = std::sync::OnceLock::new();
+    ACTIVE.get_or_init(|| std::sync::RwLock::new(Palette::DEFAULT))
+}
+
+/// Set the palette used by the running TUI.
+pub(crate) fn set_active(palette: Palette) {
+    *active_slot().write().expect("active palette lock poisoned") = palette;
+}
+
+/// The palette in force. Config-driven preset selection lands here at TUI
+/// startup, before the first frame is drawn.
+pub fn active() -> Palette {
+    *active_slot().read().expect("active palette lock poisoned")
+}
+
+/// WCAG relative luminance of an RGB role. Non-RGB colours have no fixed
+/// luminance — they are whatever the terminal theme says — so they return
+/// `None` and cannot be contrast-checked.
+pub fn relative_luminance(color: Color) -> Option<f64> {
+    let Color::Rgb(r, g, b) = color else {
+        return None;
+    };
+    fn channel(v: u8) -> f64 {
+        let v = v as f64 / 255.0;
+        if v <= 0.03928 {
+            v / 12.92
+        } else {
+            ((v + 0.055) / 1.055).powf(2.4)
+        }
+    }
+    Some(0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b))
+}
+
+/// WCAG contrast ratio between two RGB roles, 1.0 (identical) to 21.0
+/// (black on white). `None` if either colour is not RGB.
+pub fn contrast_ratio(a: Color, b: Color) -> Option<f64> {
+    let (la, lb) = (relative_luminance(a)?, relative_luminance(b)?);
+    let (hi, lo) = if la >= lb { (la, lb) } else { (lb, la) };
+    Some((hi + 0.05) / (lo + 0.05))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const STATES: [ActivityState; 4] = [
+        ActivityState::Active,
+        ActivityState::Idle,
+        ActivityState::AwaitingInput,
+        ActivityState::Error,
+    ];
+
+    /// Every preset except `ansi`, whose colours the terminal owns and which
+    /// therefore has no fixed luminance to assert against.
+    fn rgb_presets() -> impl Iterator<Item = (&'static str, Palette)> {
+        Palette::presets()
+            .into_iter()
+            .filter(|(_, p)| relative_luminance(p.card.bg).is_some())
+    }
+
+    /// Text roles clear WCAG AA (4.5:1) against their own surface; `dim` is
+    /// decoration and only has to clear the 3:1 non-text threshold.
+    #[test]
+    fn every_role_is_legible_on_its_own_surface() {
+        for (preset, p) in rgb_presets() {
+            for (surface_name, surface) in [("card", &p.card), ("selection", &p.selection)] {
+                for (role, color) in surface.roles() {
+                    let ratio = contrast_ratio(surface.bg, color)
+                        .unwrap_or_else(|| panic!("{preset}.{surface_name}.{role} must be RGB"));
+                    let floor = if role == "dim" { 3.0 } else { 4.5 };
+                    assert!(
+                        ratio >= floor,
+                        "{preset}.{surface_name}.{role} contrast {ratio:.2} is below {floor}"
+                    );
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn every_preset_supplies_every_role() {
+        for (name, p) in Palette::presets() {
+            assert_eq!(p.roles().len(), 27, "{name} role set is incomplete");
+            assert_eq!(Palette::named(name), Some(p));
+        }
+        assert_eq!(Palette::named("unknown"), None);
+    }
+
+    /// The selection background exists to be seen as a different surface, not
+    /// merely a slightly different shade of the card.
+    #[test]
+    fn selection_background_is_distinguishable_from_the_card_background() {
+        for (name, p) in rgb_presets() {
+            let ratio = contrast_ratio(p.card.bg, p.selection.bg).unwrap();
+            assert!(
+                ratio >= 1.6,
+                "{name} card and selection backgrounds differ by only {ratio:.2}"
+            );
+        }
+    }
+
+    /// The bug this palette fixes: a state colour chosen for the dark card
+    /// background is not legible on the selection background, so the
+    /// selection surface carries its own — distinct — state colours.
+    #[test]
+    fn selection_state_colours_are_not_the_card_state_colours() {
+        for (name, p) in Palette::presets() {
+            for state in STATES {
+                assert_ne!(
+                    p.card.activity(state),
+                    p.selection.activity(state),
+                    "{name} {state:?} must have a selection-specific colour"
+                );
+            }
+        }
+    }
+
+    /// Other panels' roles are RGB too, so a preset swap moves all of them.
+    /// Foregrounds are checked against the chrome background they are
+    /// actually painted on; they must never rely on the terminal default.
+    #[test]
+    fn chrome_roles_are_rgb_values() {
+        for (preset, p) in rgb_presets() {
+            for (name, color) in p.roles().into_iter().skip(16) {
+                assert!(
+                    relative_luminance(color).is_some(),
+                    "{preset}.{name} must be an RGB value"
+                );
+            }
+            // The mode indicator paints fg on bg; both pairs must stay readable.
+            for (name, fg, bg) in [
+                ("normal", p.mode_normal_fg, p.mode_normal_bg),
+                ("insert", p.mode_insert_fg, p.mode_insert_bg),
+            ] {
+                let ratio = contrast_ratio(fg, bg).unwrap();
+                assert!(
+                    ratio >= 4.5,
+                    "{preset} mode {name} contrast {ratio:.2} is below 4.5"
+                );
+            }
+            for (name, fg, floor) in [
+                ("border_focused", p.border_focused, 3.0),
+                ("border_unfocused", p.border_unfocused, 3.0),
+                ("focus_accent", p.focus_accent, 3.0),
+                ("group_row", p.group_row, 4.5),
+                ("error_text", p.error_text, 4.5),
+            ] {
+                let ratio = contrast_ratio(fg, p.chrome_bg).unwrap();
+                assert!(
+                    ratio >= floor,
+                    "{preset}.{name} contrast {ratio:.2} is below {floor} on chrome_bg"
+                );
+            }
+            for (name, fg) in [
+                ("card.fg", p.card.fg),
+                ("card.muted", p.card.muted),
+                ("group_row", p.group_row),
+            ] {
+                let ratio = contrast_ratio(fg, p.sidebar_focus_bg).unwrap();
+                assert!(
+                    ratio >= 4.5,
+                    "{preset}.{name} contrast {ratio:.2} is below 4.5 on sidebar_focus_bg"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn contrast_ratio_matches_known_values() {
+        let black = Color::Rgb(0, 0, 0);
+        let white = Color::Rgb(255, 255, 255);
+        assert!((contrast_ratio(black, white).unwrap() - 21.0).abs() < 0.01);
+        assert!((contrast_ratio(white, white).unwrap() - 1.0).abs() < 0.01);
+        assert_eq!(contrast_ratio(Color::Cyan, white), None);
+    }
+}

crates/maestro-tui/src/pane.rs

@@ -74,7 +74,7 @@ impl Pane {
 
         // Place the terminal cursor at vt100's cursor position when we own
         // focus and the cursor is on-screen. Terminals blink it on their own.
-        if self.focused && !screen.hide_cursor() {
+        if self.focused && screen.scrollback() == 0 && !screen.hide_cursor() {
             let (cr, cc) = screen.cursor_position();
             if cr < rows && cc < cols {
                 f.set_cursor_position((area.x + cc, area.y + cr));
@@ -106,6 +106,9 @@ fn translate_cell_style(cell: &vt100::Cell) -> Style {
     s
 }
 
+/// PTY cell colours pass through verbatim: they belong to the program
+/// running in the pane, not to the TUI's own chrome, so they are deliberately
+/// not palette roles (see `crate::palette`).
 fn translate_color(c: vt100::Color) -> Option<Color> {
     match c {
         vt100::Color::Default => None,

crates/maestro-tui/src/projects.rs

@@ -0,0 +1,216 @@
+//! Pure helpers behind the draft pane's project picker (#64): staleness,
+//! recency ordering, worktree grouping, and free-text filtering. Mirrors
+//! `web/src/projectList.ts` so both clients order and dim identically — the
+//! daemon reports the timestamps; what "stale" means is a client decision
+//! (#54).
+
+use chrono::{DateTime, TimeDelta, Utc};
+use maestro_protocol::Project;
+
+/// Projects whose last activity is older than this are dimmed and sort after
+/// fresh ones — still reachable, visibly stale.
+pub const STALE_AFTER_DAYS: i64 = 7;
+
+/// True when a project has no usable activity timestamp, one in the future,
+/// or its last activity is older than [`STALE_AFTER_DAYS`] days.
+pub fn is_stale(project: &Project, now: DateTime<Utc>) -> bool {
+    match project.last_activity {
+        None => true,
+        Some(t) => {
+            let age = now.signed_duration_since(t);
+            age < TimeDelta::zero() || age > TimeDelta::days(STALE_AFTER_DAYS)
+        }
+    }
+}
+
+fn time_of(project: &Project) -> DateTime<Utc> {
+    project.last_activity.unwrap_or(DateTime::UNIX_EPOCH)
+}
+
+/// Fresh projects first, each block newest-activity-first; unknown or future
+/// timestamps sort as stalest. Ties fall back to name, then path, so the
+/// order is stable.
+pub fn sort_projects(mut projects: Vec<Project>, now: DateTime<Utc>) -> Vec<Project> {
+    projects.sort_by(|a, b| {
+        let stale = is_stale(a, now).cmp(&is_stale(b, now));
+        stale
+            .then_with(|| time_of(b).cmp(&time_of(a)))
+            .then_with(|| a.name.cmp(&b.name))
+            .then_with(|| a.path.cmp(&b.path))
+    });
+    projects
+}
+
+/// Substring filter over project name and full path, case-insensitive.
+pub fn matches_filter(project: &Project, query: &str) -> bool {
+    let q = query.trim().to_lowercase();
+    if q.is_empty() {
+        return true;
+    }
+    project.name.to_lowercase().contains(&q)
+        || project.path.to_string_lossy().to_lowercase().contains(&q)
+}
+
+/// One repository group: the main checkout followed by its linked worktrees.
+/// A group's position follows its freshest member, since a worktree worked on
+/// today should pull its (dormant) base repo up with it.
+#[derive(Debug)]
+pub struct ProjectGroup<'a> {
+    pub main: &'a Project,
+    pub worktrees: Vec<&'a Project>,
+}
+
+/// Group `sorted` projects by their base repository. A worktree nests under
+/// its main checkout even when the main sorts later; a main checkout missing
+/// from the list doesn't drop its worktrees.
+pub fn group_projects(sorted: &[Project]) -> Vec<ProjectGroup<'_>> {
+    let mut members: Vec<(String, Vec<&Project>)> = Vec::new();
+    for p in sorted {
+        let key = p
+            .base_repo
+            .as_ref()
+            .unwrap_or(&p.path)
+            .to_string_lossy()
+            .into_owned();
+        match members.iter_mut().find(|(k, _)| *k == key) {
+            Some((_, list)) => list.push(p),
+            None => members.push((key, vec![p])),
+        }
+    }
+    members
+        .into_iter()
+        .map(|(key, mut list)| {
+            let main_pos = list
+                .iter()
+                .position(|p| p.path.to_string_lossy() == key && !p.is_worktree)
+                .unwrap_or(0);
+            let main = list.remove(main_pos);
+            // Keep the daemon's newest-first order within the group.
+            list.sort_by_key(|p| std::cmp::Reverse(time_of(p)));
+            ProjectGroup {
+                main,
+                worktrees: list,
+            }
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    fn days_ago(days: i64) -> DateTime<Utc> {
+        Utc::now() - TimeDelta::days(days)
+    }
+
+    fn project(name: &str, path: &str, last_activity: Option<DateTime<Utc>>) -> Project {
+        Project {
+            path: PathBuf::from(path),
+            name: name.into(),
+            is_worktree: false,
+            base_repo: None,
+            last_activity,
+            last_command: None,
+        }
+    }
+
+    fn worktree(
+        name: &str,
+        path: &str,
+        base: &str,
+        last_activity: Option<DateTime<Utc>>,
+    ) -> Project {
+        Project {
+            is_worktree: true,
+            base_repo: Some(PathBuf::from(base)),
+            ..project(name, path, last_activity)
+        }
+    }
+
+    #[test]
+    fn unknown_and_future_activity_are_stale() {
+        let now = Utc::now();
+        assert!(is_stale(&project("x", "/x", None), now));
+        assert!(is_stale(
+            &project("x", "/x", Some(now + TimeDelta::hours(1))),
+            now
+        ));
+    }
+
+    #[test]
+    fn activity_within_a_week_is_fresh_beyond_is_stale() {
+        let now = Utc::now();
+        assert!(!is_stale(&project("x", "/x", Some(days_ago(6))), now));
+        assert!(is_stale(&project("x", "/x", Some(days_ago(8))), now));
+    }
+
+    #[test]
+    fn fresh_sorts_before_stale_then_newest_first() {
+        let now = Utc::now();
+        let sorted = sort_projects(
+            vec![
+                project("old-fresh", "/a", Some(days_ago(5))),
+                project("stale", "/b", Some(days_ago(30))),
+                project("newest", "/c", Some(days_ago(1))),
+                project("unknown", "/d", None),
+            ],
+            now,
+        );
+        let names: Vec<&str> = sorted.iter().map(|p| p.name.as_str()).collect();
+        assert_eq!(names, ["newest", "old-fresh", "stale", "unknown"]);
+    }
+
+    #[test]
+    fn ties_break_by_name_then_path() {
+        let now = Utc::now();
+        let t = Some(days_ago(2));
+        let sorted = sort_projects(vec![project("b", "/b", t), project("a", "/a", t)], now);
+        let names: Vec<&str> = sorted.iter().map(|p| p.name.as_str()).collect();
+        assert_eq!(names, ["a", "b"]);
+    }
+
+    #[test]
+    fn filter_matches_name_or_path_case_insensitively() {
+        let p = project("Maestro", "/home/u/tea/Maestro", None);
+        assert!(matches_filter(&p, "maes"));
+        assert!(matches_filter(&p, " tea "));
+        assert!(!matches_filter(&p, "zzz"));
+        assert!(matches_filter(&p, ""), "empty query matches everything");
+    }
+
+    #[test]
+    fn worktrees_nest_under_their_main_checkout() {
+        let now = Utc::now();
+        let main = project("maestro", "/repos/maestro", Some(days_ago(10)));
+        let wt = worktree("64-tui", "/repos/wt64", "/repos/maestro", Some(days_ago(1)));
+        let other = project("other", "/repos/other", Some(days_ago(2)));
+        let sorted = sort_projects(vec![main, wt, other], now);
+        let groups = group_projects(&sorted);
+        assert_eq!(groups.len(), 2);
+        assert_eq!(
+            groups[0].main.name, "maestro",
+            "fresh worktree pulls its repo up"
+        );
+        assert_eq!(groups[0].worktrees.len(), 1);
+        assert_eq!(groups[0].worktrees[0].name, "64-tui");
+        assert_eq!(groups[1].main.name, "other");
+    }
+
+    /// A main checkout absent from the scan must not drop its worktrees.
+    #[test]
+    fn worktrees_survive_a_missing_main_checkout() {
+        let now = Utc::now();
+        let wt = worktree(
+            "solo-wt",
+            "/repos/solo-wt",
+            "/repos/solo",
+            Some(days_ago(1)),
+        );
+        let sorted = sort_projects(vec![wt], now);
+        let groups = group_projects(&sorted);
+        assert_eq!(groups.len(), 1);
+        assert_eq!(groups[0].main.name, "solo-wt");
+        assert!(groups[0].worktrees.is_empty());
+    }
+}

crates/maestro-tui/src/render.rs

@@ -1,27 +1,27 @@
-//! Top-level draw orchestration. Composes sidebar / tab bar / pane / overlays
+//! Top-level draw orchestration. Composes sidebar / pane / overlays
 //! into one frame, and returns a [`RegionMap`] that the input router uses to
 //! hit-test mouse clicks.
 
 use ratatui::layout::{Constraint, Direction, Layout, Rect};
-use ratatui::style::{Color, Style};
+use ratatui::style::Modifier;
 use ratatui::text::Span;
-use ratatui::widgets::{Block, Borders, Paragraph};
+use ratatui::widgets::Paragraph;
 use ratatui::Frame;
 
 use crate::input::Region;
 use crate::keymap::Mode;
-use crate::overlays::{HelpOverlay, KillConfirm, SpawnModal, Toast};
+use crate::overlays::{HelpOverlay, KillConfirm, RenamePrompt, Toast};
+use crate::palette;
 use crate::pane::Pane;
 use crate::sidebar::Sidebar;
-use crate::state::{AppState, Focus, OverlayKind};
-use crate::tabs::TabBar;
+use crate::state::{AppState, Focus, OverlayKind, SidebarItem};
 
 /// Tagged regions for mouse hit-testing. The input router resolves a mouse
 /// coordinate to one of these via [`RegionMap::region_at`].
 #[derive(Debug, Default, Clone)]
 pub struct RegionMap {
     pub sidebar: Option<Rect>,
-    pub tab_bar: Option<Rect>,
+    pub sidebar_items: Vec<SidebarItem>,
     pub pane: Option<Rect>,
     pub modal: Option<Rect>,
 }
@@ -33,11 +33,6 @@ impl RegionMap {
                 return Region::Modal;
             }
         }
-        if let Some(r) = self.tab_bar {
-            if inside(r, col, row) {
-                return Region::Tab;
-            }
-        }
         if let Some(r) = self.sidebar {
             if inside(r, col, row) {
                 return Region::SidebarRow;
@@ -50,6 +45,24 @@ impl RegionMap {
         }
         Region::Unknown
     }
+
+    /// Resolve a mouse row against the rendered sidebar sequence. The title
+    /// occupies one inner row; groups occupy one row and visible cards two.
+    pub fn sidebar_item_at(&self, row: u16) -> Option<SidebarItem> {
+        let area = self.sidebar?;
+        let mut cursor = area.y.saturating_add(1);
+        for item in &self.sidebar_items {
+            let height = match item {
+                SidebarItem::Group(_) => 1,
+                SidebarItem::Session(_) => 2,
+            };
+            if row >= cursor && row < cursor.saturating_add(height) {
+                return Some(item.clone());
+            }
+            cursor = cursor.saturating_add(height);
+        }
+        None
+    }
 }
 
 fn inside(r: Rect, col: u16, row: u16) -> bool {
@@ -61,11 +74,15 @@ fn inside(r: Rect, col: u16, row: u16) -> bool {
 #[derive(Debug)]
 pub struct RenderInputs<'a> {
     pub sidebar: &'a Sidebar,
-    pub tab_bar: &'a TabBar,
+    pub home_dir: &'a str,
+    pub pane_title: &'a str,
     pub pane: Option<&'a Pane>,
+    /// Inline spawn form when the pane is a draft (issue #63).
+    pub draft: Option<&'a crate::draft::DraftPane>,
     pub state: &'a AppState,
-    pub spawn: &'a SpawnModal,
     pub help: &'a HelpOverlay,
+    /// Edit buffer behind the rename prompt (#125).
+    pub rename_input: &'a crate::text_input::TextInput,
 }
 
 /// Draw one frame. Returns the `RegionMap` the input router will consult for
@@ -97,58 +114,78 @@ pub fn draw(f: &mut Frame, inputs: RenderInputs<'_>) -> RegionMap {
     let right = cols[1];
 
     if inputs.state.sidebar_visible {
-        inputs
-            .sidebar
-            .render_with_focus(f, sidebar_area, inputs.state.focus == Focus::Sidebar);
+        inputs.sidebar.render_with_focus_and_collapsed_home(
+            f,
+            sidebar_area,
+            inputs.state.focus == Focus::Sidebar,
+            &inputs.state.collapsed_sidebar_groups,
+            inputs.home_dir,
+        );
         map.sidebar = Some(sidebar_area);
+        map.sidebar_items = inputs
+            .sidebar
+            .rendered_items_with_collapsed(&inputs.state.collapsed_sidebar_groups);
     }
 
-    // 1-row tab bar + 1-row horizontal rule (doubles as the pane's focus
-    // indicator) + flex pane area below. Saves the 4 rows the old
-    // `Length(3) + Borders::ALL` layout was eating before any content showed.
     let rows = Layout::default()
         .direction(Direction::Vertical)
-        .constraints([
-            Constraint::Length(1),
-            Constraint::Length(1),
-            Constraint::Min(0),
-        ])
+        .constraints([Constraint::Length(1), Constraint::Min(0)])
         .split(right);
-    let tab_area = rows[0];
-    let separator_area = rows[1];
-    let pane_area = rows[2];
-
-    inputs.tab_bar.render(f, tab_area);
-    map.tab_bar = Some(tab_area);
+    let title_area = rows[0];
+    let pane_area = rows[1];
 
     let pane_focused = inputs.state.focus == Focus::Pane;
-    f.render_widget(
-        Block::default()
-            .borders(Borders::TOP)
-            .border_style(focus_style(pane_focused)),
-        separator_area,
-    );
+    render_title_bar(f, title_area, inputs.pane_title, pane_focused);
     if let Some(p) = inputs.pane {
         p.render(f, pane_area);
     }
+    if let Some(d) = inputs.draft {
+        d.render(f, pane_area, pane_focused);
+    }
+    // `RegionMap::pane` is also the PTY resize source. The title bar is
+    // chrome; every remaining cell belongs to the emulator.
     map.pane = Some(pane_area);
 
     // Status bar — always visible, never eclipsed by overlays so the user can
     // always see the current mode + key hints.
     render_status_bar(f, status_area, inputs.state);
 
-    match &inputs.state.overlay {
-        Some(OverlayKind::Spawn) => {
-            inputs.spawn.render(f, area);
-            map.modal = Some(area);
-        }
+    match inputs.state.overlay() {
         Some(OverlayKind::KillConfirm(id)) => {
+            // #83: surface what the watcher last saw in the worktree, in
+            // InTheWay's own words, before the operator commits to the kill.
+            let blockers = inputs
+                .sidebar
+                .sessions
+                .iter()
+                .find(|s| &s.id == id)
+                .and_then(|s| s.blocked_work)
+                .filter(|b| !b.is_clear())
+                .map(|b| b.to_string());
             let kc = KillConfirm {
                 label: id.to_string(),
+                blockers,
             };
             kc.render(f, area);
             map.modal = Some(area);
         }
+        Some(OverlayKind::Rename(id)) => {
+            let current = inputs
+                .sidebar
+                .sessions
+                .iter()
+                .find(|s| &s.id == id)
+                .map(crate::sidebar::name_for)
+                .unwrap_or_else(|| id.to_string());
+            let prompt = RenamePrompt {
+                current: &current,
+                input: inputs.rename_input,
+            };
+            if let Some((x, y)) = prompt.render(f, area) {
+                f.set_cursor_position((x, y));
+            }
+            map.modal = Some(area);
+        }
         Some(OverlayKind::Help) => {
             inputs.help.render(f, area);
             map.modal = Some(area);
@@ -163,14 +200,15 @@ pub fn draw(f: &mut Frame, inputs: RenderInputs<'_>) -> RegionMap {
     map
 }
 
-/// Border style for a panel based on whether it currently has focus.
-/// Focused = cyan; unfocused = the terminal default.
-fn focus_style(focused: bool) -> Style {
-    if focused {
-        Style::default().fg(Color::Cyan)
+fn render_title_bar(f: &mut Frame, area: Rect, title: &str, focused: bool) {
+    let palette = palette::active();
+    let style = if focused {
+        palette.mode_style(false)
     } else {
-        Style::default()
+        palette.card.text_style()
     }
+    .add_modifier(Modifier::BOLD);
+    f.render_widget(Paragraph::new(format!(" {title}")).style(style), area);
 }
 
 /// Render the always-visible status bar at the bottom of the frame. Surfaces
@@ -186,13 +224,10 @@ fn render_status_bar(f: &mut Frame, area: Rect, state: &AppState) {
         Focus::Pane => "pane",
     };
     let hint = match state.mode {
-        Mode::Normal => "j/k: nav  •  enter: attach  •  s: spawn  •  ?: help  •  ^Wq: quit",
-        Mode::Insert => "^a: back to normal",
-    };
-    let mode_style = match state.mode {
-        Mode::Normal => Style::default().fg(Color::Black).bg(Color::Cyan),
-        Mode::Insert => Style::default().fg(Color::Black).bg(Color::Yellow),
+        Mode::Normal => "j/k: nav  •  enter: attach  •  s: new draft  •  ?: help  •  ^Wq: quit",
+        Mode::Insert => "^a: return to sidebar",
     };
+    let mode_style = palette::active().mode_style(state.mode == Mode::Insert);
     let line = ratatui::text::Line::from(vec![
         Span::styled(format!(" {mode_label} "), mode_style),
         Span::raw(format!("  {focus_label}  •  {hint}")),
@@ -214,22 +249,16 @@ mod tests {
                 width: 10,
                 height: 20,
             }),
-            tab_bar: Some(Rect {
+            sidebar_items: Vec::new(),
+            pane: Some(Rect {
                 x: 10,
                 y: 0,
                 width: 30,
-                height: 3,
-            }),
-            pane: Some(Rect {
-                x: 10,
-                y: 3,
-                width: 30,
-                height: 17,
+                height: 20,
             }),
             modal: None,
         };
         assert_eq!(map.region_at(5, 5), Region::SidebarRow);
-        assert_eq!(map.region_at(15, 1), Region::Tab);
         assert_eq!(map.region_at(15, 5), Region::Pane);
         assert_eq!(map.region_at(50, 50), Region::Unknown);
     }
@@ -243,17 +272,12 @@ mod tests {
                 width: 10,
                 height: 20,
             }),
-            tab_bar: Some(Rect {
+            sidebar_items: Vec::new(),
+            pane: Some(Rect {
                 x: 10,
                 y: 0,
                 width: 30,
-                height: 3,
-            }),
-            pane: Some(Rect {
-                x: 10,
-                y: 3,
-                width: 30,
-                height: 17,
+                height: 20,
             }),
             modal: Some(Rect {
                 x: 5,
@@ -266,4 +290,181 @@ mod tests {
         assert_eq!(map.region_at(15, 10), Region::Modal);
         assert_eq!(map.region_at(3, 12), Region::SidebarRow); // outside modal
     }
+
+    #[test]
+    fn sidebar_mouse_rows_follow_group_and_two_line_card_heights() {
+        use std::path::PathBuf;
+        use uuid::Uuid;
+
+        let group_a = SidebarItem::Group(PathBuf::from("/a"));
+        let card_a = SidebarItem::Session(Uuid::from_u128(1));
+        let group_b = SidebarItem::Group(PathBuf::from("/b"));
+        let card_b = SidebarItem::Session(Uuid::from_u128(2));
+        let map = RegionMap {
+            sidebar: Some(Rect::new(0, 0, 28, 10)),
+            sidebar_items: vec![group_a.clone(), card_a.clone(), group_b.clone(), card_b],
+            ..RegionMap::default()
+        };
+        assert_eq!(map.sidebar_item_at(1), Some(group_a));
+        assert_eq!(map.sidebar_item_at(2), Some(card_a.clone()));
+        assert_eq!(map.sidebar_item_at(3), Some(card_a));
+        assert_eq!(map.sidebar_item_at(4), Some(group_b));
+
+        let collapsed = RegionMap {
+            sidebar: Some(Rect::new(0, 0, 28, 10)),
+            sidebar_items: vec![
+                SidebarItem::Group(PathBuf::from("/a")),
+                SidebarItem::Group(PathBuf::from("/b")),
+                SidebarItem::Session(Uuid::from_u128(2)),
+            ],
+            ..RegionMap::default()
+        };
+        assert_eq!(
+            collapsed.sidebar_item_at(2),
+            Some(SidebarItem::Group(PathBuf::from("/b")))
+        );
+    }
+
+    /// Issue #63: an empty pane is a draft — the frame must show the spawn
+    /// form where the terminal would otherwise be.
+    #[test]
+    fn a_draft_pane_renders_the_spawn_form_in_its_pane_area() {
+        use crate::overlays::HelpOverlay;
+        use crate::state::PaneRef;
+        use std::collections::HashSet;
+
+        let mut state = AppState::new();
+        state.open_draft_pane();
+        let draft = match &state.tabs[0].pane {
+            Some(PaneRef::Draft(d)) => d,
+            other => panic!("expected a draft pane, got {other:?}"),
+        };
+        let sidebar = Sidebar {
+            sessions: Vec::new(),
+            highlight: None,
+            attached: HashSet::new(),
+        };
+        let help = HelpOverlay { lines: Vec::new() };
+        let inputs = RenderInputs {
+            sidebar: &sidebar,
+            home_dir: "",
+            pane_title: "new session",
+            pane: None,
+            draft: Some(draft),
+            state: &state,
+            help: &help,
+            rename_input: &crate::text_input::TextInput::default(),
+        };
+
+        let backend = ratatui::backend::TestBackend::new(80, 24);
+        let mut terminal = ratatui::Terminal::new(backend).unwrap();
+        terminal
+            .draw(|f| {
+                draw(f, inputs);
+            })
+            .unwrap();
+        let buf = terminal.backend().buffer().clone();
+        let mut out = String::new();
+        for y in 0..buf.area.height {
+            for x in 0..buf.area.width {
+                out.push_str(buf[(x, y)].symbol());
+            }
+            out.push('\n');
+        }
+        for s in [
+            "new session",
+            "cmd:",
+            "dir:",
+            "name:",
+            "[ Spawn ]",
+            "Other directory…",
+        ] {
+            assert!(out.contains(s), "missing {s:?}:\n{out}");
+        }
+    }
+
+    #[test]
+    fn panel_rectangles_are_stable_when_focus_moves() {
+        use crate::overlays::HelpOverlay;
+        use crate::sidebar::Sidebar;
+        use std::collections::HashSet;
+
+        let sidebar = Sidebar {
+            sessions: Vec::new(),
+            highlight: None,
+            attached: HashSet::new(),
+        };
+        let help = HelpOverlay { lines: Vec::new() };
+        let draw_map = |focus| {
+            let mut state = AppState::new();
+            state.focus = focus;
+            let inputs = RenderInputs {
+                sidebar: &sidebar,
+                home_dir: "",
+                pane_title: "session",
+                pane: None,
+                draft: None,
+                state: &state,
+                help: &help,
+                rename_input: &crate::text_input::TextInput::default(),
+            };
+            let backend = ratatui::backend::TestBackend::new(80, 24);
+            let mut terminal = ratatui::Terminal::new(backend).unwrap();
+            let mut map = None;
+            terminal.draw(|f| map = Some(draw(f, inputs))).unwrap();
+            map.unwrap()
+        };
+
+        let sidebar_focus = draw_map(Focus::Sidebar);
+        let pane_focus = draw_map(Focus::Pane);
+        assert_eq!(sidebar_focus.sidebar, pane_focus.sidebar);
+        assert_eq!(sidebar_focus.pane, pane_focus.pane);
+        assert_eq!(sidebar_focus.pane, Some(Rect::new(28, 1, 52, 22)));
+    }
+
+    #[test]
+    fn panel_focus_uses_backgrounds_without_borders() {
+        use crate::overlays::HelpOverlay;
+        use crate::sidebar::Sidebar;
+        use std::collections::HashSet;
+
+        let sidebar = Sidebar {
+            sessions: Vec::new(),
+            highlight: None,
+            attached: HashSet::new(),
+        };
+        let help = HelpOverlay { lines: Vec::new() };
+        let render = |focus| {
+            let mut state = AppState::new();
+            state.focus = focus;
+            let inputs = RenderInputs {
+                sidebar: &sidebar,
+                home_dir: "",
+                pane_title: "session",
+                pane: None,
+                draft: None,
+                state: &state,
+                help: &help,
+                rename_input: &crate::text_input::TextInput::default(),
+            };
+            let backend = ratatui::backend::TestBackend::new(80, 24);
+            let mut terminal = ratatui::Terminal::new(backend).unwrap();
+            terminal
+                .draw(|f| {
+                    draw(f, inputs);
+                })
+                .unwrap();
+            terminal.backend().buffer().clone()
+        };
+
+        let sidebar_focused = render(Focus::Sidebar);
+        let pane_focused = render(Focus::Pane);
+        let p = palette::active();
+        assert_eq!(sidebar_focused[(0, 0)].style().bg, Some(p.sidebar_focus_bg));
+        assert_eq!(pane_focused[(0, 0)].style().bg, Some(p.chrome_bg));
+        assert_eq!(sidebar_focused[(28, 0)].style().bg, Some(p.card.bg));
+        assert_eq!(pane_focused[(28, 0)].style().bg, Some(p.mode_normal_bg));
+        let title: String = (28..80).map(|x| pane_focused[(x, 0)].symbol()).collect();
+        assert!(title.contains("session"), "missing title: {title:?}");
+    }
 }

crates/maestro-tui/src/session_task.rs

@@ -23,6 +23,10 @@ use maestro_protocol::ClientControl;
 use tokio::sync::mpsc;
 use tokio_tungstenite::tungstenite::Message;
 
+/// Match the browser terminal's retained history without letting long-running
+/// sessions grow the client without bound.
+pub const SCROLLBACK_ROWS: usize = 5_000;
+
 /// Input the dispatcher (or the resize tracker) pushes to a session task.
 #[derive(Debug, Clone)]
 pub enum SessionInput {
@@ -103,7 +107,7 @@ impl SessionTask {
     /// up with `SessionInput::Resize` on every frame whose allocation changes.
     pub fn spawn(ws_url: String, rows: u16, cols: u16) -> SessionHandle {
         let (tx, mut rx) = mpsc::channel::<SessionInput>(64);
-        let parser = Arc::new(Mutex::new(vt100::Parser::new(rows, cols, 0)));
+        let parser = Arc::new(Mutex::new(vt100::Parser::new(rows, cols, SCROLLBACK_ROWS)));
         let state = Arc::new(AtomicU8::new(SessionState::Connecting as u8));
 
         let parser_bg = parser.clone();

crates/maestro-tui/src/state.rs

@@ -1,14 +1,18 @@
 //! `AppState` — the top-level mutable state of the running TUI.
 //!
-//! v1 keeps it small on purpose: a list of tabs (each bound to at most one
-//! session), an active tab index, focus split between sidebar and pane, the
-//! current input mode, and an optional overlay (spawn modal, kill confirm,
-//! help, transient toast).
+//! v1 keeps it small on purpose: one pane containing a session or draft form,
+//! focus split between sidebar and pane, the current input mode, and an optional overlay (kill confirm,
+//! help, transient toast). The spawn form is no longer an overlay — an empty
+//! pane is a draft pane (issue #63).
 //!
-//! v1.5 will replace `Tab::pane: Option<SessionId>` with a split tree.
+//! v1.5 will replace `Tab::pane`'s single slot with a split tree.
+
+use std::collections::HashSet;
+use std::path::PathBuf;
 
 use uuid::Uuid;
 
+use crate::draft::DraftPane;
 use crate::keymap::Mode;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -17,16 +21,48 @@ pub enum Focus {
     Pane,
 }
 
+/// One selectable item in the rendered sidebar sequence.
+///
+/// Group paths, unlike a session's position in the catalog, survive catalog
+/// redraws and make a highlighted collapsed group unambiguous.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum SidebarItem {
+    Group(PathBuf),
+    Session(Uuid),
+}
+
+/// What a tab's pane slot holds: a live session, or an inline draft form.
+// The draft variant dwarfs `Session(Uuid)`; the pane is moved rarely enough
+// that boxing every access costs more than the copy does.
+#[allow(clippy::large_enum_variant)]
+#[derive(Debug, Clone, PartialEq)]
+pub enum PaneRef {
+    Session(Uuid),
+    Draft(DraftPane),
+}
+
 #[derive(Debug, Clone)]
 pub struct Tab {
     pub name: String,
-    pub pane: Option<Uuid>,
+    pub pane: Option<PaneRef>,
+}
+
+impl Tab {
+    /// The session this tab shows, if it shows one. Draft panes have none.
+    pub fn session(&self) -> Option<Uuid> {
+        match &self.pane {
+            Some(PaneRef::Session(sid)) => Some(*sid),
+            _ => None,
+        }
+    }
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum OverlayKind {
-    Spawn,
     KillConfirm(Uuid),
+    /// Rename prompt for this session (#125). The edit buffer lives on `App`,
+    /// so this stays comparable.
+    Rename(Uuid),
     Help,
     Toast(String),
 }
@@ -38,8 +74,15 @@ pub struct AppState {
     pub focus: Focus,
     pub mode: Mode,
     pub sidebar_visible: bool,
-    pub sidebar_highlight: Option<Uuid>,
-    pub overlay: Option<OverlayKind>,
+    pub sidebar_highlight: Option<SidebarItem>,
+    /// Group paths whose cards are hidden. This is UI state rather than
+    /// catalog state, so it survives every catalog redraw.
+    pub collapsed_sidebar_groups: HashSet<PathBuf>,
+    /// Private: every transition goes through [`AppState::show_overlay`],
+    /// [`AppState::dismiss_overlay`] or [`AppState::toast`]. Poking the field
+    /// from four call sites is what left a toast on screen with no way to
+    /// clear it.
+    overlay: Option<OverlayKind>,
 }
 
 impl Default for AppState {
@@ -60,10 +103,29 @@ impl AppState {
             mode: Mode::Normal,
             sidebar_visible: true,
             sidebar_highlight: None,
+            collapsed_sidebar_groups: HashSet::new(),
             overlay: None,
         }
     }
 
+    pub fn overlay(&self) -> Option<&OverlayKind> {
+        self.overlay.as_ref()
+    }
+
+    pub fn show_overlay(&mut self, kind: OverlayKind) {
+        self.overlay = Some(kind);
+    }
+
+    /// Clear whatever overlay is up. Returns true if one was showing.
+    pub fn dismiss_overlay(&mut self) -> bool {
+        self.overlay.take().is_some()
+    }
+
+    /// Surface a transient message. Replaces any overlay currently up.
+    pub fn toast(&mut self, message: impl Into<String>) {
+        self.overlay = Some(OverlayKind::Toast(message.into()));
+    }
+
     pub fn active_tab(&self) -> &Tab {
         &self.tabs[self.active_tab_idx]
     }
@@ -72,71 +134,85 @@ impl AppState {
         &mut self.tabs[self.active_tab_idx]
     }
 
-    /// Append a new tab and switch to it. Sidebar regains focus so the user
-    /// can pick something to attach.
-    pub fn new_tab(&mut self) {
-        let name = format!("{}", self.tabs.len() + 1);
-        self.tabs.push(Tab { name, pane: None });
-        self.active_tab_idx = self.tabs.len() - 1;
-        self.focus = Focus::Sidebar;
-    }
-
-    /// Drop the active tab. No-op if it's the only one — there must always
-    /// be at least one tab.
-    pub fn close_tab(&mut self) {
-        if self.tabs.len() <= 1 {
-            return;
-        }
-        self.tabs.remove(self.active_tab_idx);
-        if self.active_tab_idx >= self.tabs.len() {
-            self.active_tab_idx = self.tabs.len() - 1;
-        }
-    }
-
-    pub fn next_tab(&mut self) {
-        if self.tabs.is_empty() {
-            return;
-        }
-        self.active_tab_idx = (self.active_tab_idx + 1) % self.tabs.len();
-    }
-
-    pub fn prev_tab(&mut self) {
-        if self.tabs.is_empty() {
-            return;
-        }
-        self.active_tab_idx = (self.active_tab_idx + self.tabs.len() - 1) % self.tabs.len();
-    }
-
-    pub fn goto_tab(&mut self, n: u8) {
-        let idx = (n as usize)
-            .saturating_sub(1)
-            .min(self.tabs.len().saturating_sub(1));
-        self.active_tab_idx = idx;
-    }
-
     /// Bind a session to the active tab, move focus into the pane, and
     /// drop straight into Insert mode so keystrokes go to the session
     /// without an extra `i` press. The leader returns to Normal.
     pub fn attach_to_focused(&mut self, session_id: Uuid) {
-        self.active_tab_mut().pane = Some(session_id);
+        self.active_tab_mut().pane = Some(PaneRef::Session(session_id));
         self.focus = Focus::Pane;
         self.mode = Mode::Insert;
     }
 
-    /// Move the sidebar highlight by `delta` (positive = down) within the
-    /// given ordered list of selectable session ids. Wraps. No-op on empty.
-    pub fn move_sidebar_highlight(&mut self, order: &[Uuid], delta: i32) {
-        if order.is_empty() {
+    /// Replace the pane with a draft form. Focus lands in the pane, Insert
+    /// mode on, so typing starts immediately, same flow as
+    /// [`Self::attach_to_focused`].
+    pub fn open_draft_pane(&mut self) {
+        self.active_tab_mut().pane = Some(PaneRef::Draft(DraftPane::default()));
+        self.focus = Focus::Pane;
+        self.mode = Mode::Insert;
+    }
+
+    /// A draft submit succeeded: replace whatever the active tab showed with
+    /// the new session in place, matching the web client's behaviour (#57).
+    pub fn complete_spawn(&mut self, sid: Uuid) {
+        self.active_tab_mut().pane = Some(PaneRef::Session(sid));
+        self.focus = Focus::Pane;
+        self.mode = Mode::Insert;
+    }
+
+    /// The session shown by the active tab's pane, if any.
+    pub fn active_session(&self) -> Option<Uuid> {
+        self.active_tab().session()
+    }
+
+    /// Move the sidebar highlight one step through the rendered item
+    /// sequence, in the direction of `delta` (positive = down), landing only
+    /// on items `is_stop` accepts. Only the sign of `delta` matters. Wraps.
+    /// No-op when `order` holds no stop.
+    ///
+    /// Anchoring walks the *full* rendered order, not just the stops, so a
+    /// highlight parked on a skipped row — an expanded group header, which a
+    /// mouse click can still select — steps to its neighbour instead of
+    /// jumping to the far end of the list.
+    pub fn move_sidebar_highlight(
+        &mut self,
+        order: &[SidebarItem],
+        delta: i32,
+        is_stop: impl Fn(&SidebarItem) -> bool,
+    ) {
+        if order.is_empty() || delta == 0 {
             return;
         }
         let len = order.len() as i32;
+        let step = delta.signum();
         let cur = self
             .sidebar_highlight
-            .and_then(|id| order.iter().position(|x| *x == id))
+            .as_ref()
+            .and_then(|id| order.iter().position(|x| x == id))
             .map(|i| i as i32)
-            .unwrap_or(-1);
-        let next = (cur + delta).rem_euclid(len) as usize;
-        self.sidebar_highlight = Some(order[next]);
+            // Nothing highlighted: start one off the end we walk from, so the
+            // first step lands on the first (or last) item.
+            .unwrap_or(if step > 0 { -1 } else { 0 });
+        let mut idx = cur;
+        for _ in 0..len {
+            idx = (idx + step).rem_euclid(len);
+            if is_stop(&order[idx as usize]) {
+                self.sidebar_highlight = Some(order[idx as usize].clone());
+                return;
+            }
+        }
+    }
+
+    /// Toggle a group. When collapsing a group containing the current card,
+    /// leave the highlight on the group row that remains visible.
+    pub fn toggle_sidebar_group(&mut self, key: PathBuf, contains_highlight: bool) {
+        if self.collapsed_sidebar_groups.remove(&key) {
+            return;
+        }
+        self.collapsed_sidebar_groups.insert(key.clone());
+        if contains_highlight {
+            self.sidebar_highlight = Some(SidebarItem::Group(key));
+        }
     }
 
     /// Toggle sidebar visibility.
@@ -163,103 +239,125 @@ mod tests {
         assert!(state.overlay.is_none());
     }
 
-    #[test]
-    fn new_tab_extends_and_focuses() {
-        let mut state = AppState::new();
-        state.new_tab();
-        assert_eq!(state.tabs.len(), 2);
-        assert_eq!(state.active_tab_idx, 1);
-        assert_eq!(state.focus, Focus::Sidebar);
-    }
-
-    #[test]
-    fn close_tab_keeps_at_least_one() {
-        let mut state = AppState::new();
-        state.close_tab();
-        assert_eq!(state.tabs.len(), 1);
-        state.new_tab();
-        state.close_tab();
-        assert_eq!(state.tabs.len(), 1);
-    }
-
-    #[test]
-    fn close_tab_advances_when_last_is_closed() {
-        let mut state = AppState::new();
-        state.new_tab();
-        state.new_tab();
-        assert_eq!(state.active_tab_idx, 2);
-        state.close_tab();
-        assert_eq!(state.tabs.len(), 2);
-        assert_eq!(state.active_tab_idx, 1);
-    }
-
-    #[test]
-    fn next_prev_tab_wraps() {
-        let mut state = AppState::new();
-        state.new_tab();
-        state.new_tab();
-        state.active_tab_idx = 0;
-        state.next_tab();
-        assert_eq!(state.active_tab_idx, 1);
-        state.next_tab();
-        assert_eq!(state.active_tab_idx, 2);
-        state.next_tab();
-        assert_eq!(state.active_tab_idx, 0);
-        state.prev_tab();
-        assert_eq!(state.active_tab_idx, 2);
-    }
-
-    #[test]
-    fn goto_tab_uses_one_based_clamp() {
-        let mut state = AppState::new();
-        state.new_tab();
-        state.new_tab();
-        state.goto_tab(1);
-        assert_eq!(state.active_tab_idx, 0);
-        state.goto_tab(2);
-        assert_eq!(state.active_tab_idx, 1);
-        state.goto_tab(99);
-        // Clamped to last available tab.
-        assert_eq!(state.active_tab_idx, state.tabs.len() - 1);
-    }
-
     #[test]
     fn move_sidebar_highlight_walks_order_and_wraps() {
         let mut state = AppState::new();
         let a = Uuid::from_u128(1);
         let b = Uuid::from_u128(2);
         let c = Uuid::from_u128(3);
-        let order = vec![a, b, c];
+        let order = vec![
+            SidebarItem::Session(a),
+            SidebarItem::Group("repo".into()),
+            SidebarItem::Session(b),
+            SidebarItem::Session(c),
+        ];
 
         // No prior highlight + delta +1 lands on first item.
-        state.move_sidebar_highlight(&order, 1);
-        assert_eq!(state.sidebar_highlight, Some(a));
+        state.move_sidebar_highlight(&order, 1, |_| true);
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(a)));
 
-        state.move_sidebar_highlight(&order, 1);
-        assert_eq!(state.sidebar_highlight, Some(b));
-        state.move_sidebar_highlight(&order, 1);
-        assert_eq!(state.sidebar_highlight, Some(c));
+        state.move_sidebar_highlight(&order, 1, |_| true);
+        assert_eq!(
+            state.sidebar_highlight,
+            Some(SidebarItem::Group("repo".into()))
+        );
+        state.move_sidebar_highlight(&order, 1, |_| true);
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(b)));
+        state.move_sidebar_highlight(&order, 1, |_| true);
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(c)));
         // Wraps forward.
-        state.move_sidebar_highlight(&order, 1);
-        assert_eq!(state.sidebar_highlight, Some(a));
+        state.move_sidebar_highlight(&order, 1, |_| true);
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(a)));
         // Wraps backward.
-        state.move_sidebar_highlight(&order, -1);
-        assert_eq!(state.sidebar_highlight, Some(c));
+        state.move_sidebar_highlight(&order, -1, |_| true);
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(c)));
+    }
+
+    #[test]
+    fn move_sidebar_highlight_skips_rows_the_filter_rejects() {
+        let mut state = AppState::new();
+        let a = Uuid::from_u128(1);
+        let b = Uuid::from_u128(2);
+        let order = vec![
+            SidebarItem::Group("repo".into()),
+            SidebarItem::Session(a),
+            SidebarItem::Group("other".into()),
+            SidebarItem::Session(b),
+        ];
+        let sessions_only = |item: &SidebarItem| matches!(item, SidebarItem::Session(_));
+
+        state.move_sidebar_highlight(&order, 1, sessions_only);
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(a)));
+        state.move_sidebar_highlight(&order, 1, sessions_only);
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(b)));
+        state.move_sidebar_highlight(&order, -1, sessions_only);
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(a)));
+
+        // Backwards from nothing lands on the last stop, not the last row.
+        state.sidebar_highlight = None;
+        state.move_sidebar_highlight(&order, -1, sessions_only);
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(b)));
+    }
+
+    /// A highlight sitting on a skipped row still moves to its neighbour.
+    #[test]
+    fn move_sidebar_highlight_anchors_on_a_skipped_row() {
+        let mut state = AppState::new();
+        let a = Uuid::from_u128(1);
+        let b = Uuid::from_u128(2);
+        let order = vec![
+            SidebarItem::Session(a),
+            SidebarItem::Group("repo".into()),
+            SidebarItem::Session(b),
+        ];
+        let sessions_only = |item: &SidebarItem| matches!(item, SidebarItem::Session(_));
+
+        state.sidebar_highlight = Some(SidebarItem::Group("repo".into()));
+        state.move_sidebar_highlight(&order, 1, sessions_only);
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(b)));
+
+        state.sidebar_highlight = Some(SidebarItem::Group("repo".into()));
+        state.move_sidebar_highlight(&order, -1, sessions_only);
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Session(a)));
+    }
+
+    #[test]
+    fn move_sidebar_highlight_is_noop_when_nothing_is_a_stop() {
+        let mut state = AppState::new();
+        let order = vec![SidebarItem::Group("repo".into())];
+        state.move_sidebar_highlight(&order, 1, |_| false);
+        assert_eq!(state.sidebar_highlight, None);
     }
 
     #[test]
     fn move_sidebar_highlight_is_noop_on_empty_order() {
         let mut state = AppState::new();
-        state.move_sidebar_highlight(&[], 1);
+        state.move_sidebar_highlight(&[], 1, |_| true);
         assert_eq!(state.sidebar_highlight, None);
     }
 
+    #[test]
+    fn collapsing_highlighted_group_moves_a_card_highlight_to_the_group() {
+        let key = PathBuf::from("/repo");
+        let mut state = AppState::new();
+        state.sidebar_highlight = Some(SidebarItem::Session(Uuid::from_u128(9)));
+        state.toggle_sidebar_group(key.clone(), true);
+        assert_eq!(
+            state.sidebar_highlight,
+            Some(SidebarItem::Group(key.clone()))
+        );
+        assert!(state.collapsed_sidebar_groups.contains(&key));
+        state.toggle_sidebar_group(key.clone(), false);
+        assert!(!state.collapsed_sidebar_groups.contains(&key));
+        assert_eq!(state.sidebar_highlight, Some(SidebarItem::Group(key)));
+    }
+
     #[test]
     fn attach_binds_focuses_pane_and_enters_insert_mode() {
         let mut state = AppState::new();
         let sid = Uuid::from_u128(7);
         state.attach_to_focused(sid);
-        assert_eq!(state.tabs[0].pane, Some(sid));
+        assert_eq!(state.tabs[0].session(), Some(sid));
         assert_eq!(state.focus, Focus::Pane);
         // The user expects to type into the session right away; the leader
         // (default ctrl-a) is the way back.
@@ -277,4 +375,47 @@ mod tests {
         // Doesn't force focus back; sidebar shown but focus stays where it was.
         assert_eq!(state.focus, Focus::Pane);
     }
+
+    #[test]
+    fn dismiss_overlay_reports_whether_one_was_showing() {
+        let mut state = AppState::new();
+        assert!(!state.dismiss_overlay());
+        state.toast("boom");
+        assert!(state.dismiss_overlay());
+        assert!(state.overlay().is_none());
+    }
+
+    /// Issue #63: `s` over an empty pane turns that pane into a draft —
+    /// focused, Insert mode on, typing starts immediately.
+    #[test]
+    fn open_draft_reuses_the_empty_active_pane() {
+        let mut state = AppState::new();
+        state.open_draft_pane();
+        assert!(matches!(state.active_tab().pane, Some(PaneRef::Draft(_))));
+        assert_eq!(state.focus, Focus::Pane);
+        assert_eq!(state.mode, Mode::Insert);
+        assert_eq!(state.tabs.len(), 1);
+    }
+
+    #[test]
+    fn open_draft_over_a_session_reuses_the_pane() {
+        let mut state = AppState::new();
+        state.attach_to_focused(Uuid::from_u128(9));
+        state.open_draft_pane();
+        assert_eq!(state.tabs.len(), 1);
+        assert_eq!(state.active_tab_idx, 0);
+        assert!(matches!(state.active_tab().pane, Some(PaneRef::Draft(_))));
+    }
+
+    /// Web parity (#57): submitting fills the pane in place.
+    #[test]
+    fn complete_spawn_replaces_the_draft_with_the_session() {
+        let mut state = AppState::new();
+        state.open_draft_pane();
+        let sid = Uuid::from_u128(21);
+        state.complete_spawn(sid);
+        assert_eq!(state.active_tab().session(), Some(sid));
+        assert_eq!(state.focus, Focus::Pane);
+        assert_eq!(state.mode, Mode::Insert);
+    }
 }

crates/maestro-tui/src/tabs.rs

@@ -1,61 +0,0 @@
-//! Tab-bar widget — top row of the main area.
-
-use ratatui::layout::Rect;
-use ratatui::style::{Modifier, Style};
-use ratatui::text::Line;
-use ratatui::widgets::Tabs;
-use ratatui::Frame;
-
-#[derive(Debug, Clone)]
-pub struct TabBar {
-    pub tab_names: Vec<String>,
-    pub active_idx: usize,
-}
-
-impl TabBar {
-    pub fn render(&self, f: &mut Frame, area: Rect) {
-        let titles: Vec<Line> = self
-            .tab_names
-            .iter()
-            .map(|n| Line::from(n.as_str()))
-            .collect();
-        let tabs = Tabs::new(titles)
-            .select(self.active_idx)
-            .highlight_style(Style::default().add_modifier(Modifier::REVERSED));
-        f.render_widget(tabs, area);
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use ratatui::backend::TestBackend;
-    use ratatui::Terminal;
-
-    fn render_to_string(bar: &TabBar, w: u16, h: u16) -> String {
-        let backend = TestBackend::new(w, h);
-        let mut terminal = Terminal::new(backend).unwrap();
-        terminal.draw(|f| bar.render(f, f.area())).unwrap();
-        let buf = terminal.backend().buffer().clone();
-        let mut out = String::new();
-        for y in 0..buf.area.height {
-            for x in 0..buf.area.width {
-                out.push_str(buf[(x, y)].symbol());
-            }
-            out.push('\n');
-        }
-        out
-    }
-
-    #[test]
-    fn renders_three_tab_names() {
-        let bar = TabBar {
-            tab_names: vec!["1".into(), "2".into(), "3".into()],
-            active_idx: 1,
-        };
-        let rendered = render_to_string(&bar, 40, 1);
-        assert!(rendered.contains("1"));
-        assert!(rendered.contains("2"));
-        assert!(rendered.contains("3"));
-    }
-}

crates/maestro-tui/src/terminal.rs

@@ -5,7 +5,9 @@
 
 use std::io;
 
-use crossterm::event::{DisableMouseCapture, EnableMouseCapture};
+use crossterm::event::{
+    DisableBracketedPaste, DisableMouseCapture, EnableBracketedPaste, EnableMouseCapture,
+};
 use crossterm::execute;
 use crossterm::terminal::{
     disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
@@ -26,7 +28,12 @@ impl TerminalGuard {
     pub fn enter() -> Result<Self, TerminalError> {
         enable_raw_mode()?;
         let mut out = io::stdout();
-        execute!(out, EnterAlternateScreen, EnableMouseCapture)?;
+        execute!(
+            out,
+            EnterAlternateScreen,
+            EnableMouseCapture,
+            EnableBracketedPaste
+        )?;
         Ok(TerminalGuard)
     }
 
@@ -34,7 +41,12 @@ impl TerminalGuard {
     /// call it without producing weird errors.
     fn restore() {
         let mut out = io::stdout();
-        let _ = execute!(out, DisableMouseCapture, LeaveAlternateScreen);
+        let _ = execute!(
+            out,
+            DisableBracketedPaste,
+            DisableMouseCapture,
+            LeaveAlternateScreen
+        );
         let _ = disable_raw_mode();
     }
 }

crates/maestro-tui/src/text_input.rs

@@ -0,0 +1,462 @@
+//! Single-line text-input primitive shared by every TUI form field.
+//!
+//! Owns a `String`, a character-indexed cursor, and horizontal scroll state.
+//! All editing goes through [`TextInput::handle_key`] so callers feed the same
+//! canonical [`InputKey`] stream the rest of the app uses; bracketed paste
+//! arrives as one [`InputKey::Paste`] and is inserted as a single operation.
+//!
+//! This is the one piece of the TUI form layer that unit-tests without a
+//! terminal: drive it with `InputKey` sequences and inspect value/cursor.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::style::Style;
+
+use crate::input::InputKey;
+
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
+pub struct TextInput {
+    value: String,
+    /// Cursor position as a char offset into `value`.
+    cursor: usize,
+    /// Char offset of the leftmost visible cell. A `Cell` so `render` can
+    /// re-clamp it without `&mut self` — widgets are drawn through shared
+    /// references in this codebase.
+    scroll: std::cell::Cell<usize>,
+}
+
+impl TextInput {
+    pub fn with_value(value: impl Into<String>) -> Self {
+        let mut input = Self {
+            value: value.into(),
+            ..Self::default()
+        };
+        input.cursor = input.value.chars().count();
+        input
+    }
+
+    pub fn value(&self) -> &str {
+        &self.value
+    }
+
+    pub fn cursor(&self) -> usize {
+        self.cursor
+    }
+
+    /// Char offset of the leftmost visible cell; only meaningful after
+    /// [`TextInput::render`] has clamped it to the field width.
+    pub fn scroll_offset(&self) -> usize {
+        self.scroll.get()
+    }
+
+    /// Insert `text` at the cursor as one operation. Used both for typed
+    /// characters and for whole bracketed-paste payloads.
+    pub fn insert(&mut self, text: &str) {
+        let at = self.byte_offset(self.cursor);
+        self.value.insert_str(at, text);
+        self.cursor += text.chars().count();
+    }
+
+    pub fn handle_key(&mut self, key: &InputKey) {
+        match key {
+            InputKey::Char {
+                c,
+                ctrl: false,
+                alt: false,
+                ..
+            } => self.insert(&c.to_string()),
+            InputKey::Char {
+                c: 'w', ctrl: true, ..
+            } => self.delete_word_backwards(),
+            InputKey::Char {
+                c: 'k', ctrl: true, ..
+            } => self.kill_to_end(),
+            // Emacs-style word motion; ctrl-arrow reaches us as a plain
+            // Left/Right today, so these are the dependable binding.
+            InputKey::Char {
+                c: 'b', ctrl: true, ..
+            } => self.cursor = self.word_left(),
+            InputKey::Char {
+                c: 'f', ctrl: true, ..
+            } => self.cursor = self.word_right(),
+            InputKey::Left => {
+                self.cursor = self.cursor.saturating_sub(1);
+            }
+            InputKey::Right => {
+                if self.cursor < self.value.chars().count() {
+                    self.cursor += 1;
+                }
+            }
+            InputKey::Home => self.cursor = 0,
+            InputKey::End => self.cursor = self.value.chars().count(),
+            InputKey::Backspace => {
+                if self.cursor > 0 {
+                    let at = self.byte_offset(self.cursor - 1);
+                    let end = self.byte_offset(self.cursor);
+                    self.value.replace_range(at..end, "");
+                    self.cursor -= 1;
+                }
+            }
+            InputKey::Delete => {
+                if self.cursor < self.value.chars().count() {
+                    let at = self.byte_offset(self.cursor);
+                    let end = self.byte_offset(self.cursor + 1);
+                    self.value.replace_range(at..end, "");
+                }
+            }
+            InputKey::Paste(text) => self.insert(text),
+            _ => {}
+        }
+    }
+
+    /// Draw into `area` (expected one row tall), scrolling horizontally so the
+    /// cursor stays visible, and return the screen column where the caller
+    /// should place the terminal cursor.
+    pub fn render(&self, area: Rect, buf: &mut Buffer, style: Style) -> u16 {
+        let width = area.width as usize;
+        let len = self.value.chars().count();
+        let scroll = self.scroll.get().min(len);
+        let scroll = if self.cursor < scroll {
+            self.cursor
+        } else if width > 0 && self.cursor.saturating_sub(scroll) >= width {
+            self.cursor + 1 - width
+        } else {
+            scroll
+        };
+        self.scroll.set(scroll);
+        for (col, c) in self.value.chars().skip(scroll).take(width).enumerate() {
+            buf[(area.x + col as u16, area.y)]
+                .set_symbol(&c.to_string())
+                .set_style(style);
+        }
+        area.x + self.cursor.saturating_sub(scroll) as u16
+    }
+
+    fn byte_offset(&self, char_index: usize) -> usize {
+        self.value
+            .char_indices()
+            .nth(char_index)
+            .map(|(b, _)| b)
+            .unwrap_or(self.value.len())
+    }
+
+    fn is_word_char(c: char) -> bool {
+        c.is_alphanumeric() || c == '_'
+    }
+
+    /// Start of the word before the cursor, skipping any separators first —
+    /// emacs `backward-word`.
+    fn word_left(&self) -> usize {
+        let chars: Vec<char> = self.value.chars().collect();
+        let mut i = self.cursor;
+        while i > 0 && !Self::is_word_char(chars[i - 1]) {
+            i -= 1;
+        }
+        while i > 0 && Self::is_word_char(chars[i - 1]) {
+            i -= 1;
+        }
+        i
+    }
+
+    /// Start of the word after the cursor, skipping the rest of the current
+    /// word first — emacs `forward-word`.
+    fn word_right(&self) -> usize {
+        let chars: Vec<char> = self.value.chars().collect();
+        let len = chars.len();
+        let mut i = self.cursor;
+        while i < len && !Self::is_word_char(chars[i]) {
+            i += 1;
+        }
+        while i < len && Self::is_word_char(chars[i]) {
+            i += 1;
+        }
+        i
+    }
+
+    fn kill_to_end(&mut self) {
+        let at = self.byte_offset(self.cursor);
+        self.value.truncate(at);
+    }
+
+    /// Shell-style ctrl-w: kill back to the previous whitespace, taking any
+    /// trailing whitespace run with it — so `cd /tmp/foo` loses the whole
+    /// path segment in one keystroke.
+    fn delete_word_backwards(&mut self) {
+        let chars: Vec<char> = self.value.chars().collect();
+        let mut i = self.cursor;
+        while i > 0 && chars[i - 1].is_whitespace() {
+            i -= 1;
+        }
+        while i > 0 && !chars[i - 1].is_whitespace() {
+            i -= 1;
+        }
+        let at = self.byte_offset(i);
+        let end = self.byte_offset(self.cursor);
+        self.value.replace_range(at..end, "");
+        self.cursor = i;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use InputKey::{Backspace, Delete, End, Home, Left, Right};
+
+    fn typed(s: &str) -> Vec<InputKey> {
+        s.chars().map(InputKey::char).collect()
+    }
+
+    fn fed(keys: &[InputKey]) -> TextInput {
+        let mut input = TextInput::default();
+        for k in keys {
+            input.handle_key(k);
+        }
+        input
+    }
+
+    fn ctrl(c: char) -> InputKey {
+        InputKey::ctrl_char(c)
+    }
+
+    #[test]
+    fn typing_lands_in_order() {
+        let input = fed(&typed("hello"));
+        assert_eq!(input.value(), "hello");
+        assert_eq!(input.cursor(), 5);
+    }
+
+    #[test]
+    fn backspace_removes_the_last_typed_char() {
+        let mut input = fed(&typed("hello"));
+        input.handle_key(&Backspace);
+        assert_eq!(input.value(), "hell");
+        assert_eq!(input.cursor(), 4);
+    }
+
+    #[test]
+    fn left_then_insert_fixes_a_middle_typo() {
+        let mut input = fed(&typed("helo"));
+        input.handle_key(&Left);
+        input.handle_key(&Left);
+        input.handle_key(&InputKey::char('l'));
+        assert_eq!(input.value(), "hello");
+        assert_eq!(input.cursor(), 3);
+    }
+
+    #[test]
+    fn motion_keys_stop_at_the_edges() {
+        let mut input = fed(&typed("abc"));
+        for _ in 0..5 {
+            input.handle_key(&Left);
+        }
+        assert_eq!(input.cursor(), 0);
+        input.handle_key(&Left);
+        assert_eq!(input.cursor(), 0);
+        for _ in 0..5 {
+            input.handle_key(&Right);
+        }
+        assert_eq!(input.cursor(), 3);
+    }
+
+    #[test]
+    fn home_and_end_jump_to_the_ends() {
+        let mut input = fed(&typed("abcdef"));
+        input.handle_key(&Home);
+        assert_eq!(input.cursor(), 0);
+        input.handle_key(&InputKey::char('x'));
+        assert_eq!(input.value(), "xabcdef");
+        input.handle_key(&End);
+        input.handle_key(&InputKey::char('!'));
+        assert_eq!(input.value(), "xabcdef!");
+    }
+
+    /// Cursor starts after the final `/`; word-left lands on word starts,
+    /// never inside a separator run.
+    #[test]
+    fn ctrl_b_walks_left_one_word_at_a_time() {
+        let mut input = TextInput::with_value("/tmp/foo bar-baz/");
+        assert_eq!(input.cursor(), 17);
+        for expected in [13, 9, 5, 1, 0, 0] {
+            input.handle_key(&ctrl('b'));
+            assert_eq!(input.cursor(), expected);
+        }
+    }
+
+    #[test]
+    fn ctrl_f_walks_right_one_word_at_a_time() {
+        let mut input = TextInput::with_value("/tmp/foo bar");
+        input.handle_key(&Home);
+        for expected in [4, 8, 12, 12] {
+            input.handle_key(&ctrl('f'));
+            assert_eq!(input.cursor(), expected);
+        }
+    }
+
+    #[test]
+    fn backspace_deletes_before_the_cursor() {
+        let mut input = fed(&typed("abcdef"));
+        input.handle_key(&Left);
+        input.handle_key(&Left);
+        input.handle_key(&Left);
+        input.handle_key(&Backspace);
+        assert_eq!(input.value(), "abdef");
+        assert_eq!(input.cursor(), 2);
+    }
+
+    #[test]
+    fn backspace_on_empty_input_is_a_noop() {
+        let mut input = TextInput::default();
+        input.handle_key(&Backspace);
+        assert_eq!(input.value(), "");
+        assert_eq!(input.cursor(), 0);
+    }
+
+    #[test]
+    fn delete_removes_the_char_under_the_cursor() {
+        let mut input = fed(&typed("abcdef"));
+        input.handle_key(&Home);
+        input.handle_key(&Delete);
+        assert_eq!(input.value(), "bcdef");
+        assert_eq!(input.cursor(), 0);
+    }
+
+    #[test]
+    fn delete_past_the_end_is_a_noop() {
+        let mut input = TextInput::with_value("abc");
+        input.handle_key(&End);
+        input.handle_key(&Delete);
+        assert_eq!(input.value(), "abc");
+    }
+
+    /// `cd /tmp/foo` with ctrl-w leaves `cd ` — the whole path segment is one
+    /// word to a shell (readline kills back to whitespace, spaces included).
+    #[test]
+    fn ctrl_w_deletes_the_word_behind_the_cursor() {
+        let mut input = fed(&[typed("cd ").as_slice(), typed("/tmp/foo").as_slice()].concat());
+        input.handle_key(&ctrl('w'));
+        assert_eq!(input.value(), "cd ");
+        assert_eq!(input.cursor(), 3);
+    }
+
+    #[test]
+    fn ctrl_w_stops_before_the_separator_run() {
+        let mut input = TextInput::with_value("a   b");
+        input.cursor = 5;
+        input.handle_key(&ctrl('w'));
+        assert_eq!(input.value(), "a   ");
+        assert_eq!(input.cursor(), 4);
+    }
+
+    #[test]
+    fn ctrl_k_kills_everything_after_the_cursor() {
+        let mut input = fed(&typed("spawn --debug extra"));
+        for _ in 0..14 {
+            input.handle_key(&Left);
+        }
+        input.handle_key(&ctrl('k'));
+        assert_eq!(input.value(), "spawn");
+        assert_eq!(input.cursor(), 5);
+    }
+
+    /// A paste arrives as one event carrying the whole payload and must land
+    /// at the cursor as a single insertion, not per-character.
+    #[test]
+    fn paste_inserts_whole_payload_at_the_cursor() {
+        let mut input = fed(&typed("cd "));
+        input.handle_key(&InputKey::Paste("/srv/work".into()));
+        assert_eq!(input.value(), "cd /srv/work");
+        assert_eq!(input.cursor(), 12);
+        // What follows still behaves like ordinary typed text.
+        input.handle_key(&InputKey::char('/'));
+        assert_eq!(input.value(), "cd /srv/work/");
+    }
+
+    #[test]
+    fn paste_between_existing_text_keeps_both_halves() {
+        let mut input = TextInput::with_value("ac");
+        input.handle_key(&Left);
+        input.handle_key(&InputKey::Paste("b×".into()));
+        assert_eq!(input.value(), "ab×c");
+        assert_eq!(input.cursor(), 3, "cursor counts chars, not bytes");
+    }
+
+    #[test]
+    fn rendering_an_empty_field_points_at_its_first_column() {
+        let input = TextInput::default();
+        let area = Rect::new(10, 5, 20, 1);
+        let mut buf = Buffer::empty(area);
+        let col = input.render(area, &mut buf, Style::default());
+        assert_eq!(col, 10);
+    }
+
+    #[test]
+    fn rendering_reports_the_visible_cursor_column() {
+        let mut input = TextInput::with_value("hello");
+        input.handle_key(&Left);
+        input.handle_key(&Left);
+        let area = Rect::new(10, 5, 20, 1);
+        let mut buf = Buffer::empty(area);
+        let col = input.render(area, &mut buf, Style::default());
+        assert_eq!(col, 13);
+        for (i, expected) in ["h", "e", "l", "l", "o"].iter().enumerate() {
+            assert_eq!(buf[(10 + i as u16, 5)].symbol(), *expected);
+        }
+    }
+
+    #[test]
+    fn rendering_a_value_wider_than_the_field_shows_its_tail() {
+        let value = "0123456789abcdefghij";
+        let input = TextInput::with_value(value);
+        let area = Rect::new(0, 0, 10, 1);
+        let mut buf = Buffer::empty(area);
+        let col = input.render(area, &mut buf, Style::default());
+        assert_eq!(col, 9, "cursor sits on the last visible column");
+        for (i, expected) in value.chars().skip(input.scroll_offset()).enumerate() {
+            assert_eq!(
+                buf[(i as u16, 0)].symbol(),
+                expected.to_string(),
+                "cell {i}"
+            );
+        }
+    }
+
+    /// Moving left into the hidden region must scroll the window back so the
+    /// cursor never disappears off the left edge.
+    #[test]
+    fn moving_left_into_the_hidden_region_scrolls_back() {
+        let value = "0123456789abcdefghij";
+        let mut input = TextInput::with_value(value);
+        let area = Rect::new(0, 0, 10, 1);
+        let mut buf = Buffer::empty(area);
+        input.render(area, &mut buf, Style::default());
+        assert_eq!(input.cursor(), 20);
+
+        input.handle_key(&Home);
+        for _ in 0..5 {
+            input.handle_key(&Right);
+        }
+        let mut buf = Buffer::empty(area);
+        let col = input.render(area, &mut buf, Style::default());
+        assert_eq!(input.cursor(), 5);
+        assert_eq!(
+            input.value().chars().nth(input.scroll_offset()),
+            Some('5'),
+            "window scrolled back to the cursor"
+        );
+        assert_eq!(col, 0);
+        assert_eq!(buf[(0, 0)].symbol(), "5");
+    }
+
+    #[test]
+    fn shrinking_the_value_clamps_scroll_and_cursor() {
+        let mut input = TextInput::with_value("0123456789abcdefghij");
+        input.handle_key(&Home);
+        input.handle_key(&ctrl('k'));
+        let area = Rect::new(0, 0, 10, 1);
+        let mut buf = Buffer::empty(area);
+        let col = input.render(area, &mut buf, Style::default());
+        assert_eq!(input.value(), "");
+        assert_eq!(col, 0);
+    }
+}

crates/maestro-tui/tests/catalog_ws.rs

@@ -1,84 +1,42 @@
-//! WS round-trip test for `CatalogStore::run_events_loop`. Spins a tiny axum
-//! server that emulates the daemon's `/api/events` contract: send a `Snapshot`
-//! on connect, then a delta.
+//! `CatalogStore::run_events_loop` against a daemon serving the real
+//! `/api/events` contract, rather than a scripted socket.
 
 use std::time::Duration;
 
-use axum::extract::ws::{Message, WebSocketUpgrade};
-use axum::response::Response;
-use axum::routing::any;
-use axum::Router;
-use chrono::Utc;
-use maestro_protocol::{CatalogEvent, Session, SessionStatus};
+use maestro_testing::{session, MockDaemon};
 use maestro_tui::catalog::CatalogStore;
 use uuid::Uuid;
 
-fn session(id: u128) -> Session {
-    Session {
-        id: Uuid::from_u128(id),
-        command: "bash".into(),
-        cwd: std::path::PathBuf::from("/tmp"),
-        env: Default::default(),
-        metadata: Default::default(),
-        status: SessionStatus::Running,
-        created_at: Utc::now(),
-        foreground: None,
-        activity: Default::default(),
-        last_activity_at: chrono::Utc::now(),
-
-        current_cwd: None,
-    }
-}
-
-async fn events_handler(ws: WebSocketUpgrade) -> Response {
-    ws.on_upgrade(|mut socket| async move {
-        let snapshot = CatalogEvent::Snapshot { sessions: vec![] };
-        let text = serde_json::to_string(&snapshot).unwrap();
-        if socket.send(Message::Text(text)).await.is_err() {
-            return;
-        }
-        // Small delay so the client has the snapshot applied before the delta.
-        tokio::time::sleep(Duration::from_millis(50)).await;
-        let added = CatalogEvent::SessionAdded {
-            session: session(1),
-        };
-        let text = serde_json::to_string(&added).unwrap();
-        let _ = socket.send(Message::Text(text)).await;
-        // Keep the connection alive so the client doesn't enter reconnect.
-        tokio::time::sleep(Duration::from_secs(2)).await;
-    })
-}
-
 #[tokio::test(flavor = "multi_thread")]
-async fn run_events_loop_applies_snapshot_then_delta() {
-    let app = Router::new().route("/api/events", any(events_handler));
-    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
-    let addr = listener.local_addr().unwrap();
-    tokio::spawn(async move {
-        axum::serve(listener, app).await.unwrap();
-    });
+async fn applies_the_snapshot_then_live_deltas() {
+    let mock = MockDaemon::start().await;
+    mock.add_session(session(Uuid::from_u128(1), "/home/mock", "bash"));
 
+    let ws_url = mock.client().events_url().expect("events url");
     let store = CatalogStore::default();
     let bg = store.clone();
-    let ws_url = format!("ws://{addr}/api/events");
     tokio::spawn(async move { bg.run_events_loop(ws_url).await });
 
-    // Bootstrap should land within ~250 ms.
-    tokio::time::timeout(
-        Duration::from_millis(500),
-        store.wait_for_initial_snapshot(),
-    )
-    .await
-    .expect("initial snapshot never arrived");
+    tokio::time::timeout(Duration::from_secs(3), store.wait_for_initial_snapshot())
+        .await
+        .expect("initial snapshot");
+    assert_eq!(store.snapshot().sessions.len(), 1);
 
-    assert!(store.snapshot().sessions.is_empty());
+    mock.add_session(session(Uuid::from_u128(2), "/home/mock", "claude"));
+    wait_until(|| store.snapshot().sessions.len() == 2).await;
 
-    // Delta arrives shortly after. Poll for up to 500 ms.
-    for _ in 0..50 {
-        if store.snapshot().sessions.len() == 1 {
+    mock.remove_session(Uuid::from_u128(1));
+    wait_until(|| store.snapshot().sessions.len() == 1).await;
+    assert_eq!(store.snapshot().sessions[0].id, Uuid::from_u128(2));
+}
+
+async fn wait_until(mut cond: impl FnMut() -> bool) {
+    let deadline = tokio::time::Instant::now() + Duration::from_secs(3);
+    while tokio::time::Instant::now() < deadline {
+        if cond() {
             return;
         }
         tokio::time::sleep(Duration::from_millis(10)).await;
     }
-    panic!("delta never propagated; got {:?}", store.snapshot());
+    panic!("timed out waiting for the catalog to converge");
 }

crates/maestro-web/Cargo.toml

@@ -22,6 +22,7 @@ dirs.workspace = true
 futures-util.workspace = true
 include_dir.workspace = true
 maestro-config.workspace = true
+maestro-protocol.workspace = true
 mime_guess.workspace = true
 reqwest.workspace = true
 serde_json.workspace = true
@@ -32,6 +33,8 @@ tracing.workspace = true
 tracing-subscriber.workspace = true
 
 [dev-dependencies]
+maestro-testing.workspace = true
+uuid.workspace = true
 reqwest.workspace = true
 serde_json.workspace = true
 tempfile.workspace = true

crates/maestro-web/README.md

@@ -31,7 +31,6 @@ The binary reads `~/.config/maestro/config.toml`. The `[web]` section:
 [web]
 bind_addr        = "127.0.0.1:8080"      # default
 daemon_url       = "http://127.0.0.1:7070"  # default
-# dev_proxy_target = "http://127.0.0.1:5173"  # only when developing the frontend
 ```
 
 Env-var overrides (all optional):

crates/maestro-web/src/config.rs

@@ -5,7 +5,9 @@ use std::path::{Path, PathBuf};
 
 use maestro_config::MaestroConfigFile;
 
-pub use maestro_config::{default_config_path, resolve_config_path, WebSection, CONFIG_PATH_ENV};
+pub use maestro_config::default_config_path;
+
+use maestro_config::WebSection;
 
 /// Default bind address when neither env nor file specify one.
 pub const DEFAULT_BIND_ADDR: &str = "127.0.0.1:8080";
@@ -14,7 +16,6 @@ pub const DEFAULT_DAEMON_URL: &str = "http://127.0.0.1:7070";
 
 pub const ENV_WEB_BIND_ADDR: &str = "MAESTRO_WEB_BIND_ADDR";
 pub const ENV_WEB_DAEMON_URL: &str = "MAESTRO_WEB_DAEMON_URL";
-pub const ENV_WEB_DEV_PROXY_TARGET: &str = "MAESTRO_WEB_DEV_PROXY_TARGET";
 
 fn default_bind_addr() -> SocketAddr {
     DEFAULT_BIND_ADDR.parse().expect("valid default bind_addr")
@@ -33,17 +34,12 @@ pub struct WebConfig {
     /// Daemon HTTP base URL — e.g. `http://127.0.0.1:7070`. Always a base
     /// without trailing slash and without a path.
     pub daemon_url: String,
-    /// Optional dev override: when set, `/` (and only `/`) is proxied here
-    /// instead of being served from the embedded bundle. Set to the Vite dev
-    /// server URL during frontend development.
-    pub dev_proxy_target: Option<String>,
 }
 
 #[derive(Debug, Clone, Default)]
 pub struct EnvOverrides {
     pub bind_addr: Option<String>,
     pub daemon_url: Option<String>,
-    pub dev_proxy_target: Option<String>,
 }
 
 impl EnvOverrides {
@@ -51,7 +47,6 @@ impl EnvOverrides {
         Self {
             bind_addr: std::env::var(ENV_WEB_BIND_ADDR).ok(),
             daemon_url: std::env::var(ENV_WEB_DAEMON_URL).ok(),
-            dev_proxy_target: std::env::var(ENV_WEB_DEV_PROXY_TARGET).ok(),
         }
     }
 }
@@ -76,15 +71,9 @@ fn resolve_with(web: WebSection, env: EnvOverrides) -> Result<WebConfig, WebConf
         .trim_end_matches('/')
         .to_string();
 
-    let dev_proxy_target = env
-        .dev_proxy_target
-        .or(web.dev_proxy_target)
-        .map(|s| s.trim_end_matches('/').to_string());
-
     Ok(WebConfig {
         bind_addr,
         daemon_url,
-        dev_proxy_target,
     })
 }
 
@@ -105,7 +94,6 @@ mod tests {
         let cfg = load_config(&path, EnvOverrides::default()).unwrap();
         assert_eq!(cfg.bind_addr, default_bind_addr());
         assert_eq!(cfg.daemon_url, "http://127.0.0.1:7070");
-        assert!(cfg.dev_proxy_target.is_none());
     }
 
     #[test]
@@ -118,17 +106,12 @@ mod tests {
 [web]
 bind_addr = "127.0.0.1:9090"
 daemon_url = "http://127.0.0.1:9070"
-dev_proxy_target = "http://127.0.0.1:5173"
 "#,
         )
         .unwrap();
         let cfg = load_config(&path, EnvOverrides::default()).unwrap();
         assert_eq!(cfg.bind_addr, "127.0.0.1:9090".parse().unwrap());
         assert_eq!(cfg.daemon_url, "http://127.0.0.1:9070");
-        assert_eq!(
-            cfg.dev_proxy_target.as_deref(),
-            Some("http://127.0.0.1:5173")
-        );
     }
 
     #[test]
@@ -147,7 +130,6 @@ daemon_url = "http://127.0.0.1:9070"
         let env = EnvOverrides {
             bind_addr: Some("0.0.0.0:8080".into()),
             daemon_url: Some("http://daemon:7070".into()),
-            dev_proxy_target: None,
         };
         let cfg = load_config(&path, env).unwrap();
         assert_eq!(cfg.bind_addr, "0.0.0.0:8080".parse().unwrap());

crates/maestro-web/src/main.rs

@@ -47,17 +47,9 @@ async fn run(config_override: Option<PathBuf>) -> Result<(), Box<dyn Error>> {
     tracing::info!(
         bind = %cfg.bind_addr,
         daemon = %cfg.daemon_url,
-        dev_proxy = ?cfg.dev_proxy_target,
         "loaded config",
     );
-    if cfg.dev_proxy_target.is_some() {
-        tracing::warn!(
-            "dev_proxy_target is set in config but not yet honored by the server \
-             (NAP-241 v1 ships only the embedded-bundle path)"
-        );
-    }
-
-    let router = router(&cfg);
+    let router = router(&cfg)?;
     let listener = TcpListener::bind(cfg.bind_addr).await?;
     tracing::info!(addr = %listener.local_addr()?, "serving");
     axum::serve(listener, router)

crates/maestro-web/src/proxy.rs

@@ -10,9 +10,11 @@ use std::sync::Arc;
 use axum::body::Body;
 use axum::extract::ws::{Message as AxMessage, WebSocket};
 use axum::extract::{Request, State};
-use axum::http::{header, HeaderMap, HeaderValue, StatusCode, Uri};
+use axum::http::{HeaderMap, HeaderValue, StatusCode, Uri};
 use axum::response::{IntoResponse, Response};
 use futures_util::{SinkExt, StreamExt};
+use maestro_protocol::routes::{self, UrlError};
+use maestro_protocol::ApiError;
 use tokio_tungstenite::tungstenite::Message as WsMessage;
 
 #[derive(Debug, Clone)]
@@ -25,21 +27,13 @@ pub struct UpstreamConfig {
 }
 
 impl UpstreamConfig {
-    pub fn from_daemon_url(daemon_url: &str) -> Self {
-        let http_base = daemon_url.trim_end_matches('/').to_string();
-        let ws_base = if let Some(rest) = http_base.strip_prefix("https://") {
-            format!("wss://{rest}")
-        } else if let Some(rest) = http_base.strip_prefix("http://") {
-            format!("ws://{rest}")
-        } else {
-            // Caller passed something already scheme-less or pre-wrapped; trust
-            // it. Validation happens at config-load time.
-            http_base.clone()
-        };
-        Self {
+    pub fn from_daemon_url(daemon_url: &str) -> Result<Self, UrlError> {
+        let http_base = routes::normalize_base(daemon_url).to_string();
+        let ws_base = routes::ws_base(&http_base)?;
+        Ok(Self {
             daemon_http_base: Arc::new(http_base),
             daemon_ws_base: Arc::new(ws_base),
-        }
+        })
     }
 }
 
@@ -170,29 +164,22 @@ fn filter_response_headers(headers: &reqwest::header::HeaderMap) -> HeaderMap {
 
 fn bad_gateway(msg: &str) -> Response {
     tracing::warn!(error = msg, "proxy: bad gateway");
-    // Plain JSON without a serde_json dep — the message is short and we control
-    // every byte we write, so manual escaping of `"` + `\` is enough here.
-    let escaped = msg.replace('\\', "\\\\").replace('"', "\\\"");
-    let body = format!(r#"{{"error":{{"code":"proxy_failed","message":"{escaped}"}}}}"#);
-    (
-        StatusCode::BAD_GATEWAY,
-        [(header::CONTENT_TYPE, "application/json")],
-        body,
-    )
-        .into_response()
+    api_error(StatusCode::BAD_GATEWAY, "proxy_failed", msg)
 }
 
 fn payload_too_large() -> Response {
     tracing::warn!(limit = MAX_REQUEST_BODY, "proxy: request body exceeds cap");
-    let body = format!(
-        r#"{{"error":{{"code":"payload_too_large","message":"request body exceeds {MAX_REQUEST_BODY} bytes"}}}}"#
-    );
-    (
+    api_error(
         StatusCode::PAYLOAD_TOO_LARGE,
-        [(header::CONTENT_TYPE, "application/json")],
-        body,
+        "payload_too_large",
+        &format!("request body exceeds {MAX_REQUEST_BODY} bytes"),
     )
-        .into_response()
+}
+
+/// Answer in the same envelope the daemon uses, so a client cannot tell whether
+/// a failure came from the daemon or from this proxy.
+fn api_error(status: StatusCode, code: &str, message: &str) -> Response {
+    (status, axum::Json(ApiError::new(code, message))).into_response()
 }
 
 // ---------------------------------------------------------------------------
@@ -291,8 +278,7 @@ pub async fn pump_ws(mut client: WebSocket, upstream_url: String) {
 const CLOSE_UPSTREAM_REJECTED: u16 = 4502;
 
 /// Turn a failed upstream WS handshake into a browser-facing close code +
-/// reason. When the daemon rejected the upgrade with its structured JSON error
-/// body (`{"error":{"code","message"}}` — see `local_api::error_response`),
+/// reason. When the daemon rejected the upgrade with an [`ApiError`] body,
 /// surface that message; otherwise fall back to a generic gateway reason. The
 /// reason rides a WS control frame, so it's truncated to the 123-byte limit.
 fn upstream_close_reason(e: &tokio_tungstenite::tungstenite::Error) -> (u16, String) {
@@ -301,13 +287,8 @@ fn upstream_close_reason(e: &tokio_tungstenite::tungstenite::Error) -> (u16, Str
         WsError::Http(resp) => resp
             .body()
             .as_ref()
-            .and_then(|b| serde_json::from_slice::<serde_json::Value>(b).ok())
-            .and_then(|v| {
-                v.get("error")
-                    .and_then(|err| err.get("message"))
-                    .and_then(|m| m.as_str())
-                    .map(str::to_owned)
-            })
+            .and_then(|b| serde_json::from_slice::<ApiError>(b).ok())
+            .map(|e| e.error.message)
             .unwrap_or_else(|| "the session's daemon rejected the attach".to_owned()),
         _ => "could not reach the session's daemon".to_owned(),
     };
@@ -346,14 +327,14 @@ mod tests {
 
     #[test]
     fn ws_base_swaps_http_scheme() {
-        let u = UpstreamConfig::from_daemon_url("http://127.0.0.1:7070/");
+        let u = UpstreamConfig::from_daemon_url("http://127.0.0.1:7070/").unwrap();
         assert_eq!(&*u.daemon_http_base, "http://127.0.0.1:7070");
         assert_eq!(&*u.daemon_ws_base, "ws://127.0.0.1:7070");
     }
 
     #[test]
     fn ws_base_swaps_https_scheme() {
-        let u = UpstreamConfig::from_daemon_url("https://daemon.example/");
+        let u = UpstreamConfig::from_daemon_url("https://daemon.example/").unwrap();
         assert_eq!(&*u.daemon_ws_base, "wss://daemon.example");
     }
 
@@ -362,7 +343,7 @@ mod tests {
     /// a bogus unreachable address; a 413 (not a 502) proves we bailed early.
     #[tokio::test]
     async fn oversized_request_body_is_rejected_with_413() {
-        let state = ProxyState::new(UpstreamConfig::from_daemon_url("http://127.0.0.1:9"));
+        let state = ProxyState::new(UpstreamConfig::from_daemon_url("http://127.0.0.1:9").unwrap());
         let big = vec![0u8; MAX_REQUEST_BODY + 1];
         let req = Request::builder()
             .method("POST")
@@ -379,7 +360,7 @@ mod tests {
     /// limit, not off-by-one against legitimate traffic.
     #[tokio::test]
     async fn body_at_cap_is_not_rejected_by_the_size_check() {
-        let state = ProxyState::new(UpstreamConfig::from_daemon_url("http://127.0.0.1:9"));
+        let state = ProxyState::new(UpstreamConfig::from_daemon_url("http://127.0.0.1:9").unwrap());
         let body = vec![0u8; MAX_REQUEST_BODY];
         let req = Request::builder()
             .method("POST")

crates/maestro-web/src/server.rs

@@ -5,6 +5,7 @@ use axum::extract::{Request, State, WebSocketUpgrade};
 use axum::response::{IntoResponse, Response};
 use axum::routing::{any, get};
 use axum::Router;
+use maestro_protocol::routes::{self, UrlError};
 
 use crate::config::WebConfig;
 use crate::proxy::{pump_ws, upstream_ws_url, ProxyState, UpstreamConfig};
@@ -12,30 +13,37 @@ use crate::static_bundle;
 
 /// Build the public router. The returned router is ready to hand to
 /// `axum::serve`.
-pub fn router(config: &WebConfig) -> Router {
-    let upstream = UpstreamConfig::from_daemon_url(&config.daemon_url);
+pub fn router(config: &WebConfig) -> Result<Router, UrlError> {
+    let upstream = UpstreamConfig::from_daemon_url(&config.daemon_url)?;
     let proxy_state = ProxyState::new(upstream);
 
     // Mount each route at its real path (not under `nest`, which would strip
     // the `/api` prefix before the proxy could forward it). WS routes go
     // first so the HTTP fallback doesn't shadow them.
-    Router::new()
-        .route("/api/attach/:id", any(ws_proxy))
-        .route("/api/events", any(ws_proxy))
+    Ok(Router::new()
+        .route(routes::patterns::ATTACH, any(ws_proxy))
+        .route(routes::EVENTS, any(ws_proxy))
         .route("/", get(serve_index))
         .fallback(catch_all)
-        .with_state(proxy_state)
+        .with_state(proxy_state))
 }
 
 /// Default handler: `/api/*` goes to the daemon, anything else falls through
 /// to the embedded SPA bundle (with SPA-style fallback to `index.html`).
 async fn catch_all(State(state): State<ProxyState>, req: Request) -> Response {
-    if req.uri().path().starts_with("/api/") {
+    if is_api_path(req.uri().path()) {
         return crate::proxy::proxy_http(State(state), req).await;
     }
     static_bundle::serve_path(req.uri().path())
 }
 
+/// Split point between the proxied daemon surface and the SPA bundle. A daemon
+/// route added outside [`routes::API_PREFIX`] would silently be answered with
+/// `index.html` instead of being forwarded.
+fn is_api_path(path: &str) -> bool {
+    path.starts_with(&format!("{}/", routes::API_PREFIX))
+}
+
 async fn ws_proxy(State(state): State<ProxyState>, ws: WebSocketUpgrade, req: Request) -> Response {
     let upstream_url = upstream_ws_url(&state, req.uri());
     ws.on_upgrade(move |socket| async move {

crates/maestro-web/tests/proxy.rs

@@ -1,72 +1,24 @@
 //! Integration tests for the maestro-web reverse-proxy.
 //!
-//! Spins up a tiny axum "daemon" on a random port, points maestro-web at it,
-//! and exercises both the HTTP and WS proxy paths end-to-end.
+//! Points maestro-web at a `MockDaemon` and exercises both the HTTP and WS
+//! proxy paths end-to-end.
 
+use maestro_testing::MockDaemon;
 use std::net::{Ipv4Addr, SocketAddr};
 use std::time::Duration;
 
-use axum::extract::ws::{Message as AxMessage, WebSocket, WebSocketUpgrade};
-use axum::response::IntoResponse;
-use axum::routing::{any, get};
-use axum::{Json, Router};
 use futures_util::{SinkExt, StreamExt};
 use maestro_web::config::WebConfig;
 use tokio::net::TcpListener;
 use tokio::sync::oneshot;
 use tokio_tungstenite::tungstenite::Message as WsMessage;
 
-async fn spawn_mock_daemon() -> (SocketAddr, oneshot::Sender<()>) {
-    async fn list_sessions() -> Json<serde_json::Value> {
-        Json(serde_json::json!([{"id": "session-1"}]))
-    }
-    async fn daemon_info() -> Json<serde_json::Value> {
-        Json(serde_json::json!({"hostname": "mock-host"}))
-    }
-    async fn echo_ws(ws: WebSocketUpgrade) -> impl IntoResponse {
-        ws.on_upgrade(echo_handler)
-    }
-    async fn echo_handler(mut socket: WebSocket) {
-        while let Some(Ok(msg)) = socket.next().await {
-            match msg {
-                AxMessage::Text(t) => {
-                    let _ = socket.send(AxMessage::Text(format!("echo:{t}"))).await;
-                }
-                AxMessage::Binary(b) => {
-                    let _ = socket.send(AxMessage::Binary(b)).await;
-                }
-                AxMessage::Close(_) => break,
-                _ => {}
-            }
-        }
-    }
-
-    let app = Router::new()
-        .route("/api/sessions", get(list_sessions))
-        .route("/api/info", get(daemon_info))
-        .route("/api/attach/:id", any(echo_ws));
-    let listener = TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, 0)))
-        .await
-        .unwrap();
-    let addr = listener.local_addr().unwrap();
-    let (tx, rx) = oneshot::channel::<()>();
-    tokio::spawn(async move {
-        let _ = axum::serve(listener, app)
-            .with_graceful_shutdown(async move {
-                let _ = rx.await;
-            })
-            .await;
-    });
-    (addr, tx)
-}
-
 async fn spawn_web(daemon_url: String) -> (SocketAddr, oneshot::Sender<()>) {
     let cfg = WebConfig {
         bind_addr: SocketAddr::from((Ipv4Addr::LOCALHOST, 0)),
         daemon_url,
-        dev_proxy_target: None,
     };
-    let router = maestro_web::router(&cfg);
+    let router = maestro_web::router(&cfg).expect("router");
     let listener = TcpListener::bind(cfg.bind_addr).await.unwrap();
     let addr = listener.local_addr().unwrap();
     let (tx, rx) = oneshot::channel::<()>();
@@ -82,7 +34,8 @@ async fn spawn_web(daemon_url: String) -> (SocketAddr, oneshot::Sender<()>) {
 
 #[tokio::test]
 async fn http_get_api_path_forwards_to_daemon() {
-    let (daemon_addr, _d) = spawn_mock_daemon().await;
+    let daemon = MockDaemon::start().await;
+    let daemon_addr = daemon.addr();
     let (web_addr, _w) = spawn_web(format!("http://{daemon_addr}")).await;
 
     let body: serde_json::Value = reqwest::get(format!("http://{web_addr}/api/sessions"))
@@ -91,12 +44,13 @@ async fn http_get_api_path_forwards_to_daemon() {
         .json()
         .await
         .unwrap();
-    assert_eq!(body[0]["id"], "session-1");
+    assert!(body.as_array().expect("array").is_empty());
 }
 
 #[tokio::test]
 async fn http_get_unrelated_path_falls_back_to_spa_index() {
-    let (daemon_addr, _d) = spawn_mock_daemon().await;
+    let daemon = MockDaemon::start().await;
+    let daemon_addr = daemon.addr();
     let (web_addr, _w) = spawn_web(format!("http://{daemon_addr}")).await;
 
     // The bundle is empty in test builds — the placeholder index.html serves.
@@ -114,22 +68,55 @@ async fn http_get_unrelated_path_falls_back_to_spa_index() {
 
 #[tokio::test]
 async fn ws_api_attach_forwards_to_daemon_and_echoes() {
-    let (daemon_addr, _d) = spawn_mock_daemon().await;
+    let daemon = MockDaemon::start().await;
+    let id = uuid::Uuid::from_u128(7);
+    daemon.add_session(maestro_testing::session(id, "/home/mock", "bash"));
+    let daemon_addr = daemon.addr();
     let (web_addr, _w) = spawn_web(format!("http://{daemon_addr}")).await;
 
-    let url = format!("ws://{web_addr}/api/attach/abc");
+    let url = format!("ws://{web_addr}/api/attach/{id}");
     let (mut ws, _) = tokio_tungstenite::connect_async(url).await.unwrap();
-    ws.send(WsMessage::Text("hello".into())).await.unwrap();
+    ws.send(WsMessage::Binary(b"hello".to_vec())).await.unwrap();
 
     let echoed = tokio::time::timeout(Duration::from_secs(1), ws.next())
         .await
         .unwrap();
     match echoed {
-        Some(Ok(WsMessage::Text(t))) => assert_eq!(t, "echo:hello"),
+        Some(Ok(WsMessage::Binary(b))) => assert_eq!(b, b"hello"),
         other => panic!("unexpected frame: {other:?}"),
     }
 }
 
+/// The client is upgraded before the upstream connection is attempted, so an
+/// upstream rejection has to come back as a close code. This is the end-to-end
+/// counterpart to `upstream_close_reason`, which had only unit tests: the
+/// daemon's own message must reach the browser rather than a generic failure.
+#[tokio::test]
+async fn ws_attach_to_an_unknown_session_closes_with_the_daemon_reason() {
+    let daemon = MockDaemon::start().await;
+    let (web_addr, _w) = spawn_web(format!("http://{}", daemon.addr())).await;
+
+    let url = format!("ws://{web_addr}/api/attach/{}", uuid::Uuid::new_v4());
+    let (mut ws, _) = tokio_tungstenite::connect_async(url)
+        .await
+        .expect("upgrade");
+
+    let frame = tokio::time::timeout(Duration::from_secs(2), ws.next())
+        .await
+        .expect("close frame");
+    match frame {
+        Some(Ok(WsMessage::Close(Some(cf)))) => {
+            assert_eq!(u16::from(cf.code), 4502);
+            assert!(
+                cf.reason.contains("no such session"),
+                "expected the daemon's message, got {:?}",
+                cf.reason
+            );
+        }
+        other => panic!("expected a Close frame with a reason, got {other:?}"),
+    }
+}
+
 #[tokio::test]
 async fn proxy_returns_502_when_daemon_unreachable() {
     // Bind a port, immediately drop the listener, hand the address to the

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)]
@@ -55,6 +57,9 @@ enum Command {
     /// Kill a session by ID.
     #[cfg(feature = "cli")]
     Kill(maestro_cli::cli::KillArgs),
+    /// Install or update the agent activity hook (#106).
+    #[cfg(feature = "cli")]
+    Hooks(maestro_cli::cli::HooksArgs),
     /// Per-host daemon: tmux wrapper + session API.
     #[cfg(feature = "daemon")]
     Daemon {
@@ -86,40 +91,64 @@ 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) => {
-            cli_dispatch(
+            maestro_cli::dispatch(
                 maestro_cli::cli::Command::List(args),
                 cli.config,
-                cli.daemon_url.clone(),
+                cli.daemon_url,
             )
             .await?
         }
         #[cfg(feature = "cli")]
         Command::Spawn(args) => {
-            cli_dispatch(
+            maestro_cli::dispatch(
                 maestro_cli::cli::Command::Spawn(args),
                 cli.config,
-                cli.daemon_url.clone(),
+                cli.daemon_url,
             )
             .await?
         }
         #[cfg(feature = "cli")]
         Command::Attach(args) => {
-            cli_dispatch(
+            maestro_cli::dispatch(
                 maestro_cli::cli::Command::Attach(args),
                 cli.config,
-                cli.daemon_url.clone(),
+                cli.daemon_url,
             )
             .await?
         }
         #[cfg(feature = "cli")]
         Command::Kill(args) => {
-            cli_dispatch(
+            maestro_cli::dispatch(
                 maestro_cli::cli::Command::Kill(args),
                 cli.config,
-                cli.daemon_url.clone(),
+                cli.daemon_url,
+            )
+            .await?
+        }
+        #[cfg(feature = "cli")]
+        Command::Hooks(args) => {
+            maestro_cli::dispatch(
+                maestro_cli::cli::Command::Hooks(args),
+                cli.config,
+                cli.daemon_url,
             )
             .await?
         }
@@ -141,16 +170,6 @@ async fn dispatch(cli: Cli) -> Result<(), Box<dyn std::error::Error>> {
     Ok(())
 }
 
-#[cfg(feature = "cli")]
-#[allow(clippy::result_large_err)]
-async fn cli_dispatch(
-    command: maestro_cli::cli::Command,
-    config: Option<PathBuf>,
-    daemon_url: Option<String>,
-) -> Result<(), maestro_cli::CliError> {
-    maestro_cli::dispatch(command, config, daemon_url).await
-}
-
 fn init_tracing(cli: &Cli) {
     let filter = if is_cli_subcommand(&cli.command) {
         cli_filter(cli.verbose)
@@ -164,26 +183,120 @@ 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(_)
+        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
 }
 
 fn cli_filter(verbose: u8) -> EnvFilter {
-    match (std::env::var_os("RUST_LOG"), verbose) {
-        (Some(_), _) => {
-            EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("warn"))
-        }
-        (None, 0) => EnvFilter::new("warn"),
-        (None, 1) => EnvFilter::new("info"),
-        (None, 2) => EnvFilter::new("debug"),
-        (None, _) => EnvFilter::new("trace"),
+    match std::env::var_os("RUST_LOG") {
+        // An explicit `RUST_LOG` always wins over `-v` flags.
+        Some(_) => EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("warn")),
+        None => EnvFilter::new(verbosity_directive(verbose)),
+    }
+}
+
+/// Map a `-v` repeat count to a tracing directive. Pure so it can be unit
+/// tested without touching the process-global `RUST_LOG`.
+fn verbosity_directive(verbose: u8) -> &'static str {
+    match verbose {
+        0 => "warn",
+        1 => "info",
+        2 => "debug",
+        _ => "trace",
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn verbosity_directive_maps_repeat_count() {
+        assert_eq!(verbosity_directive(0), "warn");
+        assert_eq!(verbosity_directive(1), "info");
+        assert_eq!(verbosity_directive(2), "debug");
+        // Anything past `-vv` saturates at trace.
+        assert_eq!(verbosity_directive(3), "trace");
+        assert_eq!(verbosity_directive(u8::MAX), "trace");
+    }
+
+    /// Parse argv the way `main` does, returning just the dispatched subcommand.
+    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() {
+        // Stable UUID for the subcommands that take a session id positional.
+        const SID: &str = "00000000-0000-0000-0000-000000000000";
+        // These four drive `cli_filter`; the tracing init must treat them as CLI.
+        for argv in [
+            vec!["maestro", "list"],
+            vec![
+                "maestro",
+                "spawn",
+                "--daemon-url",
+                "d",
+                "--cwd",
+                "/tmp",
+                "--command",
+                "bash",
+            ],
+            vec!["maestro", "attach", SID],
+            vec!["maestro", "kill", SID],
+        ] {
+            let cmd = command_of(&argv);
+            assert!(
+                is_cli_subcommand(&cmd),
+                "expected {argv:?} to be classified as a CLI subcommand"
+            );
+        }
+    }
+
+    #[cfg(all(feature = "cli", feature = "daemon", feature = "tui"))]
+    #[test]
+    fn server_subcommands_are_not_classified_as_cli() {
+        // daemon / tui get the env-driven filter, not the `-v` one.
+        for argv in [vec!["maestro", "daemon"], vec!["maestro", "tui"]] {
+            let cmd = command_of(&argv);
+            assert!(
+                !is_cli_subcommand(&cmd),
+                "expected {argv:?} to NOT be classified as a CLI subcommand"
+            );
+        }
+    }
+
+    /// Under a non-`cli` feature build, the classifier is the always-false stub
+    /// and every subcommand takes the env-driven filter.
+    #[cfg(not(feature = "cli"))]
+    #[test]
+    fn classifier_is_always_false_without_cli_feature() {
+        #[cfg(feature = "daemon")]
+        assert!(!is_cli_subcommand(&command_of(&["maestro", "daemon"])));
+        #[cfg(feature = "tui")]
+        assert!(!is_cli_subcommand(&command_of(&["maestro", "tui"])));
     }
 }

crates/maestro/tests/cli.rs

@@ -0,0 +1,119 @@
+//! Smoke tests for the umbrella `maestro` binary's dispatch surface (NAP-271).
+//!
+//! These run against the real built binary via Cargo's `CARGO_BIN_EXE_maestro`
+//! env var. Integration tests are compiled with the package's active feature
+//! set, so the per-subcommand checks are `#[cfg]`-gated and the suite is
+//! meaningful under every feature subset (`cli` / `daemon` / `tui`)
+//! as well as the default all-features build. The asserts only inspect
+//! `--help`/`--version` output and exit codes, so nothing is actually started.
+
+use std::process::Command;
+
+fn maestro() -> Command {
+    Command::new(env!("CARGO_BIN_EXE_maestro"))
+}
+
+fn run(args: &[&str]) -> (bool, String) {
+    let out = maestro().args(args).output().expect("run maestro");
+    let combined = format!(
+        "{}{}",
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr)
+    );
+    (out.status.success(), combined)
+}
+
+/// Subcommands expected in `--help`, derived from the active feature set.
+fn expected_subcommands() -> Vec<&'static str> {
+    let mut subs: Vec<&'static str> = Vec::new();
+    #[cfg(feature = "cli")]
+    subs.extend(["list", "spawn", "attach", "kill"]);
+    #[cfg(feature = "daemon")]
+    subs.extend(["daemon"]);
+    #[cfg(feature = "tui")]
+    subs.extend(["tui"]);
+    subs
+}
+
+#[test]
+fn top_level_help_lists_subcommands() {
+    let (ok, text) = run(&["--help"]);
+    assert!(ok, "--help should exit 0:\n{text}");
+    for sub in expected_subcommands() {
+        assert!(
+            text.contains(sub),
+            "--help missing subcommand `{sub}`:\n{text}"
+        );
+    }
+}
+
+#[test]
+fn version_flag_succeeds() {
+    let (ok, text) = run(&["--version"]);
+    assert!(ok, "--version should exit 0:\n{text}");
+    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 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 exit 0:\n{text}");
+    assert!(text.contains("Usage"), "expected usage text:\n{text}");
+}
+
+#[test]
+fn unknown_subcommand_fails() {
+    let (ok, text) = run(&["definitely-not-a-subcommand"]);
+    assert!(!ok, "unknown subcommand should fail:\n{text}");
+}
+
+#[cfg(feature = "cli")]
+#[test]
+fn cli_subcommand_help_works() {
+    // A representative CLI subcommand resolves and renders help.
+    let (ok, text) = run(&["spawn", "--help"]);
+    assert!(ok, "spawn --help should exit 0:\n{text}");
+    assert!(
+        text.contains("--daemon-url"),
+        "spawn help missing flags:\n{text}"
+    );
+}
+
+#[cfg(feature = "daemon")]
+#[test]
+fn daemon_subcommand_help_works() {
+    let (ok, text) = run(&["daemon", "--help"]);
+    assert!(ok, "daemon --help should exit 0:\n{text}");
+}
+
+#[cfg(feature = "tui")]
+#[test]
+fn tui_subcommand_help_works() {
+    let (ok, text) = run(&["tui", "--help"]);
+    assert!(ok, "tui --help should exit 0:\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`).
 
@@ -131,24 +134,47 @@ cover every v1 action — only override what you want to change:
 
 ```toml
 [tui]
+theme = "dark"              # see the theme list below
 leader = "ctrl-a"            # one byte that escapes Insert mode
-chord_timeout_ms = 1000      # how long to hold a partial chord like `g`
+chord_timeout_ms = 1000      # how long to hold a partial chord like `ctrl-w`
 
 [tui.keymap.normal]
 "i"            = "EnterInsert"
-"s"            = "OpenSpawnModal"
+"s"            = "NewDraftPane"
 "x"            = "KillHighlighted"
+"r"            = "RenameHighlighted"
 "?"            = "ShowHelp"
-"ctrl-t"       = "NewTab"
-"g t"          = "NextTab"
 "ctrl-w h"     = "FocusSidebar"
 "enter"        = "AttachHighlighted"
+"pageup"       = "ScrollPanePageUp"
+"pagedown"     = "ScrollPanePageDown"
 
 [tui.keymap.insert]
 # (leader is added automatically as LeaveInsert; only override here when you
 # want extra Insert-mode bindings)
 ```
 
+`theme` selects the complete TUI palette. `dark` is the default and follows
+Maestro's terminal-native dark product palette; `light` is its light peer;
+`ansi` uses the terminal's named ANSI colours for terminals without truecolour.
+The remaining presets adapt well-known editor themes, with individual colours
+lifted or darkened where the originals fall short of the WCAG AA contrast
+floors the palette tests assert:
+
+| name              | based on         |
+|-------------------|------------------|
+| `solarized-dark`  | Solarized Dark   |
+| `solarized-light` | Solarized Light  |
+| `catppuccin`      | Catppuccin Mocha |
+| `github-dark`     | GitHub Dark      |
+| `github-light`    | GitHub Light     |
+| `tokyo-night`     | Tokyo Night      |
+| `gruvbox`         | Gruvbox Dark     |
+| `nord`            | Nord             |
+| `dracula`         | Dracula          |
+
+An unknown name is rejected as an `[tui].theme` configuration error.
+
 The full action vocabulary is the `Action` enum in
 `crates/maestro-tui/src/action.rs`.
 
@@ -280,8 +306,9 @@ maestro daemon                  # foreground; or wire your own service manager
 ```
 
 Every setting has a default, so `~/.config/maestro/config.toml` is optional —
-create it only to change the bind address, worktree root, spawn presets, or TUI
-keymap.
+create it only to change the bind address, spawn presets, or TUI
+keymap. (Worktrees live inside their base repos at `<repo>/worktrees/<branch>`;
+set `[daemon].worktree_root` only to override that.)
 
 ## Non-Linux hosts