feat(maestro): spawn form rerolls from a fetched name batch (#53)

Cargo.lock

@@ -1102,6 +1102,7 @@ dependencies = [
  "futures-util",
  "libc",
  "maestro-config",
+ "maestro-names",
  "maestro-protocol",
  "reqwest",
  "serde",
@@ -1146,6 +1147,13 @@ 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"

Cargo.toml

@@ -18,6 +18,7 @@ dirs = "5"
 futures-util = { version = "0.3", default-features = false, features = ["sink", "std"] }
 libc = "0.2"
 maestro-config = { path = "crates/maestro-config" }
+maestro-names = { path = "crates/maestro-names" }
 maestro-protocol = { path = "crates/maestro-protocol" }
 maestro-testing = { path = "crates/maestro-testing" }
 maestro-tui = { path = "crates/maestro-tui" }

crates/maestro-daemon/Cargo.toml

@@ -18,6 +18,7 @@ dirs.workspace = true
 futures-util.workspace = true
 libc.workspace = true
 maestro-config.workspace = true
+maestro-names.workspace = true
 maestro-protocol.workspace = true
 serde.workspace = true
 serde_json.workspace = true
@@ -32,5 +33,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/branches.rs

@@ -1,167 +0,0 @@
-//! `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/lib.rs

@@ -9,7 +9,6 @@
 
 pub mod activity;
 pub mod attach;
-pub mod branches;
 pub mod cli;
 pub mod config;
 pub mod dirlist;

crates/maestro-daemon/src/local_api.rs

@@ -19,7 +19,7 @@ use axum::routing::{any, delete, get};
 use axum::{Json, Router};
 use maestro_config::SpawnPreset;
 use maestro_protocol::{
-    routes, ApiError, CatalogEvent, CreateSessionRequest, DaemonInfo, GitRoot, Session,
+    routes, ApiError, CatalogEvent, CreateSessionRequest, DaemonInfo, GitRoot, NameBatch, Session,
     PROTOCOL_VERSION,
 };
 use serde::Deserialize;
@@ -48,7 +48,7 @@ pub fn router(state: LocalApiState) -> Router {
         .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))
@@ -122,6 +122,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(),

crates/maestro-daemon/tests/branches.rs

@@ -1,141 +0,0 @@
-//! 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/local_api.rs

@@ -232,6 +232,57 @@ async fn projects_returns_empty_for_a_disabled_scanner() {
     assert!(projects.is_empty());
 }
 
+/// #53: every returned handle splits into a known adjective and noun.
+fn assert_valid_names(batch: &maestro_protocol::NameBatch) {
+    for name in &batch.names {
+        let (adj, noun) = name.split_once('-').unwrap_or_else(|| {
+            panic!("handle {name:?} is not adjective-noun");
+        });
+        assert!(
+            maestro_names::ADJECTIVES.contains(&adj),
+            "{adj} not in ADJECTIVES"
+        );
+        assert!(maestro_names::NOUNS.contains(&noun), "{noun} not in NOUNS");
+    }
+}
+
+#[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

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,96 @@
+//! The one home of the session-handle wordlists (#53).
+//!
+//! Previously duplicated in `web/src/names.ts`; every client now gets handles
+//! from here, served by `GET /api/names`.
+
+/// Musical adjectives — tempo, dynamics, and articulation markings.
+pub const ADJECTIVES: &[&str] = &[
+    "allegro",
+    "andante",
+    "adagio",
+    "presto",
+    "vivace",
+    "largo",
+    "grave",
+    "lento",
+    "moderato",
+    "crescendo",
+    "staccato",
+    "legato",
+    "forte",
+    "dolce",
+    "agitato",
+    "cantabile",
+    "sostenuto",
+    "tremolo",
+    "rubato",
+    "marcato",
+    "brillante",
+    "maestoso",
+    "grazioso",
+    "espressivo",
+    "tranquillo",
+    "animato",
+    "spirito",
+    "sotto",
+    "vivo",
+    "feroce",
+];
+
+/// Musical nouns — instruments and forms from the concert hall.
+pub const NOUNS: &[&str] = &[
+    "cello", "violin", "viola", "oboe", "flute", "clarinet", "bassoon", "trumpet", "trombone",
+    "tuba", "horn", "timpani", "harp", "piano", "organ", "lyre", "lute", "fugue", "sonata",
+    "octave", "chord", "cadence", "prelude", "rondo", "nocturne", "scherzo", "refrain", "coda",
+    "motif", "overture",
+];
+
+/// Upper bound for a `GET /api/names?count=N` batch.
+pub const MAX_BATCH: usize = 100;
+
+/// A fresh `adjective-noun` handle, e.g. `allegro-cello`.
+pub fn generate() -> String {
+    use rand::seq::SliceRandom;
+    let mut rng = rand::thread_rng();
+    format!(
+        "{}-{}",
+        ADJECTIVES.choose(&mut rng).unwrap(),
+        NOUNS.choose(&mut rng).unwrap()
+    )
+}
+
+/// `count` fresh handles (the caller clamps; this only trusts its input).
+pub fn generate_batch(count: usize) -> Vec<String> {
+    (0..count).map(|_| generate()).collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn generated_name_is_adjective_dash_noun() {
+        let name = generate();
+        let (adj, noun) = name.split_once('-').expect("name contains a dash");
+        assert!(ADJECTIVES.contains(&adj), "{adj} not in ADJECTIVES");
+        assert!(NOUNS.contains(&noun), "{noun} not in NOUNS");
+    }
+
+    #[test]
+    fn batch_returns_the_requested_count() {
+        assert_eq!(generate_batch(1).len(), 1);
+        assert_eq!(generate_batch(50).len(), 50);
+        for name in generate_batch(10) {
+            let (adj, noun) = name.split_once('-').unwrap();
+            assert!(ADJECTIVES.contains(&adj) && NOUNS.contains(&noun));
+        }
+    }
+
+    #[test]
+    fn rerolls_can_differ() {
+        // 30x30=900 combinations; 20 draws all matching has probability ~1e-40.
+        let first = generate();
+        let differs = (0..20).any(|_| generate() != first);
+        assert!(differs);
+    }
+}

crates/maestro-protocol/src/lib.rs

@@ -212,21 +212,6 @@ pub struct Project {
     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 {
@@ -294,6 +279,13 @@ pub struct DaemonInfo {
     pub presets: Vec<SpawnPreset>,
 }
 
+/// Payload of `GET /api/names?count=N` (#53) — a batch of fresh
+/// `adjective-noun` session handles generated by the `maestro-names` crate.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct NameBatch {
+    pub names: Vec<String>,
+}
+
 // ---------------------------------------------------------------------------
 // Catalog events (`WS /api/events`)
 // ---------------------------------------------------------------------------

crates/maestro-protocol/src/routes.rs

@@ -21,14 +21,18 @@ pub const RECENT_DIRS: &str = "/api/recent-dirs";
 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.
+/// Name of the query parameter [`DIRS`] and [`GITROOT`] both take.
 pub const PATH_QUERY: &str = "path";
 
+/// Name of the query parameter [`NAMES`] takes.
+pub const COUNT_QUERY: &str = "count";
+
 /// `DELETE /api/sessions/:id`.
 pub fn session(id: Uuid) -> String {
     format!("{SESSIONS}/{id}")
@@ -183,7 +187,7 @@ mod tests {
             RECENT_DIRS,
             PROJECTS,
             GITROOT,
-            BRANCHES,
+            NAMES,
             EVENTS,
         ] {
             assert!(path.starts_with(API_PREFIX), "{path} escapes {API_PREFIX}");

web/src/api.ts

@@ -5,6 +5,7 @@ import type {
   DaemonInfo,
   DirListing,
   GitRoot,
+  NameBatch,
   Projects,
   RecentDirs,
   Session,
@@ -81,4 +82,11 @@ export async function gitRoot(path: string): Promise<GitRoot> {
   return jsonOrError(await fetch(url, { credentials: "same-origin" }));
 }
 
+/** A batch of fresh session handles for the spawn form's instant reroll (#53).
+ * Rerolls consume the batch locally; only exhaustion goes back to the daemon. */
+export async function fetchNames(count: number): Promise<NameBatch> {
+  const url = `${routes.NAMES}?${routes.COUNT_QUERY}=${encodeURIComponent(count)}`;
+  return jsonOrError(await fetch(url, { credentials: "same-origin" }));
+}
+
 export { eventsWsUrl } from "./routes.js";

web/src/names.ts

@@ -1,29 +0,0 @@
-// Client-side session-handle generator for the spawn form's instant reroll
-// (#23/#27). The spawn form rerolls without a round trip, so the wordlists
-// live here; nothing server-side generates handles.
-
-/** Musical adjectives — tempo, dynamics, and articulation markings. */
-const ADJECTIVES = [
-  "allegro", "andante", "adagio", "presto", "vivace", "largo", "grave", "lento",
-  "moderato", "crescendo", "staccato", "legato", "forte", "dolce", "agitato",
-  "cantabile", "sostenuto", "tremolo", "rubato", "marcato", "brillante",
-  "maestoso", "grazioso", "espressivo", "tranquillo", "animato", "spirito",
-  "sotto", "vivo", "feroce",
-];
-
-/** Musical nouns — instruments and forms from the concert hall. */
-const NOUNS = [
-  "cello", "violin", "viola", "oboe", "flute", "clarinet", "bassoon", "trumpet",
-  "trombone", "tuba", "horn", "timpani", "harp", "piano", "organ", "lyre",
-  "lute", "fugue", "sonata", "octave", "chord", "cadence", "prelude", "rondo",
-  "nocturne", "scherzo", "refrain", "coda", "motif", "overture",
-];
-
-function pick<T>(list: T[]): T {
-  return list[Math.floor(Math.random() * list.length)];
-}
-
-/** A fresh `adjective-noun` handle, e.g. `allegro-cello`. */
-export function generateName(): string {
-  return `${pick(ADJECTIVES)}-${pick(NOUNS)}`;
-}

web/src/projectPicker.test.ts

@@ -15,7 +15,8 @@ function project(overrides: Partial<Project>): Project {
   };
 }
 
-/** Two fetches gate the form's initial load: /api/info then /api/projects. */
+/** Three fetches gate the form's initial load: /api/info, /api/projects, and
+ * the /api/names batch (#53). */
 function stubFetch(info: unknown, projects: Project[]): void {
   vi.stubGlobal(
     "fetch",
@@ -25,7 +26,9 @@ function stubFetch(info: unknown, projects: Project[]): void {
         ? info
         : url.includes("/api/projects")
           ? projects
-          : undefined;
+          : url.includes("/api/names")
+            ? { names: ["allegro-cello", "presto-fugue", "adagio-lyre"] }
+            : undefined;
       return new Response(JSON.stringify(body), { status: 200 });
     }),
   );

web/src/routes.ts

@@ -11,11 +11,15 @@ export const DIRS = "/api/dirs";
 export const RECENT_DIRS = "/api/recent-dirs";
 export const PROJECTS = "/api/projects";
 export const GITROOT = "/api/gitroot";
+export const NAMES = "/api/names";
 export const EVENTS = "/api/events";
 
 /** Name of the query parameter `DIRS` and `GITROOT` both take. */
 export const PATH_QUERY = "path";
 
+/** Name of the query parameter `NAMES` takes. */
+export const COUNT_QUERY = "count";
+
 export function session(id: Uuid): string {
   return `${SESSIONS}/${encodeURIComponent(id)}`;
 }

web/src/spawnForm.ts

@@ -1,8 +1,7 @@
 import { escapeHtml } from "./html.js";
-import { createSession, getDaemonInfo, projects as fetchProjects, gitRoot } from "./api.js";
+import { createSession, fetchNames, getDaemonInfo, projects as fetchProjects, gitRoot } from "./api.js";
 import { attachDirAutocomplete } from "./dirAutocomplete.js";
 import { filterProjects, groupProjects, isStale, sortProjects } from "./projectList.js";
-import { generateName } from "./names.js";
 import type { CreateSessionRequest, Project, Session, SpawnPreset } from "./types.js";
 import { abbreviateCwd, abbreviateFolderName } from "./types.js";
 
@@ -197,8 +196,46 @@ export function createSpawnForm(opts: SpawnFormOptions): SpawnFormHandle {
   const syncBranchToName = () => {
     if (!branchEdited) branchInput.value = nameInput.value;
   };
-  nameInput.value = prefill.name ?? generateName();
+  // Handles come from `GET /api/names` in batches (#53): the first one seeds
+  // the field, rerolls consume the rest locally so they stay instant, and a
+  // new batch is fetched when (and only when) the queue runs dry. One refill
+  // at a time keeps rapid rerolls from storming the daemon.
+  const NAME_BATCH_SIZE = 20;
+  let nameQueue: string[] = [];
+  let nameFetch: Promise<void> | null = null;
+  // Guards against a late batch clobbering something the operator already
+  // typed or rerolled.
+  let nameTouched = Boolean(prefill.name);
+  const refillNames = (): Promise<void> => {
+    if (!nameFetch) {
+      nameFetch = fetchNames(NAME_BATCH_SIZE)
+        .then((batch) => {
+          if (!destroyed) nameQueue.push(...batch.names);
+        })
+        .catch(() => {
+          /* reroll just stays on the current name */
+        })
+        .finally(() => {
+          nameFetch = null;
+        });
+    }
+    return nameFetch;
+  };
+
+  nameInput.value = prefill.name ?? "";
+  if (!nameTouched) {
+    void refillNames().then(() => {
+      if (destroyed || nameTouched || nameInput.value) return;
+      const next = nameQueue.shift();
+      if (next !== undefined) {
+        nameInput.value = next;
+        syncBranchToName();
+        emit();
+      }
+    });
+  }
   nameInput.addEventListener("input", () => {
+    nameTouched = true;
     syncBranchToName();
     emit();
   });
@@ -207,9 +244,21 @@ export function createSpawnForm(opts: SpawnFormOptions): SpawnFormHandle {
     emit();
   });
   (form.querySelector(".reroll") as HTMLButtonElement).addEventListener("click", () => {
-    nameInput.value = generateName();
-    syncBranchToName();
-    emit();
+    nameTouched = true;
+    const apply = () => {
+      if (destroyed) return;
+      const next = nameQueue.shift();
+      if (next === undefined) return;
+      nameInput.value = next;
+      syncBranchToName();
+      emit();
+    };
+    // Only hit the daemon when the local batch is exhausted.
+    if (nameQueue.length === 0) {
+      void refillNames().then(apply);
+    } else {
+      apply();
+    }
   });
   syncBranchToName(); // seed the branch from the initial name
 

web/src/spawnFormNames.test.ts

@@ -0,0 +1,129 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createSpawnForm, type SpawnFormHandle } from "./spawnForm.js";
+
+const BATCH_A = ["allegro-cello", "presto-fugue", "adagio-lyre"];
+const BATCH_B = ["forte-oboe", "largo-tuba", "vivace-harp"];
+
+/** Stub the three fetches the form's initial load makes. Records every
+ * /api/names URL so tests can assert how many batches were fetched. */
+function stubFetch(batches: string[][]): string[] {
+  let batch = 0;
+  const nameUrls: string[] = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes("/api/names")) {
+        nameUrls.push(url);
+        const names = batches[Math.min(batch, batches.length - 1)];
+        batch += 1;
+        return new Response(JSON.stringify({ names }), { status: 200 });
+      }
+      const body = url.includes("/api/info")
+        ? { hostname: "h", version: "0", home_dir: "/home/user", presets: [] }
+        : [];
+      return new Response(JSON.stringify(body), { status: 200 });
+    }),
+  );
+  return nameUrls;
+}
+
+describe("spawnForm name batch (#53)", () => {
+  let handle: SpawnFormHandle | null = null;
+  let nameUrls: string[];
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    handle?.destroy();
+    handle = null;
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  async function mount(seed?: Parameters<typeof createSpawnForm>[0]["seed"]) {
+    nameUrls = stubFetch([BATCH_A, BATCH_B]);
+    handle = createSpawnForm({ seed, onSuccess() {} });
+    document.body.appendChild(handle.el);
+    for (let i = 0; i < 40; i++) await Promise.resolve();
+    return handle.el;
+  }
+
+  const nameOf = (form: HTMLFormElement) =>
+    form.querySelector<HTMLInputElement>("input[name=name]")!.value;
+
+  function reroll(form: HTMLFormElement): void {
+    form.querySelector<HTMLButtonElement>(".reroll")!.click();
+  }
+
+  async function drain(): Promise<void> {
+    for (let i = 0; i < 40; i++) await Promise.resolve();
+  }
+
+  it("seeds its name from a fetched batch when no seed provides one", async () => {
+    const form = await mount();
+    expect(BATCH_A).toContain(nameOf(form));
+    expect(nameUrls).toHaveLength(1);
+    expect(nameUrls[0]).toContain("/api/names");
+    expect(nameUrls[0]).toContain("count=");
+  });
+
+  it("keeps a seeded name and defers fetching until the first reroll", async () => {
+    const form = await mount({ name: "my-session" });
+    expect(nameOf(form)).toBe("my-session");
+    expect(nameUrls ?? []).toHaveLength(0);
+
+    reroll(form);
+    await drain();
+    expect(nameOf(form)).not.toBe("my-session");
+    expect(nameUrls).toHaveLength(1);
+  });
+
+  it("rerolls locally from the batch with no extra round trips", async () => {
+    const form = await mount();
+    expect(nameUrls).toHaveLength(1);
+    const seen = new Set([nameOf(form)]);
+
+    for (let i = 0; i < BATCH_A.length; i++) {
+      reroll(form);
+      seen.add(nameOf(form));
+    }
+    await drain();
+
+    // Every value came from the one fetched batch.
+    expect(seen.size).toBeGreaterThanOrEqual(2);
+    for (const value of seen) {
+      expect([...BATCH_A, ...BATCH_B]).toContain(value);
+    }
+    expect(nameUrls).toHaveLength(2); // refetch fired when the batch ran out
+    expect(nameUrls[1]).toContain("/api/names");
+  });
+
+  it("refetches only once even if rerolls outpace the network", async () => {
+    const form = await mount();
+    // Drain the batch without awaiting between rerolls.
+    for (let i = 0; i < BATCH_A.length + 1; i++) reroll(form);
+    await drain();
+    // One refill in flight covers the whole run — no fetch storm.
+    expect(nameUrls.length).toBeLessThanOrEqual(2);
+  });
+
+  it("does not clobber an operator-typed name when the batch arrives late", async () => {
+    nameUrls = stubFetch([BATCH_A]);
+    handle = createSpawnForm({ onSuccess() {} });
+    const form = handle.el;
+    document.body.appendChild(form);
+
+    // The operator types before the fetch resolves.
+    const input = form.querySelector<HTMLInputElement>("input[name=name]")!;
+    input.value = "hand-typed";
+    input.dispatchEvent(new Event("input"));
+    for (let i = 0; i < 40; i++) await Promise.resolve();
+
+    expect(nameOf(form)).toBe("hand-typed");
+  });
+});

web/src/types.ts

@@ -83,6 +83,12 @@ export interface GitRoot {
   root?: string;
 }
 
+/** `GET /api/names?count=N` — a batch of fresh session handles (#53). Mirrors
+ * `maestro_protocol::NameBatch`. */
+export interface NameBatch {
+  names: string[];
+}
+
 /** One discovered git repository (or linked worktree) for `GET /api/projects`
  * (#54). Mirrors `maestro_protocol::Project`. */
 export interface Project {