feat(maestro): port the command bar to React (#247)

CommandBar, ResultList, ActionPage and useCommandBar over the same
model docs/COMMAND-BAR.md specifies: sigils, empty-query session order,
the drill-in action page, and the keys.

The highlight now walks the rows in the order they render. The legacy
bar indexed the highlight by display order but activated by rank order,
so Enter could act on a different row than the one lit.

web/src/commandBar.ts

@@ -21,7 +21,7 @@ import {
   type MatchRange,
   type MatchResult,
   type SessionCandidate,
-} from "./matcher.js";
+} from "./utils/matcher.js";
 import { splitPath } from "./paths.js";
 import { splitCommand } from "./toolIcon.js";
 import { abbreviateCwd, sessionName, sessionTreePath, type Session } from "./types.js";

web/src/components/commandBar/ActionPage.tsx

@@ -0,0 +1,34 @@
+// A session's action page (docs/COMMAND-BAR.md, "Drill-in"): the same overlay
+// over kill, rename and spawn similar, still fuzzy searchable. The page names
+// the session it acts on, so the target is never ambiguous.
+
+import { sessionName, type Session } from "../../types.js";
+import { ResultList } from "./ResultList.js";
+import type { BarGroup } from "./model.js";
+
+export interface ActionPageProps {
+  session: Session;
+  /** The three actions, ranked by the query line — one kind, so no headers. */
+  groups: BarGroup[];
+  highlighted: number;
+  onActivate(index: number): void;
+}
+
+export function ActionPage({ session, groups, highlighted, onActivate }: ActionPageProps) {
+  return (
+    <>
+      <div
+        role="presentation"
+        className="cmdbar-page-header border-b border-border px-sp-3 py-sp-1 text-fs-11 text-muted"
+      >
+        {`Actions for "${sessionName(session)}"`}
+      </div>
+      <ResultList
+        groups={groups}
+        showHeaders={false}
+        highlighted={highlighted}
+        onActivate={onActivate}
+      />
+    </>
+  );
+}

web/src/components/commandBar/CommandBar.test.tsx

@@ -0,0 +1,407 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  KILL_SESSION_EVENT,
+  RENAME_SESSION_EVENT,
+  SESSION_SELECT_EVENT,
+  SPAWN_SIMILAR_EVENT,
+} from "../../catalog.js";
+import { COMMAND_SPECS, type Command } from "../../commands.js";
+import type { Session } from "../../types.js";
+import { CommandBar, SPAWN_DIRECTORY_EVENT, type CommandBarProps } from "./CommandBar.js";
+
+vi.mock("../../api.js", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  listDir: vi.fn(async () => ({ path: "", entries: [] })),
+  projects: vi.fn(async () => []),
+  recentDirs: vi.fn(async () => ({ dirs: [] })),
+}));
+
+function session(id: string, over: Partial<Session> = {}): Session {
+  return {
+    id,
+    cwd: "/home/me/dev/api",
+    command: "bash",
+    env: {},
+    metadata: { name: id },
+    status: "Running",
+    created_at: "2026-01-01T00:00:00Z",
+    ...over,
+  };
+}
+
+function command(over: Partial<Command> = {}): Command {
+  return {
+    id: "cmd",
+    label: "A command",
+    group: "Test",
+    keys: ["a"],
+    scope: "global",
+    run: () => {},
+    ...over,
+  };
+}
+
+const sessions = [
+  session("api", { current_cwd: "/home/me/dev/api", last_focused_at: "2026-01-01T11:00:00Z" }),
+  session("worker", {
+    current_cwd: "/home/me/dev/worker",
+    last_focused_at: "2026-01-01T10:00:00Z",
+  }),
+  session("notes", { current_cwd: "/home/me/notes" }),
+];
+
+function open(over: Partial<CommandBarProps> = {}) {
+  return render(
+    <CommandBar
+      sessions={sessions}
+      homeDir="/home/me"
+      commands={[]}
+      onOpenSession={() => {}}
+      onClose={() => {}}
+      {...over}
+    />,
+  );
+}
+
+function input(): HTMLInputElement {
+  return screen.getByRole("combobox") as HTMLInputElement;
+}
+
+function type(value: string): void {
+  fireEvent.change(input(), { target: { value } });
+}
+
+function press(key: string, init: Record<string, unknown> = {}): void {
+  fireEvent.keyDown(input(), { key, ...init });
+}
+
+function rowNames(): string[] {
+  return [...document.querySelectorAll(".cmdbar-row-name")].map((r) => r.textContent ?? "");
+}
+
+function activeName(): string | undefined {
+  return document.querySelector(".cmdbar-row.is-active .cmdbar-row-name")?.textContent ?? undefined;
+}
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+describe("the overlay", () => {
+  it("is a registry command, so the help overlay lists it", () => {
+    const spec = COMMAND_SPECS.find((s) => s.id === "bar.open");
+    expect(spec?.keys).toEqual(["ctrl-k"]);
+    expect(spec?.scope).toBe("global");
+  });
+
+  it("lists sessions by recency under a kind header on an empty query", () => {
+    open();
+    expect([...document.querySelectorAll(".cmdbar-group-title")].map((h) => h.textContent)).toEqual([
+      "Sessions",
+    ]);
+    expect(rowNames()).toEqual(["api", "worker", "notes"]);
+    expect(activeName()).toBe("api");
+  });
+
+  it("ranks a typed query through the matcher and highlights the matched range", () => {
+    open();
+    type("wor");
+    expect(rowNames()).toEqual(["worker"]);
+    expect([...document.querySelectorAll(".cmdbar-row-name mark")].map((m) => m.textContent)).toEqual(
+      ["wor"],
+    );
+  });
+
+  it("highlights inside the directory when that is the field that matched", () => {
+    open();
+    type("dev/wor");
+    expect(rowNames()).toEqual(["worker"]);
+    expect(
+      [...document.querySelectorAll(".cmdbar-row-meta mark")].map((m) => m.textContent).join(""),
+    ).toBe("dev/wor");
+  });
+
+  it("renders a no-results state rather than an empty list", () => {
+    open();
+    type("zzz");
+    expect(rowNames()).toEqual([]);
+    expect(screen.getByText("No matches")).toBeDefined();
+  });
+
+  it("moves the highlight with the arrows and ctrl-p/ctrl-n, without wrapping", () => {
+    open();
+    press("ArrowUp");
+    expect(activeName()).toBe("api");
+    press("ArrowDown");
+    expect(activeName()).toBe("worker");
+    press("n", { ctrlKey: true });
+    expect(activeName()).toBe("notes");
+    press("ArrowDown");
+    expect(activeName()).toBe("notes");
+    press("p", { ctrlKey: true });
+    expect(activeName()).toBe("worker");
+  });
+
+  it("puts the highlight back on the best row whenever the query changes", () => {
+    open();
+    press("ArrowDown");
+    expect(activeName()).toBe("worker");
+    type("o");
+    expect(activeName()).toBe(rowNames()[0]);
+  });
+
+  it("opens the highlighted session through the caller's open path on Enter", () => {
+    const onOpenSession = vi.fn();
+    const onClose = vi.fn();
+    open({ onOpenSession, onClose });
+    press("ArrowDown");
+    press("Enter");
+    expect(onOpenSession).toHaveBeenCalledWith("worker");
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it("raises the shared select event when the caller supplies no handler", () => {
+    const listener = vi.fn();
+    document.addEventListener(SESSION_SELECT_EVENT, listener);
+    open({ onOpenSession: undefined });
+    press("Enter");
+    document.removeEventListener(SESSION_SELECT_EVENT, listener);
+    expect((listener.mock.calls[0][0] as CustomEvent).detail).toBe("api");
+  });
+
+  it("Enter on an empty result list does nothing", () => {
+    const onOpenSession = vi.fn();
+    const onClose = vi.fn();
+    open({ onOpenSession, onClose });
+    type("zzz");
+    press("Enter");
+    expect(onOpenSession).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("closes on Escape and on a press outside the panel", () => {
+    const onClose = vi.fn();
+    open({ onClose });
+    press("Escape");
+    expect(onClose).toHaveBeenCalledTimes(1);
+    fireEvent.mouseDown(document.querySelector(".cmdbar-overlay") as HTMLElement);
+    expect(onClose).toHaveBeenCalledTimes(2);
+  });
+
+  it("stays open for a press inside the panel", () => {
+    const onClose = vi.fn();
+    open({ onClose });
+    fireEvent.mouseDown(document.querySelector(".cmdbar-panel") as HTMLElement);
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("returns the keyboard to whatever held it when it opened", () => {
+    const before = document.createElement("input");
+    document.body.appendChild(before);
+    before.focus();
+    const view = open();
+    expect(document.activeElement).toBe(input());
+    view.unmount();
+    expect(document.activeElement).toBe(before);
+    before.remove();
+  });
+
+  it("clicking a row opens that session", () => {
+    const onOpenSession = vi.fn();
+    open({ onOpenSession });
+    fireEvent.click(document.querySelectorAll(".cmdbar-row")[1]);
+    expect(onOpenSession).toHaveBeenCalledWith("worker");
+  });
+});
+
+describe("the sigils", () => {
+  const commands = [
+    command({ id: "help.toggle", label: "Show help", keys: ["?"] }),
+    command({ id: "spawn.open", label: "Open the spawn form", keys: ["n"], run: vi.fn() }),
+  ];
+
+  it("lists every command in registry order under `>`, with its chord and no header", () => {
+    open({ commands });
+    type(">");
+    expect(rowNames()).toEqual(["Show help", "Open the spawn form"]);
+    expect(document.querySelectorAll(".cmdbar-group-title")).toHaveLength(0);
+    expect([...document.querySelectorAll(".cmdbar-row-keys kbd")].map((k) => k.textContent)).toEqual(
+      ["?", "n"],
+    );
+  });
+
+  it("matches a command on its label and never on its chord", () => {
+    open({ commands });
+    type(">help");
+    expect(rowNames()).toEqual(["Show help"]);
+    type(">?");
+    expect(rowNames()).toEqual([]);
+  });
+
+  it("runs the highlighted command on Enter", () => {
+    const run = vi.fn();
+    open({ commands: [command({ label: "Run me", run })] });
+    type(">run");
+    press("Enter");
+    expect(run).toHaveBeenCalled();
+  });
+
+  it("keeps the list mixed with no sigil, and returns to it when the sigil goes", () => {
+    open({ commands });
+    type(">show");
+    expect(rowNames()).toEqual(["Show help"]);
+    type("");
+    expect(rowNames()).toEqual(["api", "worker", "notes"]);
+  });
+
+  it("lists recent dirs then projects under `~`", async () => {
+    open({ loadDirectories: async () => ["/home/me/dev/api", "/srv/x"] });
+    type("~");
+    await waitFor(() => expect(rowNames()).toEqual(["~/dev/api", "/srv/x"]));
+    expect(document.querySelectorAll(".cmdbar-group-title")).toHaveLength(0);
+  });
+
+  it("fills the list in from /api/dirs as a path is typed", async () => {
+    const listDirEntries = vi.fn(async () => ["maestro", "api"]);
+    open({ loadDirectories: async () => ["/home/me/notes"], listDirEntries });
+    // The second `~` is a literal query character and reaches the matcher.
+    type("~~/dev/mae");
+    await waitFor(() => expect(rowNames()).toEqual(["~/dev/maestro"]));
+    expect(listDirEntries).toHaveBeenCalledWith("~/dev/");
+  });
+
+  it("spawns in the highlighted directory on Enter", async () => {
+    const onSpawnDirectory = vi.fn();
+    open({ loadDirectories: async () => ["/srv/x"], onSpawnDirectory });
+    type("~");
+    await waitFor(() => expect(rowNames()).toEqual(["/srv/x"]));
+    press("Enter");
+    expect(onSpawnDirectory).toHaveBeenCalledWith("/srv/x");
+  });
+
+  it("raises the spawn event when the caller supplies no handler", async () => {
+    const listener = vi.fn();
+    document.addEventListener(SPAWN_DIRECTORY_EVENT, listener);
+    open({ loadDirectories: async () => ["/srv/x"] });
+    type("~");
+    await waitFor(() => expect(rowNames()).toEqual(["/srv/x"]));
+    press("Enter");
+    document.removeEventListener(SPAWN_DIRECTORY_EVENT, listener);
+    expect((listener.mock.calls[0][0] as CustomEvent).detail).toBe("/srv/x");
+  });
+});
+
+describe("the session action page", () => {
+  function drill(over: Partial<CommandBarProps> = {}) {
+    const view = open(over);
+    press("Tab");
+    return view;
+  }
+
+  it("lists kill, rename and spawn similar for the highlighted session", () => {
+    drill();
+    expect(rowNames()).toEqual(["Kill session", "Rename session", "Spawn similar"]);
+  });
+
+  it("names the session being acted on", () => {
+    drill();
+    expect(screen.getByText('Actions for "api"')).toBeDefined();
+  });
+
+  it("drops the kind headers, since the page is one kind", () => {
+    drill();
+    expect(document.querySelectorAll(".cmdbar-group-title")).toHaveLength(0);
+  });
+
+  it("stays fuzzy-searchable over the three actions", () => {
+    drill();
+    type("ren");
+    expect(rowNames()).toEqual(["Rename session"]);
+  });
+
+  it("does nothing on a command row", () => {
+    open({ commands: [command({ label: "Show help" })] });
+    type(">show");
+    press("Tab");
+    expect(rowNames()).toEqual(["Show help"]);
+  });
+
+  it("does nothing on a directory row", async () => {
+    open({ loadDirectories: async () => ["/srv/x"] });
+    type("~");
+    await waitFor(() => expect(rowNames()).toEqual(["/srv/x"]));
+    press("Tab");
+    expect(rowNames()).toEqual(["/srv/x"]);
+  });
+
+  it("returns to the result list on Escape, with the previous query intact", () => {
+    const onClose = vi.fn();
+    open({ onClose });
+    type("wor");
+    press("Tab");
+    expect(rowNames()).toEqual(["Kill session", "Rename session", "Spawn similar"]);
+    press("Escape");
+    expect(onClose).not.toHaveBeenCalled();
+    expect(input().value).toBe("wor");
+    expect(rowNames()).toEqual(["worker"]);
+  });
+
+  it("returns to the result list on backspace at an empty query", () => {
+    drill();
+    fireEvent.keyDown(input(), { key: "Backspace" });
+    expect(rowNames()).toEqual(["api", "worker", "notes"]);
+  });
+
+  it("keeps backspace ordinary while the page's query has text", () => {
+    drill();
+    type("ren");
+    fireEvent.keyDown(input(), { key: "Backspace" });
+    expect(rowNames()).toEqual(["Rename session"]);
+  });
+
+  it("closes the bar when the page's Escape has already been used", () => {
+    const onClose = vi.fn();
+    drill({ onClose });
+    press("Escape");
+    press("Escape");
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("raises kill, rename and spawn similar with the session, closing the bar", () => {
+    for (const [query, key] of [
+      ["kill", "onKillSession"],
+      ["rename", "onRenameSession"],
+      ["spawn", "onSpawnSimilar"],
+    ] as const) {
+      const handler = vi.fn();
+      const onClose = vi.fn();
+      drill({ [key]: handler, onClose });
+      type(query);
+      press("Enter");
+      expect(handler).toHaveBeenCalledWith(expect.objectContaining({ id: "api" }));
+      expect(onClose).toHaveBeenCalled();
+      cleanup();
+    }
+  });
+
+  it("hands each action to the flow it already has, by default", () => {
+    for (const [query, event] of [
+      ["kill", KILL_SESSION_EVENT],
+      ["rename", RENAME_SESSION_EVENT],
+      ["spawn", SPAWN_SIMILAR_EVENT],
+    ] as const) {
+      const listener = vi.fn();
+      document.addEventListener(event, listener);
+      drill();
+      type(query);
+      press("Enter");
+      document.removeEventListener(event, listener);
+      expect((listener.mock.calls[0][0] as CustomEvent).detail.id).toBe("api");
+      cleanup();
+    }
+  });
+});

web/src/components/commandBar/CommandBar.tsx

@@ -0,0 +1,379 @@
+// The `ctrl-k` command bar (docs/COMMAND-BAR.md): a query line over a result
+// list. Sessions and commands rank together by default; `>` narrows to
+// commands, `~` to directories. `tab` on a session drills into its action page.
+//
+// The bar picks an action and hands off — it never reimplements one. Each
+// handler defaults to the event the flow that already implements it listens
+// on, so the React bar and the legacy shell raise the same flows.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+
+import {
+  KILL_SESSION_EVENT,
+  RENAME_SESSION_EVENT,
+  SESSION_SELECT_EVENT,
+  SPAWN_SIMILAR_EVENT,
+} from "../../catalog.js";
+import { publishedCommands, type Command } from "../../commands.js";
+import { sessionName, type Session } from "../../types.js";
+import { ActionPage } from "./ActionPage.js";
+import { ResultList } from "./ResultList.js";
+import {
+  barGroups,
+  barRows,
+  commandBarCandidates,
+  dirEntryPaths,
+  directoryBarCandidates,
+  isActionCandidate,
+  listDirEntries as defaultListDirEntries,
+  loadBarDirectories,
+  parseBarQuery,
+  probeDir,
+  sessionActionCandidates,
+  sessionBarCandidates,
+  PLACEHOLDERS,
+  type BarCandidate,
+  type BarResult,
+  type DirectoryBarCandidate,
+  type SessionAction,
+} from "./model.js";
+
+/** Raised when Enter lands on a directory row and no handler was given. The
+ *  bar picks the directory; the shell owns the spawn, which is the same
+ *  fast-forward path `N` takes. */
+export const SPAWN_DIRECTORY_EVENT = "cmdbar-spawn-directory";
+
+export interface CommandBarProps {
+  /** Sessions to build candidates from, as the store has them right now. */
+  sessions: readonly Session[];
+  /** The daemon's home dir, for the directory field's `~/…` abbreviation. */
+  homeDir?: string;
+  /** The command registry to list under `>`. Defaults to every bound command,
+   * in registry order. */
+  commands?: readonly Command[];
+  /** The directory list behind `~`, fetched once on first use. */
+  loadDirectories?: () => Promise<string[]>;
+  /** One directory's subdirectories, for filling the list in as a path is
+   * typed. Defaults to `GET /api/dirs`. */
+  listDirEntries?: (dir: string) => Promise<string[]>;
+  onOpenSession?(sessionId: string): void;
+  onSpawnDirectory?(path: string): void;
+  onKillSession?(session: Session): void;
+  onRenameSession?(session: Session): void;
+  onSpawnSimilar?(session: Session): void;
+  /** Closing returns the keyboard to whatever held it when the bar opened. */
+  onClose(): void;
+}
+
+function raise(name: string, detail: unknown): void {
+  document.dispatchEvent(new CustomEvent(name, { detail }));
+}
+
+export function CommandBar(props: CommandBarProps) {
+  const {
+    sessions,
+    homeDir,
+    commands,
+    loadDirectories = loadBarDirectories,
+    listDirEntries = defaultListDirEntries,
+    onClose,
+  } = props;
+
+  const inputRef = useRef<HTMLInputElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+
+  const [raw, setRaw] = useState("");
+  const [highlighted, setHighlighted] = useState(0);
+  // The action page: `page` is the session being acted on, `stashed` the
+  // result-list query it was drilled into from — backing out restores it, so
+  // the round trip costs the operator nothing.
+  const [page, setPage] = useState<Session | null>(null);
+  const [stashed, setStashed] = useState("");
+
+  // `~`'s candidates: the recents-and-projects list, fetched once, plus
+  // whatever `/api/dirs` has filled in for the directory being typed.
+  const [directories, setDirectories] = useState<DirectoryBarCandidate[]>([]);
+  const [probed, setProbed] = useState<DirectoryBarCandidate[]>([]);
+  const requestedRef = useRef(false);
+  const listingsRef = useRef(new Map<string, string[]>());
+
+  // On the action page the query line is over the three actions, so there is
+  // no sigil to read: `>` and `~` are ordinary characters there.
+  const parsed = useMemo(() => (page ? { sigil: null, query: raw } : parseBarQuery(raw)), [page, raw]);
+
+  const sessionCandidates = useMemo(
+    () => sessionBarCandidates(sessions, homeDir),
+    [sessions, homeDir],
+  );
+  const commandCandidates = useMemo(
+    () => commandBarCandidates(commands ?? publishedCommands()),
+    [commands],
+  );
+
+  // Closing returns the keyboard to whatever held it when the bar opened: a
+  // round trip through the bar never silently moves focus.
+  useEffect(() => {
+    const previouslyFocused = document.activeElement as HTMLElement | null;
+    inputRef.current?.focus();
+    return () => {
+      if (previouslyFocused?.isConnected) previouslyFocused.focus();
+    };
+  }, []);
+
+  // The recents-and-projects list, the first time `~` is used. No directories
+  // is a shorter list, not an error state.
+  useEffect(() => {
+    if (parsed.sigil !== "~" || requestedRef.current) return;
+    requestedRef.current = true;
+    let live = true;
+    loadDirectories()
+      .then((paths) => {
+        if (live) setDirectories(directoryBarCandidates(paths, homeDir));
+      })
+      .catch(() => {});
+    return () => {
+      live = false;
+    };
+  }, [parsed.sigil, loadDirectories, homeDir]);
+
+  // Fill the list in from `GET /api/dirs` once the query looks like a path: the
+  // directory it names is listed and its children join the candidates, so `~`
+  // reaches a directory that was never spawned in.
+  const dir = parsed.sigil === "~" ? probeDir(parsed.query) : "";
+  useEffect(() => {
+    if (dir === "") {
+      setProbed([]);
+      return;
+    }
+    const cached = listingsRef.current.get(dir);
+    if (cached) {
+      setProbed(directoryBarCandidates(dirEntryPaths(dir, cached), homeDir));
+      return;
+    }
+    let live = true;
+    setProbed([]);
+    listDirEntries(dir)
+      .then((entries) => {
+        listingsRef.current.set(dir, entries);
+        if (live) setProbed(directoryBarCandidates(dirEntryPaths(dir, entries), homeDir));
+      })
+      .catch(() => {
+        /* an unreadable directory contributes nothing */
+      });
+    return () => {
+      live = false;
+    };
+  }, [dir, listDirEntries, homeDir]);
+
+  /** What the matcher sees for the query line as it stands. With no sigil the
+   *  list is mixed — sessions and commands together — except on an empty query,
+   *  where the bar is a session switcher. */
+  const candidates: BarCandidate[] = useMemo(() => {
+    if (page) return sessionActionCandidates();
+    switch (parsed.sigil) {
+      case ">":
+        return [...commandCandidates];
+      case "~": {
+        const seen = new Set<string>();
+        return [...directories, ...probed].filter((c) =>
+          seen.has(c.path) ? false : (seen.add(c.path), true),
+        );
+      }
+      default:
+        return parsed.query === ""
+          ? [...sessionCandidates]
+          : [...sessionCandidates, ...commandCandidates];
+    }
+  }, [page, parsed.sigil, parsed.query, sessionCandidates, commandCandidates, directories, probed]);
+
+  const groups = useMemo(
+    () => barGroups(barRows(parsed.query, candidates)),
+    [parsed.query, candidates],
+  );
+  // Grouping is a rendering of the ranking, so the flattened groups are the
+  // rows in the order they appear — which is the order the highlight walks and
+  // Enter acts on.
+  const rows: BarResult[] = useMemo(() => groups.flatMap((g) => g.results), [groups]);
+
+  // The highlight starts on the globally best row every time the list changes:
+  // an old index would point at a different result.
+  useEffect(() => {
+    setHighlighted(0);
+  }, [rows]);
+
+  /** The highlight does not wrap: it stops at the first and last row. */
+  const move = useCallback(
+    (delta: number) => {
+      setHighlighted((at) => Math.min(rows.length - 1, Math.max(0, at + delta)));
+    },
+    [rows.length],
+  );
+
+  const runAction = useCallback(
+    (action: SessionAction, session: Session) => {
+      onClose();
+      switch (action.id) {
+        case "kill":
+          (props.onKillSession ?? ((s: Session) => raise(KILL_SESSION_EVENT, s)))(session);
+          return;
+        case "rename":
+          (props.onRenameSession ?? ((s: Session) => raise(RENAME_SESSION_EVENT, s)))(session);
+          return;
+        case "spawn-similar":
+          (props.onSpawnSimilar ?? ((s: Session) => raise(SPAWN_SIMILAR_EVENT, s)))(session);
+          return;
+      }
+    },
+    [onClose, props.onKillSession, props.onRenameSession, props.onSpawnSimilar],
+  );
+
+  const activate = useCallback(
+    (index: number) => {
+      const result = rows[index];
+      if (!result) return;
+      const candidate = result.candidate;
+      if (isActionCandidate(candidate)) {
+        // The page cannot be up without a session to act on.
+        if (page) runAction(candidate.action, page);
+        return;
+      }
+      onClose();
+      switch (candidate.kind) {
+        case "session":
+          (props.onOpenSession ?? ((id: string) => raise(SESSION_SELECT_EVENT, id)))(
+            candidate.session.id,
+          );
+          return;
+        case "command":
+          candidate.command.run();
+          return;
+        case "directory":
+          (props.onSpawnDirectory ?? ((p: string) => raise(SPAWN_DIRECTORY_EVENT, p)))(
+            candidate.path,
+          );
+          return;
+      }
+    },
+    [rows, page, runAction, onClose, props.onOpenSession, props.onSpawnDirectory],
+  );
+
+  /** `tab`: drill into the highlighted session's action page. No effect on any
+   *  other kind, and none on the page itself, which has no session rows. */
+  const drillIn = useCallback(() => {
+    const candidate = rows[highlighted]?.candidate;
+    if (page || candidate?.kind !== "session") return;
+    setPage(candidate.session);
+    setStashed(raw);
+    setRaw("");
+  }, [rows, highlighted, page, raw]);
+
+  /** Escape, or backspace at an empty query: back to the result list with the
+   *  query the drill-in was made from. */
+  const leavePage = useCallback(() => {
+    setPage(null);
+    setRaw(stashed);
+    setStashed("");
+  }, [stashed]);
+
+  const onKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    switch (e.key) {
+      case "Escape":
+        e.preventDefault();
+        // On an action page Escape is one level up, not the way out.
+        if (page) leavePage();
+        else onClose();
+        return;
+      case "Tab":
+        e.preventDefault();
+        drillIn();
+        return;
+      case "Backspace":
+        // Ordinary editing, except at an empty query on the action page.
+        if (page && raw === "") {
+          e.preventDefault();
+          leavePage();
+        }
+        return;
+      case "Enter":
+        e.preventDefault();
+        activate(highlighted);
+        return;
+      case "ArrowDown":
+        e.preventDefault();
+        move(1);
+        return;
+      case "ArrowUp":
+        e.preventDefault();
+        move(-1);
+        return;
+      case "n":
+        if (e.ctrlKey) {
+          e.preventDefault();
+          move(1);
+        }
+        return;
+      case "p":
+        if (e.ctrlKey) {
+          e.preventDefault();
+          move(-1);
+        }
+        return;
+    }
+  };
+
+  const activeRowId = rows.length > 0 ? `cmdbar-row-${highlighted}` : undefined;
+
+  return createPortal(
+    <div
+      className="cmdbar-overlay fixed inset-0 z-modal flex items-start justify-center bg-bg/70 pt-[12vh] backdrop-blur-sm max-[600px]:items-end max-[600px]:pt-0"
+      role="dialog"
+      aria-modal="true"
+      aria-label="Command bar"
+      onMouseDown={(e) => {
+        // A press on the scrim closes; one inside the panel is left alone.
+        if (!panelRef.current?.contains(e.target as Node)) onClose();
+      }}
+    >
+      <div
+        ref={panelRef}
+        className="cmdbar-panel flex w-full max-w-[560px] flex-col overflow-hidden rounded-r-3 border border-border bg-surface shadow-2 max-[600px]:max-w-none max-[600px]:rounded-b-none"
+      >
+        <input
+          ref={inputRef}
+          type="text"
+          role="combobox"
+          aria-expanded="true"
+          aria-controls="cmdbar-results"
+          aria-label="Search sessions, commands and directories"
+          aria-activedescendant={activeRowId}
+          autoComplete="off"
+          spellCheck={false}
+          className="cmdbar-input w-full border-b border-border bg-transparent px-sp-3 py-sp-2 text-fs-15 text-ink outline-none"
+          placeholder={page ? `Act on ${sessionName(page)}…` : PLACEHOLDERS[parsed.sigil ?? "mixed"]}
+          value={raw}
+          onChange={(e) => setRaw(e.currentTarget.value)}
+          onKeyDown={onKeyDown}
+        />
+        {page ? (
+          <ActionPage
+            session={page}
+            groups={groups}
+            highlighted={highlighted}
+            onActivate={activate}
+          />
+        ) : (
+          <ResultList
+            groups={groups}
+            // While a sigil is in force there is one kind, so the header is
+            // dropped.
+            showHeaders={parsed.sigil === null}
+            highlighted={highlighted}
+            onActivate={activate}
+          />
+        )}
+      </div>
+    </div>,
+    document.body,
+  );
+}

web/src/components/commandBar/ResultList.tsx

@@ -0,0 +1,171 @@
+// The bar's result list: kind headers over rank-ordered rows
+// (docs/COMMAND-BAR.md, "Structure"). Headers are labels, never rows — the
+// highlight walks the rows alone, in the order they are rendered.
+
+import { useEffect, useRef } from "react";
+
+import { keyCaps } from "../../commands.js";
+import {
+  highlightSegments,
+  isActionCandidate,
+  metaText,
+  rowName,
+  type BarGroup,
+  type BarResult,
+} from "./model.js";
+
+export interface ResultListProps {
+  groups: BarGroup[];
+  /** Dropped while a sigil is in force or on the action page: one kind needs
+   * no header. */
+  showHeaders: boolean;
+  /** Index into the flattened rows, in the order they render. */
+  highlighted: number;
+  onActivate(index: number): void;
+}
+
+function Highlighted({ text, ranges }: { text: string; ranges: BarResult["ranges"] }) {
+  return (
+    <>
+      {highlightSegments(text, ranges).map((segment, i) =>
+        segment.hit ? (
+          <mark key={i} className="cmdbar-hit bg-transparent font-semibold text-accent">
+            {segment.text}
+          </mark>
+        ) : (
+          <span key={i}>{segment.text}</span>
+        ),
+      )}
+    </>
+  );
+}
+
+function Row({
+  result,
+  index,
+  active,
+  onActivate,
+}: {
+  result: BarResult;
+  index: number;
+  active: boolean;
+  onActivate(index: number): void;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const candidate = result.candidate;
+
+  useEffect(() => {
+    if (active) ref.current?.scrollIntoView({ block: "nearest" });
+  }, [active]);
+
+  const name = rowName(candidate);
+  const nameMatched =
+    result.field === "name" || result.field === "label" || result.field === "path";
+  const meta = metaText(result);
+  const dead = candidate.kind === "session" && candidate.session.status === "Dead";
+  const chord =
+    candidate.kind === "command" && !isActionCandidate(candidate)
+      ? candidate.command.keys[0]
+      : undefined;
+
+  return (
+    <div
+      ref={ref}
+      role="option"
+      id={`cmdbar-row-${index}`}
+      aria-selected={active}
+      data-index={index}
+      data-kind={candidate.kind}
+      data-session-id={candidate.kind === "session" ? candidate.session.id : undefined}
+      data-action-id={isActionCandidate(candidate) ? candidate.action.id : undefined}
+      data-command-id={
+        candidate.kind === "command" && !isActionCandidate(candidate)
+          ? candidate.command.id
+          : undefined
+      }
+      data-path={candidate.kind === "directory" ? candidate.path : undefined}
+      className={[
+        "cmdbar-row flex cursor-pointer items-baseline gap-sp-2 rounded-r-1 px-sp-3 py-sp-1 text-fs-13",
+        active ? "is-active bg-surface-2 text-ink" : "text-ink",
+        dead ? "is-dead opacity-60" : "",
+      ]
+        .filter(Boolean)
+        .join(" ")}
+      onClick={() => onActivate(index)}
+    >
+      <span className="cmdbar-row-name truncate">
+        {nameMatched ? <Highlighted text={name} ranges={result.ranges} /> : name}
+      </span>
+      {chord !== undefined ? (
+        <span className="cmdbar-row-keys ml-auto flex gap-1">
+          {keyCaps(chord).map((cap, i) => (
+            <kbd
+              key={i}
+              className="rounded-r-1 border border-border px-1 text-fs-11 text-muted"
+            >
+              {cap}
+            </kbd>
+          ))}
+        </span>
+      ) : meta ? (
+        <span className="cmdbar-row-meta ml-auto truncate text-fs-11 text-muted">
+          {result.field !== undefined && result.field !== "name" ? (
+            <Highlighted text={meta} ranges={result.ranges} />
+          ) : (
+            meta
+          )}
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+export function ResultList({ groups, showHeaders, highlighted, onActivate }: ResultListProps) {
+  if (groups.length === 0) {
+    return (
+      <div
+        id="cmdbar-results"
+        role="listbox"
+        aria-label="Results"
+        className="cmdbar-results max-h-[50vh] overflow-auto p-sp-1"
+      >
+        <div className="cmdbar-empty px-sp-3 py-sp-2 text-fs-12 text-muted">No matches</div>
+      </div>
+    );
+  }
+
+  let index = 0;
+  return (
+    <div
+      id="cmdbar-results"
+      role="listbox"
+      aria-label="Results"
+      className="cmdbar-results max-h-[50vh] overflow-auto p-sp-1"
+    >
+      {groups.map((group) => (
+        <div key={group.kind}>
+          {showHeaders ? (
+            <div
+              role="presentation"
+              className="cmdbar-group-title px-sp-3 pt-sp-2 pb-1 text-fs-11 uppercase tracking-wide text-muted"
+            >
+              {group.title}
+            </div>
+          ) : null}
+          {group.results.map((result) => {
+            const at = index++;
+            return (
+              <Row
+                key={at}
+                result={result}
+                index={at}
+                active={at === highlighted}
+                onActivate={onActivate}
+              />
+            );
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}

web/src/components/commandBar/index.ts

@@ -0,0 +1,5 @@
+export { CommandBar, SPAWN_DIRECTORY_EVENT, type CommandBarProps } from "./CommandBar.js";
+export { ResultList, type ResultListProps } from "./ResultList.js";
+export { ActionPage, type ActionPageProps } from "./ActionPage.js";
+export { useCommandBar, type CommandBarControls, type UseCommandBarOptions } from "./useCommandBar.js";
+export * from "./model.js";

web/src/components/commandBar/model.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it } from "vitest";
+
+import type { Command } from "../../commands.js";
+import type { Session } from "../../types.js";
+import {
+  barGroups,
+  barRows,
+  commandBarCandidates,
+  dedupeCommands,
+  directoryBarCandidates,
+  directoryCandidate,
+  highlightSegments,
+  orderSessionsForBar,
+  parseBarQuery,
+  sessionActionCandidates,
+  sessionBarCandidates,
+  sessionCandidate,
+} from "./model.js";
+
+function session(id: string, over: Partial<Session> = {}): Session {
+  return {
+    id,
+    cwd: "/home/me/dev/api",
+    command: "bash",
+    env: {},
+    metadata: { name: id },
+    status: "Running",
+    created_at: "2026-01-01T00:00:00Z",
+    ...over,
+  };
+}
+
+function command(over: Partial<Command> = {}): Command {
+  return {
+    id: "a",
+    label: "A command",
+    group: "Test",
+    keys: ["a"],
+    scope: "global",
+    run: () => {},
+    ...over,
+  };
+}
+
+describe("empty-query ordering", () => {
+  it("sorts most recently focused first", () => {
+    const older = session("older", { last_focused_at: "2026-01-01T10:00:00Z" });
+    const newer = session("newer", { last_focused_at: "2026-01-01T11:00:00Z" });
+    expect(orderSessionsForBar([older, newer]).map((s) => s.id)).toEqual(["newer", "older"]);
+  });
+
+  it("sorts a never-focused session after every focused one, newest created first", () => {
+    const focused = session("focused", { last_focused_at: "2026-01-01T09:00:00Z" });
+    const old = session("old", { created_at: "2026-01-01T00:00:00Z" });
+    const fresh = session("fresh", { created_at: "2026-01-02T00:00:00Z" });
+    expect(orderSessionsForBar([old, fresh, focused]).map((s) => s.id)).toEqual([
+      "focused",
+      "fresh",
+      "old",
+    ]);
+  });
+
+  it("sorts dead sessions after live ones regardless of recency", () => {
+    const dead = session("dead", { status: "Dead", last_focused_at: "2026-01-01T12:00:00Z" });
+    const live = session("live", { last_focused_at: "2026-01-01T10:00:00Z" });
+    expect(orderSessionsForBar([dead, live]).map((s) => s.id)).toEqual(["live", "dead"]);
+  });
+
+  it("treats an empty last_focused_at as never focused", () => {
+    const blank = session("blank", { last_focused_at: "" });
+    const focused = session("focused", { last_focused_at: "2026-01-01T10:00:00Z" });
+    expect(orderSessionsForBar([blank, focused]).map((s) => s.id)).toEqual(["focused", "blank"]);
+  });
+});
+
+describe("session candidates", () => {
+  it("carries the candidate table's fields, with the directory abbreviated", () => {
+    const s = session("api", {
+      metadata: { name: "api" },
+      current_cwd: "/home/me/dev/api",
+      command: "claude --resume",
+    });
+    expect(sessionCandidate(s, "/home/me").fields).toEqual({
+      name: "api",
+      directory: "~/dev/api",
+      command: "claude --resume",
+      tool: "claude",
+    });
+  });
+
+  it("leaves the tool out when the program has no mark, and groups a worktree by its repo", () => {
+    const s = session("edit", {
+      metadata: {},
+      command: "hx src/",
+      worktree: { path: "/home/me/dev/api/wt/x", base_repo: "/home/me/dev/api" },
+    });
+    const candidate = sessionCandidate(s, "/home/me");
+    expect(candidate.fields.tool).toBeUndefined();
+    expect(candidate.fields.directory).toBe("~/dev/api");
+    // No `metadata.name`: the sidebar's fallback is the command line.
+    expect(candidate.fields.name).toBe("hx src/");
+  });
+
+  it("builds candidates in the empty-query order", () => {
+    const a = session("a", { last_focused_at: "2026-01-01T10:00:00Z" });
+    const b = session("b", { last_focused_at: "2026-01-01T11:00:00Z" });
+    expect(sessionBarCandidates([a, b]).map((c) => c.session.id)).toEqual(["b", "a"]);
+  });
+});
+
+describe("rows and grouping", () => {
+  it("an empty query keeps every candidate in input order", () => {
+    const candidates = sessionBarCandidates([session("a"), session("b")]);
+    expect(barRows("", candidates).map((r) => r.score)).toEqual([0, 0]);
+  });
+
+  it("groups by kind without reordering the ranking", () => {
+    const rows = barRows("kill", [
+      ...sessionBarCandidates([session("killer-app", { metadata: { name: "killer-app" } })]),
+      ...commandBarCandidates([command({ label: "Kill selected session" })]),
+    ]);
+    const groups = barGroups(rows);
+    expect(groups.map((g) => g.title)).toEqual(["Sessions", "Commands"]);
+    expect(groups.flatMap((g) => g.results)).toEqual(rows);
+  });
+});
+
+describe("parsing the query line", () => {
+  it("reads a sigil only in first position", () => {
+    expect(parseBarQuery(">help")).toEqual({ sigil: ">", query: "help" });
+    expect(parseBarQuery("~dev")).toEqual({ sigil: "~", query: "dev" });
+  });
+
+  it("leaves a sigil character elsewhere in the query literal", () => {
+    expect(parseBarQuery("~dev/~scratch")).toEqual({ sigil: "~", query: "dev/~scratch" });
+    expect(parseBarQuery("a>b")).toEqual({ sigil: null, query: "a>b" });
+  });
+
+  it("returns to the mixed list when the sigil is backspaced away", () => {
+    expect(parseBarQuery("")).toEqual({ sigil: null, query: "" });
+  });
+});
+
+describe("command candidates", () => {
+  it("dedupes by action, not by chord", () => {
+    const run = () => {};
+    const cmds = [
+      command({ id: "one", label: "Do it", keys: ["j"], run }),
+      command({ id: "two", label: "Do it", keys: ["down"], run }),
+    ];
+    expect(commandBarCandidates(cmds)).toHaveLength(1);
+    expect(dedupeCommands(cmds)).toHaveLength(1);
+  });
+
+  it("matches on the label only, never on the chord", () => {
+    const candidates = commandBarCandidates([command({ label: "Show help", keys: ["ctrl-q"] })]);
+    expect(barRows("ctrlq", candidates)).toEqual([]);
+    expect(barRows("show", candidates)).toHaveLength(1);
+  });
+});
+
+describe("directory candidates", () => {
+  it("abbreviates the path it shows and keeps the one it spawns in", () => {
+    const candidate = directoryCandidate("/home/me/dev/api", "/home/me");
+    expect(candidate.fields.path).toBe("~/dev/api");
+    expect(candidate.path).toBe("/home/me/dev/api");
+  });
+
+  it("expands a typed `~` and dedupes by the directory spawned in", () => {
+    const candidates = directoryBarCandidates(
+      ["~/dev/api", "/home/me/dev/api", "", "/srv/x"],
+      "/home/me",
+    );
+    expect(candidates.map((c) => c.path)).toEqual(["/home/me/dev/api", "/srv/x"]);
+  });
+});
+
+describe("the action page's candidates", () => {
+  it("offers no action beyond the three", () => {
+    expect(sessionActionCandidates().map((c) => c.action.id)).toEqual([
+      "kill",
+      "rename",
+      "spawn-similar",
+    ]);
+  });
+});
+
+describe("highlight segments", () => {
+  it("splits the text on the matcher's ranges", () => {
+    expect(highlightSegments("web-search", [[0, 1], [4, 5]])).toEqual([
+      { text: "w", hit: true },
+      { text: "eb-", hit: false },
+      { text: "s", hit: true },
+      { text: "earch", hit: false },
+    ]);
+  });
+});

web/src/components/commandBar/model.ts

@@ -0,0 +1,366 @@
+// The command bar's pure model (docs/COMMAND-BAR.md), lifted from
+// ../../commandBar.ts for the React port (#247): what a candidate is, the
+// order an empty query lists them in, how a query line splits into a sigil and
+// a query, and how a ranked list groups for rendering.
+//
+// Nothing here touches the DOM or the network apart from `loadBarDirectories`,
+// which is the one place the `~` list comes from.
+
+import { listDir, projects as fetchProjects, recentDirs } from "../../api.js";
+import type { Command } from "../../commands.js";
+import { splitPath } from "../../paths.js";
+import { splitCommand } from "../../toolIcon.js";
+import { abbreviateCwd, sessionName, sessionTreePath, type Session } from "../../types.js";
+import {
+  matchAndRank,
+  type CandidateKind,
+  type CommandCandidate,
+  type DirectoryCandidate,
+  type MatchRange,
+  type MatchResult,
+  type SessionCandidate,
+} from "../../utils/matcher.js";
+
+/** A matcher candidate that remembers what it came from, so a result can be
+ *  acted on without a second lookup. The extra property is invisible to the
+ *  matcher, which only ever reads `kind` and `fields`. */
+export type SessionBarCandidate = SessionCandidate & { session: Session };
+export type CommandBarCandidate = CommandCandidate & { command: Command };
+/** `fields.path` is the abbreviated path the operator reads and the matcher
+ *  ranks; `path` is the one a spawn is made in. */
+export type DirectoryBarCandidate = DirectoryCandidate & { path: string };
+
+/** One row of a session's action page. It is a `command` to the matcher — a
+ *  single `label` field, ranked exactly like a registry command — and carries
+ *  the action it stands for instead of a registry entry. */
+export type ActionBarCandidate = CommandCandidate & { action: SessionAction };
+
+export type BarCandidate =
+  | SessionBarCandidate
+  | CommandBarCandidate
+  | ActionBarCandidate
+  | DirectoryBarCandidate;
+export type BarResult = MatchResult<BarCandidate>;
+
+/** One kind's slice of the ranked list, in rank order. */
+export interface BarGroup<C extends BarCandidate = BarCandidate> {
+  kind: CandidateKind;
+  title: string;
+  results: MatchResult<C>[];
+}
+
+const KIND_TITLES: Record<CandidateKind, string> = {
+  session: "Sessions",
+  command: "Commands",
+  directory: "Directories",
+};
+
+// ---- the sigils ----
+
+export type BarSigil = ">" | "~";
+
+export interface BarQuery {
+  /** The sigil in force, or null for the mixed list. */
+  sigil: BarSigil | null;
+  /** What the matcher sees: everything after a sigil, or the whole query. */
+  query: string;
+}
+
+export const PLACEHOLDERS: Record<"mixed" | BarSigil, string> = {
+  mixed: "Go to a session…",
+  ">": "Run a command…",
+  "~": "Spawn in a directory…",
+};
+
+/** Split a raw query line into its sigil and the query proper.
+ *
+ *  A sigil is only a sigil in first position: `>` or `~` anywhere else is a
+ *  literal query character, which is what a directory query with a second `~`
+ *  in it depends on. Backspacing past a sigil needs no special case either —
+ *  the first character goes and the query is a mixed one again. */
+export function parseBarQuery(raw: string): BarQuery {
+  const first = raw[0];
+  if (first === ">" || first === "~") return { sigil: first, query: raw.slice(1) };
+  return { sigil: null, query: raw };
+}
+
+// ---- the session action page ----
+
+/** The actions a session's action page offers, and no others: the bar picks
+ *  one and hands off to the flow that already implements it
+ *  (docs/COMMAND-BAR.md, "Drill-in"). */
+export type SessionActionId = "kill" | "rename" | "spawn-similar";
+
+export interface SessionAction {
+  id: SessionActionId;
+  label: string;
+}
+
+export const SESSION_ACTIONS: readonly SessionAction[] = [
+  { id: "kill", label: "Kill session" },
+  { id: "rename", label: "Rename session" },
+  { id: "spawn-similar", label: "Spawn similar" },
+];
+
+/** The action page's candidates, in the order above — which is the order an
+ *  empty query lists them in, since the matcher keeps input order. */
+export function sessionActionCandidates(): ActionBarCandidate[] {
+  return SESSION_ACTIONS.map((action) => ({
+    kind: "command",
+    action,
+    fields: { label: action.label },
+  }));
+}
+
+/** Narrow a `command` candidate to an action row. Both share the matcher's
+ *  `command` kind, so what separates them is what they carry. */
+export function isActionCandidate(candidate: BarCandidate): candidate is ActionBarCandidate {
+  return candidate.kind === "command" && "action" in candidate;
+}
+
+// ---- candidates ----
+
+function focusedAt(s: Session): number | null {
+  const stamp = s.last_focused_at;
+  if (typeof stamp !== "string" || stamp === "") return null;
+  const ms = Date.parse(stamp);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+function createdAt(s: Session): number {
+  const ms = Date.parse(s.created_at ?? "");
+  return Number.isNaN(ms) ? 0 : ms;
+}
+
+/** The empty-query order (docs/COMMAND-BAR.md, "Empty query"): most recently
+ *  focused first; a session that has never been focused sorts after every
+ *  session that has, most recently created first among those; and a dead
+ *  session sorts after every live one regardless of recency, because a session
+ *  you cannot attach to is not where you just were.
+ *
+ *  This is also the input order for a non-empty query, which is what the
+ *  matcher's last tie-break preserves. */
+export function orderSessionsForBar(sessions: readonly Session[]): Session[] {
+  return [...sessions].sort((a, b) => {
+    const deadA = a.status === "Dead" ? 1 : 0;
+    const deadB = b.status === "Dead" ? 1 : 0;
+    if (deadA !== deadB) return deadA - deadB;
+
+    const focusA = focusedAt(a);
+    const focusB = focusedAt(b);
+    if ((focusA === null) !== (focusB === null)) return focusA === null ? 1 : -1;
+    if (focusA !== null && focusB !== null && focusA !== focusB) return focusB - focusA;
+
+    return createdAt(b) - createdAt(a);
+  });
+}
+
+/** Build one session's candidate: the fields docs/COMMAND-BAR.md's candidate
+ *  table names, with the directory abbreviated the way the sidebar shows it. */
+export function sessionCandidate(s: Session, homeDir?: string): SessionBarCandidate {
+  const treePath = sessionTreePath(s);
+  const directory = treePath ? abbreviateCwd(treePath, homeDir) : undefined;
+  const tool = splitCommand(s.command).tool ?? undefined;
+  return {
+    kind: "session",
+    session: s,
+    fields: {
+      name: sessionName(s),
+      ...(directory ? { directory } : {}),
+      ...(s.command ? { command: s.command } : {}),
+      ...(tool ? { tool } : {}),
+    },
+  };
+}
+
+/** Every session as a candidate, in the empty-query order. */
+export function sessionBarCandidates(
+  sessions: readonly Session[],
+  homeDir?: string,
+): SessionBarCandidate[] {
+  return orderSessionsForBar(sessions).map((s) => sessionCandidate(s, homeDir));
+}
+
+/** Drop the commands that would list twice. Several chords can be bound to one
+ *  action — the registry already carries its aliases on one entry, but nothing
+ *  stops two entries running the same handler, and listed naively that is two
+ *  identical rows. The dedupe is by **action**, never by chord: the chord is
+ *  displayed, so a command with two of them is still one row. */
+export function dedupeCommands(commands: readonly Command[]): Command[] {
+  const seenRun = new Set<Command["run"]>();
+  const seenLabel = new Set<string>();
+  const kept: Command[] = [];
+  for (const command of commands) {
+    if (seenRun.has(command.run) || seenLabel.has(command.label)) continue;
+    seenRun.add(command.run);
+    seenLabel.add(command.label);
+    kept.push(command);
+  }
+  return kept;
+}
+
+/** Every bound command as a candidate, in registry order. Only the label is a
+ *  field: the chord is displayed beside the row, never matched, because
+ *  matching it would make `>` results depend on a user's rebinds. */
+export function commandBarCandidates(commands: readonly Command[]): CommandBarCandidate[] {
+  return dedupeCommands(commands).map((command) => ({
+    kind: "command",
+    command,
+    fields: { label: command.label },
+  }));
+}
+
+/** `~/dev/api` back to `/home/me/dev/api` — the inverse of `abbreviateCwd`, for
+ *  a path the operator typed or `/api/dirs` completed. */
+export function expandHome(path: string, homeDir?: string): string {
+  if (!homeDir) return path;
+  if (path === "~") return homeDir;
+  return path.startsWith("~/") ? `${homeDir}${path.slice(1)}` : path;
+}
+
+export function directoryCandidate(path: string, homeDir?: string): DirectoryBarCandidate {
+  const absolute = expandHome(path, homeDir);
+  return { kind: "directory", path: absolute, fields: { path: abbreviateCwd(absolute, homeDir) } };
+}
+
+/** Candidates for `~`, deduped by the directory they spawn in and keeping the
+ *  first mention of each — recent dirs (newest first) ahead of the project
+ *  list, which is the empty-query order the contract asks for. */
+export function directoryBarCandidates(
+  paths: readonly string[],
+  homeDir?: string,
+): DirectoryBarCandidate[] {
+  const seen = new Set<string>();
+  const out: DirectoryBarCandidate[] = [];
+  for (const path of paths) {
+    if (path === "") continue;
+    const candidate = directoryCandidate(path, homeDir);
+    if (seen.has(candidate.path)) continue;
+    seen.add(candidate.path);
+    out.push(candidate);
+  }
+  return out;
+}
+
+/** The directory list the bar starts from: what the spawn form already knows —
+ *  `GET /api/recent-dirs` and the project list — either alone if the other
+ *  fails. */
+export async function loadBarDirectories(): Promise<string[]> {
+  const [recents, discovered] = await Promise.all([
+    recentDirs()
+      .then((r) => r.dirs.map((d) => d.cwd))
+      .catch(() => [] as string[]),
+    fetchProjects()
+      .then((list) => list.map((p) => p.path))
+      .catch(() => [] as string[]),
+  ]);
+  return [...recents, ...discovered];
+}
+
+/** One directory's children as candidate paths, for filling the `~` list in as
+ *  a path is typed. The directory being listed comes from the query itself. */
+export function dirEntryPaths(dir: string, entries: readonly string[]): string[] {
+  return entries.map((entry) => `${dir}${entry}`);
+}
+
+/** The directory a `~` query names, or `""` when it names none yet. */
+export function probeDir(query: string): string {
+  return splitPath(query).dir;
+}
+
+/** `GET /api/dirs`, in the shape the bar wants it. */
+export function listDirEntries(dir: string): Promise<string[]> {
+  return listDir(dir).then((listing) => listing.entries);
+}
+
+// ---- grouping ----
+
+/** Bucket a ranked list by kind for rendering. Grouping is a rendering of the
+ *  ranking, never a reordering of it: a group holds its matches in rank order,
+ *  and groups appear in the order their best-scoring member does — so the first
+ *  row under the first header is the globally best result. */
+export function barGroups<C extends BarCandidate>(
+  results: readonly MatchResult<C>[],
+): BarGroup<C>[] {
+  const groups: BarGroup<C>[] = [];
+  for (const result of results) {
+    const kind = result.candidate.kind;
+    let group = groups.find((g) => g.kind === kind);
+    if (!group) {
+      group = { kind, title: KIND_TITLES[kind], results: [] };
+      groups.push(group);
+    }
+    group.results.push(result);
+  }
+  return groups;
+}
+
+/** The rows a query produces, flat and in rank order — what the highlight walks
+ *  and what Enter acts on. Headers are labels, not rows, so they are never in
+ *  this list. */
+export function barRows<C extends BarCandidate>(
+  query: string,
+  candidates: readonly C[],
+): MatchResult<C>[] {
+  return matchAndRank(query, candidates);
+}
+
+// ---- row text ----
+
+/** The name line of a row: the session's name, the command's label, or the
+ *  directory's path. */
+export function rowName(candidate: BarCandidate): string {
+  switch (candidate.kind) {
+    case "session":
+      return candidate.fields.name;
+    case "command":
+      return candidate.fields.label;
+    case "directory":
+      return candidate.fields.path;
+  }
+}
+
+/** The secondary line under a session row: the field the match was found in
+ *  when that was not the name, so a session found through its directory says
+ *  so. Only sessions have one — a command shows keycaps instead, and a
+ *  directory's path is already the name. */
+export function metaText(result: BarResult): string | undefined {
+  if (result.candidate.kind !== "session") return undefined;
+  const fields = result.candidate.fields;
+  switch (result.field) {
+    case "directory":
+      return fields.directory;
+    case "command":
+      return fields.command;
+    case "tool":
+      return fields.tool;
+    default:
+      return fields.directory;
+  }
+}
+
+/** One run of a row's text, flagged when the matcher matched inside it. The
+ *  React rendering of `renderHighlighted`: ranges come from the matcher as
+ *  `[start, end)` character pairs over the field that won. */
+export interface HighlightSegment {
+  text: string;
+  hit: boolean;
+}
+
+export function highlightSegments(
+  text: string,
+  ranges: readonly MatchRange[],
+): HighlightSegment[] {
+  const out: HighlightSegment[] = [];
+  let cursor = 0;
+  for (const [start, end] of ranges) {
+    if (start > cursor) out.push({ text: text.slice(cursor, start), hit: false });
+    out.push({ text: text.slice(start, end), hit: true });
+    cursor = end;
+  }
+  if (cursor < text.length) out.push({ text: text.slice(cursor), hit: false });
+  return out;
+}
+
+export { sessionName };
+export type { CandidateKind, MatchRange, MatchResult };

web/src/components/commandBar/useCommandBar.test.tsx

@@ -0,0 +1,76 @@
+// @vitest-environment happy-dom
+import { act, cleanup, render } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { OPEN_COMMAND_BAR_EVENT } from "../../catalog.js";
+import { useCommandBar, type UseCommandBarOptions } from "./useCommandBar.js";
+
+let controls: ReturnType<typeof useCommandBar>;
+
+function Probe(opts: UseCommandBarOptions) {
+  controls = useCommandBar(opts);
+  return <div>{controls.open ? "open" : "closed"}</div>;
+}
+
+function ctrlK(target: EventTarget = window): void {
+  act(() => {
+    target.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "k", ctrlKey: true, bubbles: true, cancelable: true }),
+    );
+  });
+}
+
+afterEach(cleanup);
+
+describe("useCommandBar", () => {
+  it("opens on ctrl-k, from the capture phase so an attached xterm never sees it", () => {
+    const view = render(<Probe />);
+    ctrlK();
+    expect(view.container.textContent).toBe("open");
+  });
+
+  it("stays deaf while the bar is already up — its own input owns the keys", () => {
+    const onOpen = vi.fn();
+    render(<Probe onOpen={onOpen} />);
+    ctrlK();
+    ctrlK();
+    expect(onOpen).toHaveBeenCalledTimes(1);
+  });
+
+  it("leaves a form field's own Ctrl-K alone", () => {
+    const field = document.createElement("input");
+    document.body.appendChild(field);
+    const view = render(<Probe />);
+    ctrlK(field);
+    expect(view.container.textContent).toBe("closed");
+    field.remove();
+  });
+
+  it("opens from the sidebar's search field, the touch entry point", () => {
+    const view = render(<Probe />);
+    act(() => {
+      document.dispatchEvent(new CustomEvent(OPEN_COMMAND_BAR_EVENT));
+    });
+    expect(view.container.textContent).toBe("open");
+  });
+
+  it("runs the caller's hook before opening, so a preview is discarded first", () => {
+    const onOpen = vi.fn();
+    render(<Probe onOpen={onOpen} />);
+    ctrlK();
+    expect(onOpen).toHaveBeenCalledTimes(1);
+  });
+
+  it("closes on demand", () => {
+    const view = render(<Probe />);
+    ctrlK();
+    act(() => controls.closeBar());
+    expect(view.container.textContent).toBe("closed");
+  });
+
+  it("binds nothing while disabled — another overlay owns the keyboard", () => {
+    const view = render(<Probe enabled={false} />);
+    ctrlK();
+    expect(view.container.textContent).toBe("closed");
+  });
+});

web/src/components/commandBar/useCommandBar.ts

@@ -0,0 +1,65 @@
+// Opening and closing the bar (docs/COMMAND-BAR.md, "Opening"). `ctrl-k` is a
+// registry command like any other, so the `?` overlay lists it without a
+// second list; the touch entry point — the sidebar's search field — raises
+// `OPEN_COMMAND_BAR_EVENT` and lands on the same open.
+
+import { useCallback, useEffect, useState } from "react";
+
+import { OPEN_COMMAND_BAR_EVENT } from "../../catalog.js";
+import { CommandSet, defineCommands, isBarTypingTarget } from "../../commands.js";
+
+export interface UseCommandBarOptions {
+  /** Run before the bar opens — the shell discards a preview here, since the
+   * bar is not previewed into (docs/PREVIEW.md). */
+  onOpen?(): void;
+  /** Off while another overlay owns the keyboard (the restart overlay, the
+   * help dialog). Defaults to on. */
+  enabled?: boolean;
+}
+
+export interface CommandBarControls {
+  open: boolean;
+  openBar(): void;
+  closeBar(): void;
+}
+
+export function useCommandBar(opts: UseCommandBarOptions = {}): CommandBarControls {
+  const { onOpen, enabled = true } = opts;
+  const [open, setOpen] = useState(false);
+
+  const openBar = useCallback(() => {
+    onOpen?.();
+    setOpen(true);
+  }, [onOpen]);
+
+  const closeBar = useCallback(() => setOpen(false), []);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const keys = new CommandSet(defineCommands({ "bar.open": openBar }));
+
+    // Capture phase: an attached xterm swallows every keystroke it is given, so
+    // the bar's binding has to be seen ahead of the terminal.
+    const onKeydown = (e: KeyboardEvent) => {
+      // The bar owns the keyboard while it is up; its own input handles the keys.
+      if (open) return;
+      // The pane's hidden textarea is not a typing target for the bar: ctrl-k
+      // is seen ahead of xterm and opens the bar. A real form field — the spawn
+      // form's inputs — keeps its own Ctrl+K.
+      if (isBarTypingTarget(e.target)) return;
+      keys.handle(e);
+    };
+    const onTouchEntry = () => {
+      if (!open) openBar();
+    };
+
+    window.addEventListener("keydown", onKeydown, true);
+    document.addEventListener(OPEN_COMMAND_BAR_EVENT, onTouchEntry);
+    return () => {
+      window.removeEventListener("keydown", onKeydown, true);
+      document.removeEventListener(OPEN_COMMAND_BAR_EVENT, onTouchEntry);
+    };
+  }, [enabled, open, openBar]);
+
+  return { open, openBar, closeBar };
+}

web/src/components/spawn/BranchPicker.test.tsx

@@ -0,0 +1,79 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { BranchInfo } from "../../types.js";
+import { BranchPicker, type BranchPickerProps } from "./BranchPicker.js";
+
+afterEach(cleanup);
+
+function props(over: Partial<BranchPickerProps> = {}): BranchPickerProps {
+  return {
+    enabled: true,
+    onToggleEnabled: vi.fn(),
+    hint: null,
+    baseRepo: "/repo",
+    mode: "new",
+    onModeChange: vi.fn(),
+    newBranch: "",
+    onNewBranchChange: vi.fn(),
+    branches: undefined,
+    existingBranch: "",
+    onExistingBranchChange: vi.fn(),
+    ...over,
+  };
+}
+
+describe("BranchPicker", () => {
+  it("shows the hint instead of the body while unresolved", () => {
+    render(<BranchPicker {...props({ hint: "Choose a working directory first." })} />);
+    expect(screen.getByText("Choose a working directory first.")).not.toBeNull();
+    expect(screen.queryByText("New branch name")).toBeNull();
+  });
+
+  it("shows the new-branch field by default and the repo line once resolved", () => {
+    render(<BranchPicker {...props()} />);
+    expect(screen.getByText("repo: /repo")).not.toBeNull();
+    expect(screen.getByPlaceholderText("feat/foo")).not.toBeNull();
+    expect(screen.queryByText("Pick a branch")).toBeNull();
+  });
+
+  it("switches to the existing-branch select and reports the mode change", () => {
+    const onModeChange = vi.fn();
+    render(<BranchPicker {...props({ onModeChange })} />);
+
+    fireEvent.click(screen.getByLabelText("Existing branch"));
+
+    expect(onModeChange).toHaveBeenCalledWith("existing");
+  });
+
+  it("disables a branch already held by another worktree, and the main checkout's HEAD", () => {
+    const branches: BranchInfo[] = [
+      { name: "main", is_head: true },
+      { name: "feat/a", is_head: false, worktree: "/repos/a" },
+      { name: "feat/b", is_head: false },
+    ];
+    render(<BranchPicker {...props({ mode: "existing", branches })} />);
+
+    const main = screen.getByRole("option", { name: /main — held by the main checkout/ }) as HTMLOptionElement;
+    const a = screen.getByRole("option", { name: /feat\/a — held by \/repos\/a/ }) as HTMLOptionElement;
+    const b = screen.getByRole("option", { name: "feat/b" }) as HTMLOptionElement;
+    expect(main.disabled).toBe(true);
+    expect(a.disabled).toBe(true);
+    expect(b.disabled).toBe(false);
+  });
+
+  it("shows a placeholder option when no local branches were found", () => {
+    render(<BranchPicker {...props({ mode: "existing", branches: [] })} />);
+    expect(screen.getByText("No local branches found.")).not.toBeNull();
+  });
+
+  it("toggles the worktree checkbox", () => {
+    const onToggleEnabled = vi.fn();
+    render(<BranchPicker {...props({ onToggleEnabled })} />);
+
+    fireEvent.click(screen.getByLabelText("Create git worktree"));
+
+    expect(onToggleEnabled).toHaveBeenCalledWith(false);
+  });
+});

web/src/components/spawn/BranchPicker.tsx

@@ -0,0 +1,119 @@
+// The spawn form's worktree section (#61): create-worktree toggle, then
+// (once a base repo is known) new-branch-vs-existing-branch, mirroring
+// spawnForm.ts's `.adv-group`/`.wt-body`/`.wt-mode` markup.
+
+import type { BranchInfo } from "../../types.js";
+import type { WorktreeBranchMode } from "../../spawnForm.js";
+
+export interface BranchPickerProps {
+  enabled: boolean;
+  onToggleEnabled(enabled: boolean): void;
+  /** Status line shown in place of the body — "Checking…", "not a repo",
+   * "choose a directory first". `null` once the body itself can render. */
+  hint: string | null;
+  /** The repo a worktree would branch from, once resolved. */
+  baseRepo: string | null;
+  mode: WorktreeBranchMode;
+  onModeChange(mode: WorktreeBranchMode): void;
+  newBranch: string;
+  onNewBranchChange(value: string): void;
+  /** This cwd's local branches, or `undefined` while unknown/not yet loaded. */
+  branches: BranchInfo[] | undefined;
+  existingBranch: string;
+  onExistingBranchChange(value: string): void;
+}
+
+export function BranchPicker(props: BranchPickerProps) {
+  return (
+    <div
+      className={`flex flex-col gap-sp-3 border-l-2 pl-sp-3 ${
+        props.enabled ? "border-accent" : "border-border"
+      }`}
+    >
+      <label className="flex cursor-pointer items-center gap-sp-2 text-fs-14 text-ink">
+        <input
+          type="checkbox"
+          data-role="toggle"
+          className="size-[18px] accent-accent"
+          checked={props.enabled}
+          onChange={(e) => props.onToggleEnabled(e.currentTarget.checked)}
+        />
+        Create git worktree
+      </label>
+
+      {props.hint && <p className="m-0 text-fs-12 text-muted">{props.hint}</p>}
+
+      {props.enabled && !props.hint && (
+        <div className="flex flex-col gap-sp-3">
+          {props.baseRepo && (
+            <p className="m-0 font-mono text-fs-12 text-muted">repo: {props.baseRepo}</p>
+          )}
+          <div role="radiogroup" aria-label="Branch source" className="flex gap-sp-4">
+            <label className="flex cursor-pointer items-center gap-sp-2 text-fs-14 text-ink">
+              <input
+                type="radio"
+                name="worktree_branch_mode"
+                checked={props.mode === "new"}
+                onChange={() => props.onModeChange("new")}
+              />
+              New branch
+            </label>
+            <label className="flex cursor-pointer items-center gap-sp-2 text-fs-14 text-ink">
+              <input
+                type="radio"
+                name="worktree_branch_mode"
+                checked={props.mode === "existing"}
+                onChange={() => props.onModeChange("existing")}
+              />
+              Existing branch
+            </label>
+          </div>
+
+          {props.mode === "new" ? (
+            <label className="flex flex-col gap-1 text-fs-12 text-muted">
+              New branch name
+              <input
+                name="worktree_branch"
+                type="text"
+                autoComplete="off"
+                placeholder="feat/foo"
+                className="w-full rounded-r-2 border border-border bg-surface-2 px-sp-3 py-2 font-mono text-fs-15 text-ink"
+                value={props.newBranch}
+                onChange={(e) => props.onNewBranchChange(e.currentTarget.value)}
+              />
+            </label>
+          ) : (
+            <label className="flex flex-col gap-1 text-fs-12 text-muted">
+              Pick a branch
+              <select
+                className="w-full rounded-r-2 border border-border bg-surface-2 px-sp-3 py-2 font-mono text-fs-15 text-ink"
+                value={props.existingBranch}
+                onChange={(e) => props.onExistingBranchChange(e.currentTarget.value)}
+              >
+                {branchOptions(props.branches)}
+              </select>
+            </label>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function branchOptions(branches: BranchInfo[] | undefined) {
+  if (!branches || branches.length === 0) {
+    return <option value="">No local branches found.</option>;
+  }
+  return branches.map((b) => {
+    // A branch already checked out anywhere stays visible but unpickable —
+    // git refuses a second checkout. That includes the main checkout's own
+    // HEAD, which is commonly `main` and would otherwise be the default pick,
+    // making every existing-branch spawn fail (#54 review).
+    const held = b.worktree ?? (b.is_head ? "the main checkout" : null);
+    return (
+      <option key={b.name} value={b.name} disabled={held !== null} title={held ?? ""}>
+        {held ? `${b.name} — held by ${held}` : b.name}
+      </option>
+    );
+  });
+}

web/src/components/spawn/DirAutocomplete.test.tsx

@@ -0,0 +1,109 @@
+// @vitest-environment happy-dom
+import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { useState } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { DirAutocomplete } from "./DirAutocomplete.js";
+
+vi.mock("../../api.js", () => ({
+  listDir: vi.fn(),
+}));
+
+import { listDir } from "../../api.js";
+
+const mockListDir = vi.mocked(listDir);
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+function Harness({ initial = "" }: { initial?: string }) {
+  const [value, setValue] = useState(initial);
+  return <DirAutocomplete value={value} onChange={setValue} placeholder="cwd" />;
+}
+
+// `fireEvent.focus`/`.blur` dispatch the event without moving the browser's
+// real focus, so `document.activeElement` (which the dropdown's fetch guards
+// against) never changes — calling the DOM method directly does both.
+function focus(el: HTMLElement): void {
+  act(() => el.focus());
+}
+function blur(el: HTMLElement): void {
+  act(() => el.blur());
+}
+
+describe("DirAutocomplete", () => {
+  it("lists entries matching the trailing segment on focus", async () => {
+    mockListDir.mockResolvedValue({ path: "/home/n", entries: ["alpha", "beta"] });
+    render(<Harness initial="/home/n/al" />);
+
+    focus(screen.getByPlaceholderText("cwd"));
+
+    expect(await screen.findByRole("option", { name: "alpha/" })).not.toBeNull();
+    expect(screen.queryByRole("option", { name: "beta/" })).toBeNull();
+  });
+
+  it("Tab commits the highlighted entry and does not close the field", async () => {
+    mockListDir.mockResolvedValue({ path: "/home/n", entries: ["alpha"] });
+    render(<Harness initial="/home/n/a" />);
+    const input = screen.getByPlaceholderText("cwd") as HTMLInputElement;
+    focus(input);
+    await screen.findByRole("option", { name: "alpha/" });
+
+    fireEvent.keyDown(input, { key: "Tab" });
+
+    expect(input.value).toBe("/home/n/alpha/");
+  });
+
+  it("arrows move the highlight and Enter accepts it without submitting", async () => {
+    mockListDir.mockResolvedValue({ path: "/home/n", entries: ["alpha", "beta"] });
+    render(<Harness initial="/home/n/" />);
+    const input = screen.getByPlaceholderText("cwd") as HTMLInputElement;
+    focus(input);
+    await screen.findByRole("option", { name: "alpha/" });
+
+    fireEvent.keyDown(input, { key: "ArrowDown" });
+    const notPrevented = fireEvent.keyDown(input, { key: "Enter" });
+
+    expect(input.value).toBe("/home/n/beta/");
+    expect(notPrevented).toBe(false); // preventDefault called -> event "processed"
+  });
+
+  it("Escape closes the dropdown and stops the key from bubbling", async () => {
+    mockListDir.mockResolvedValue({ path: "/home/n", entries: ["alpha"] });
+    const onKeyDown = vi.fn();
+    render(
+      <div onKeyDown={onKeyDown}>
+        <Harness initial="/home/n/a" />
+      </div>,
+    );
+    const input = screen.getByPlaceholderText("cwd");
+    focus(input);
+    await screen.findByRole("option", { name: "alpha/" });
+
+    fireEvent.keyDown(input, { key: "Escape" });
+
+    await waitFor(() => expect(screen.queryByRole("option")).toBeNull());
+    expect(onKeyDown).not.toHaveBeenCalled();
+  });
+
+  it("does not reopen on refocus until the operator types again", async () => {
+    mockListDir.mockResolvedValue({ path: "/home/n", entries: ["alpha"] });
+    render(<Harness initial="/home/n/a" />);
+    const input = screen.getByPlaceholderText("cwd");
+    focus(input);
+    await screen.findByRole("option", { name: "alpha/" });
+    fireEvent.keyDown(input, { key: "Escape" });
+    await waitFor(() => expect(screen.queryByRole("option")).toBeNull());
+
+    blur(input);
+    focus(input);
+
+    await new Promise((r) => setTimeout(r, 10));
+    expect(screen.queryByRole("option")).toBeNull();
+
+    fireEvent.change(input, { target: { value: "/home/n/al" } });
+    expect(await screen.findByRole("option", { name: "alpha/" })).not.toBeNull();
+  });
+});

web/src/components/spawn/DirAutocomplete.tsx

@@ -0,0 +1,256 @@
+// React port of ../../dirAutocomplete.ts: shell-style directory autocomplete
+// on a path <input>. Lists one directory at a time over `GET /api/dirs`,
+// caches per directory, and filters the trailing path segment locally.
+//
+// Keyboard model mirrors `cd dir/sub<tab>`:
+//   Tab    commit the highlighted entry and let focus move on; with nothing
+//          highlighted, plain tab navigation
+//   ↑/↓    move the highlight
+//   Enter  accept the highlighted entry (and suppress form submit); with
+//          nothing highlighted, bubble to the form unprevented
+//   Esc    close the dropdown, refocus the input, and stop the key from
+//          bubbling — so dismissing the popup can't also close a parent modal
+//
+// Once dismissed (Esc or blur) the popup stays closed until the operator
+// types again — refocusing alone doesn't reopen it.
+
+import { useCallback, useEffect, useRef, useState, type InputHTMLAttributes, type Ref } from "react";
+import { createPortal } from "react-dom";
+
+import { listDir } from "../../api.js";
+import { splitPath } from "../../paths.js";
+
+/** Most entries rendered at once — a long list is unhelpful and slow. */
+const MAX_VISIBLE = 60;
+/** Debounce before a network fetch when the input crosses into a new directory. */
+const FETCH_DEBOUNCE_MS = 90;
+
+export interface DirAutocompleteProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "onChange"> {
+  value: string;
+  onChange(value: string): void;
+  /** Access to the underlying `<input>` — e.g. to focus/select it. */
+  inputRef?: Ref<HTMLInputElement>;
+}
+
+function assignRef(ref: Ref<HTMLInputElement> | undefined, el: HTMLInputElement | null): void {
+  if (!ref) return;
+  if (typeof ref === "function") ref(el);
+  else (ref as { current: HTMLInputElement | null }).current = el;
+}
+
+export function DirAutocomplete({ value, onChange, inputRef, ...inputProps }: DirAutocompleteProps) {
+  const localRef = useRef<HTMLInputElement | null>(null);
+  const cache = useRef(new Map<string, string[]>());
+  const fetchSeq = useRef(0);
+  const debounceTimer = useRef<number | undefined>(undefined);
+  const dismissedRef = useRef(false);
+
+  const [filtered, setFiltered] = useState<string[]>([]);
+  const [highlight, setHighlight] = useState(-1);
+  const [open, setOpen] = useState(false);
+  const [rect, setRect] = useState<{ left: number; top: number; width: number } | null>(null);
+
+  const setInputRef = useCallback(
+    (el: HTMLInputElement | null) => {
+      localRef.current = el;
+      assignRef(inputRef, el);
+    },
+    [inputRef],
+  );
+
+  const reposition = useCallback(() => {
+    const el = localRef.current;
+    if (!el) return;
+    const r = el.getBoundingClientRect();
+    setRect({ left: r.left, top: r.bottom + 4, width: r.width });
+  }, []);
+
+  const close = useCallback(() => {
+    setOpen(false);
+    setFiltered([]);
+    setHighlight(-1);
+  }, []);
+
+  const dismiss = useCallback(() => {
+    dismissedRef.current = true;
+    close();
+  }, [close]);
+
+  const applyFilter = useCallback(
+    (entries: string[], prefix: string) => {
+      // A fetch can outlive the dismissal it was meant to serve (Tab-commit
+      // re-arms a refresh, then blur dismisses 120ms later). Showing it now
+      // would anchor a dropdown under an unfocused input nothing closes.
+      if (dismissedRef.current || document.activeElement !== localRef.current) {
+        close();
+        return;
+      }
+      const lower = prefix.toLowerCase();
+      const next = entries.filter((e) => e.toLowerCase().startsWith(lower));
+      setFiltered(next);
+      setHighlight(next.length > 0 ? 0 : -1);
+      if (next.length === 0) {
+        close();
+        return;
+      }
+      setOpen(true);
+      reposition();
+    },
+    [close, reposition],
+  );
+
+  const refresh = useCallback(
+    (raw: string) => {
+      const { dir, prefix } = splitPath(raw);
+      const cached = cache.current.get(dir);
+      if (cached) {
+        applyFilter(cached, prefix);
+        return;
+      }
+      const seq = ++fetchSeq.current;
+      listDir(dir)
+        .then((listing) => {
+          cache.current.set(dir, listing.entries);
+          if (seq !== fetchSeq.current) return; // a newer fetch superseded this one
+          const cur = splitPath(localRef.current?.value ?? raw);
+          if (cur.dir === dir) applyFilter(listing.entries, cur.prefix);
+        })
+        .catch(() => {
+          if (seq === fetchSeq.current) close();
+        });
+    },
+    [applyFilter, close],
+  );
+
+  const scheduleRefresh = useCallback(
+    (raw: string) => {
+      window.clearTimeout(debounceTimer.current);
+      debounceTimer.current = window.setTimeout(() => refresh(raw), FETCH_DEBOUNCE_MS);
+    },
+    [refresh],
+  );
+
+  /** Complete `name` as the next path segment and append `/` so the child
+   * directory's listing loads on the next interaction — the drill-in
+   * gesture. Unlike `accept`, doesn't steal focus: Tab uses this to commit
+   * and move to the next field in one gesture. */
+  const commit = useCallback(
+    (name: string) => {
+      const { dir } = splitPath(value);
+      onChange(`${dir}${name}/`);
+    },
+    [value, onChange],
+  );
+
+  const accept = useCallback(
+    (name: string) => {
+      commit(name);
+      localRef.current?.focus();
+    },
+    [commit],
+  );
+
+  useEffect(() => {
+    if (!open) return;
+    window.addEventListener("scroll", reposition, true);
+    window.addEventListener("resize", reposition);
+    return () => {
+      window.removeEventListener("scroll", reposition, true);
+      window.removeEventListener("resize", reposition);
+    };
+  }, [open, reposition]);
+
+  useEffect(() => () => window.clearTimeout(debounceTimer.current), []);
+
+  return (
+    <>
+      <input
+        {...inputProps}
+        ref={setInputRef}
+        value={value}
+        autoComplete="off"
+        role="combobox"
+        aria-expanded={open}
+        aria-autocomplete="list"
+        onChange={(e) => {
+          dismissedRef.current = false;
+          const next = e.currentTarget.value;
+          onChange(next);
+          scheduleRefresh(next);
+        }}
+        onFocus={(e) => {
+          inputProps.onFocus?.(e);
+          if (dismissedRef.current) return;
+          refresh(value);
+        }}
+        onBlur={(e) => {
+          inputProps.onBlur?.(e);
+          // Delay so a dropdown mousedown can complete first.
+          window.setTimeout(dismiss, 120);
+        }}
+        onKeyDown={(e) => {
+          inputProps.onKeyDown?.(e);
+          if (e.defaultPrevented) return;
+          if (e.key === "Escape") {
+            if (open) {
+              e.preventDefault();
+              e.stopPropagation();
+              dismiss();
+              localRef.current?.focus();
+            }
+            return;
+          }
+          if (e.key === "Tab") {
+            if (!open || highlight < 0 || highlight >= filtered.length) return; // plain tab navigation
+            commit(filtered[highlight]); // no preventDefault — focus moves to the next field
+            return;
+          }
+          if (!open) return;
+          if (e.key === "ArrowDown") {
+            e.preventDefault();
+            setHighlight((h) => Math.min(h + 1, filtered.length - 1));
+          } else if (e.key === "ArrowUp") {
+            e.preventDefault();
+            setHighlight((h) => Math.max(h - 1, 0));
+          } else if (e.key === "Enter" && highlight >= 0 && highlight < filtered.length) {
+            e.preventDefault(); // accept the entry instead of submitting the form
+            accept(filtered[highlight]);
+          }
+        }}
+      />
+      {open &&
+        rect &&
+        createPortal(
+          <ul
+            role="listbox"
+            className="dir-ac fixed z-modal max-h-[240px] overflow-y-auto rounded-r-2 border border-border-strong bg-surface py-sp-1 font-mono shadow-2"
+            style={{ left: rect.left, top: rect.top, width: rect.width }}
+          >
+            {filtered.slice(0, MAX_VISIBLE).map((name, i) => (
+              <li
+                key={name}
+                role="option"
+                aria-selected={i === highlight}
+                className={`cursor-pointer truncate px-sp-3 py-1 text-fs-12 text-ink ${
+                  i === highlight ? "bg-accent-tint" : ""
+                }`}
+                onMouseDown={(e) => {
+                  e.preventDefault(); // accept before the input's blur fires
+                  accept(name);
+                }}
+              >
+                {name}/
+              </li>
+            ))}
+            {filtered.length > MAX_VISIBLE && (
+              <li className="px-sp-3 py-1 text-fs-11 text-faint">
+                +{filtered.length - MAX_VISIBLE} more — keep typing to narrow
+              </li>
+            )}
+          </ul>,
+          document.body,
+        )}
+    </>
+  );
+}

web/src/components/spawn/SpawnForm.test.tsx

@@ -0,0 +1,383 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { BranchInfo, DaemonInfo, Project, Session, SpawnPreset } from "../../types.js";
+import { SpawnForm } from "./SpawnForm.js";
+
+vi.mock("../../api.js", () => ({
+  createSession: vi.fn(),
+  fetchBranches: vi.fn(),
+  fetchNames: vi.fn(),
+  getDaemonInfo: vi.fn(),
+  gitRoot: vi.fn(),
+  listDir: vi.fn(),
+  projects: vi.fn(),
+}));
+
+import {
+  createSession,
+  fetchBranches,
+  fetchNames,
+  getDaemonInfo,
+  gitRoot,
+  listDir,
+  projects as fetchProjects,
+} from "../../api.js";
+
+const mockCreateSession = vi.mocked(createSession);
+const mockFetchBranches = vi.mocked(fetchBranches);
+const mockFetchNames = vi.mocked(fetchNames);
+const mockGetDaemonInfo = vi.mocked(getDaemonInfo);
+const mockGitRoot = vi.mocked(gitRoot);
+const mockListDir = vi.mocked(listDir);
+const mockFetchProjects = vi.mocked(fetchProjects);
+
+const presets: SpawnPreset[] = [
+  { id: "claude", label: "Claude", command: "claude" },
+  { id: "opencode", label: "opencode", command: "opencode" },
+  { id: "zsh", label: "Shell", command: "zsh" },
+  { id: "custom", label: "Custom…", command: "" },
+];
+
+function info(over: Partial<DaemonInfo> = {}): DaemonInfo {
+  return { hostname: "h", version: "1", home_dir: "/home/n", presets, ...over };
+}
+
+function project(over: Partial<Project> = {}): Project {
+  return { path: "/repos/p", name: "p", last_activity: new Date().toISOString(), ...over };
+}
+
+function session(over: Partial<Session> = {}): Session {
+  return {
+    id: "s1",
+    cwd: "/repos/p",
+    command: "claude",
+    env: {},
+    metadata: {},
+    status: "Running",
+    created_at: "2026-01-01T00:00:00Z",
+    ...over,
+  };
+}
+
+/** Defaults every test starts from: one known project, no branches, a fresh
+ * generated handle. Individual tests override what they care about. */
+function stub(over: { projects?: Project[]; info?: DaemonInfo; names?: string[]; branches?: BranchInfo[] } = {}) {
+  mockGetDaemonInfo.mockResolvedValue(over.info ?? info());
+  mockFetchProjects.mockResolvedValue(over.projects ?? [project()]);
+  mockFetchNames.mockResolvedValue({ names: over.names ?? ["amber-fox"] });
+  mockFetchBranches.mockResolvedValue(over.branches ?? []);
+  mockGitRoot.mockResolvedValue({});
+  mockListDir.mockResolvedValue({ path: "", entries: [] });
+}
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+async function settle() {
+  await waitFor(() => expect(screen.queryByText("Loading projects…")).toBeNull());
+}
+
+/** Everything worktree/name/structured-related lives behind the "Advanced"
+ * disclosure, collapsed by default (#93) — mirrors the vanilla form exactly. */
+function openAdvanced() {
+  fireEvent.click(screen.getByRole("button", { name: /Advanced/ }));
+}
+
+describe("SpawnForm harness picker", () => {
+  it("selects the first non-custom preset by default and reveals the custom input on Custom…", async () => {
+    stub();
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+
+    expect(screen.getByRole("button", { name: /^Claude/ }).className).toContain("border-accent");
+    fireEvent.click(screen.getByRole("button", { name: "Custom…" }));
+
+    expect(screen.getByPlaceholderText("bash -l").hidden).toBe(false);
+  });
+
+  it("resolves a seeded command to its matching preset", async () => {
+    stub();
+    render(<SpawnForm seed={{ command: "opencode" }} onSuccess={vi.fn()} />);
+    await settle();
+
+    const opencode = screen.getByRole("button", { name: /opencode/ });
+    expect(opencode.className).toContain("border-accent");
+  });
+
+  it("drops an unmatched seeded command into the custom field", async () => {
+    stub();
+    render(<SpawnForm seed={{ command: "hx src/" }} onSuccess={vi.fn()} />);
+    await settle();
+
+    const raw = screen.getByPlaceholderText("bash -l") as HTMLInputElement;
+    expect(raw.hidden).toBe(false);
+    expect(raw.value).toBe("hx src/");
+  });
+});
+
+describe("SpawnForm project picker", () => {
+  it("lists discovered projects and reveals the worktree step on pick", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" }), project({ path: "/repos/b", name: "b" })] });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+
+    expect(screen.queryByText("Worktree")).toBeNull();
+    fireEvent.click(screen.getByText("a"));
+
+    expect(screen.getByText("Worktree")).not.toBeNull();
+    expect(screen.getByText("+ new").closest("button")?.getAttribute("data-active")).toBe("true");
+  });
+
+  it("filters the project grid by name", async () => {
+    stub({ projects: [project({ path: "/repos/alpha", name: "alpha" }), project({ path: "/repos/beta", name: "beta" })] });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+
+    fireEvent.change(screen.getByPlaceholderText("Filter projects…"), { target: { value: "alp" } });
+
+    expect(screen.getByText("alpha")).not.toBeNull();
+    expect(screen.queryByText("beta")).toBeNull();
+  });
+
+  it("falls back to the raw directory input when no projects are discovered", async () => {
+    stub({ projects: [] });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+
+    expect((screen.getByPlaceholderText("/home/user/project") as HTMLInputElement).value).toBe("/home/n");
+  });
+
+  it("Other directory… clears the picker and opens the raw input", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" })] });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    fireEvent.click(screen.getByText("a"));
+    expect(screen.getByText("a").closest("button")?.getAttribute("data-active")).toBe("true");
+
+    fireEvent.click(screen.getByText("Other directory…"));
+
+    expect(screen.getByText("a").closest("button")?.getAttribute("data-active")).toBeNull();
+    expect((screen.getByPlaceholderText("/home/user/project") as HTMLInputElement).value).toBe("/repos/a");
+  });
+});
+
+describe("SpawnForm worktree defaults", () => {
+  it("defaults the toggle on for a picked project and infers the repo without a gitroot probe", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" })] });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+
+    fireEvent.click(screen.getByText("a"));
+
+    expect(screen.getByText("repo: /repos/a")).not.toBeNull();
+    expect(mockGitRoot).not.toHaveBeenCalled();
+  });
+
+  it("defaults the toggle off for a project that is itself a worktree (#91)", async () => {
+    stub({
+      projects: [
+        project({ path: "/repos/main", name: "main" }),
+        project({ path: "/repos/wt", name: "wt", is_worktree: true, base_repo: "/repos/main" }),
+      ],
+    });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+
+    fireEvent.click(screen.getByText("main"));
+    fireEvent.click(screen.getByText("wt"));
+
+    expect((screen.getByLabelText("Create git worktree") as HTMLInputElement).checked).toBe(false);
+  });
+
+  it("still probes gitroot for a free-text directory", async () => {
+    stub();
+    mockGitRoot.mockResolvedValue({ root: "/repos/found" });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+    fireEvent.click(screen.getByText("Other directory…"));
+
+    fireEvent.change(screen.getByPlaceholderText("/home/user/project"), {
+      target: { value: "/repos/found/sub" },
+    });
+
+    await waitFor(() => expect(mockGitRoot).toHaveBeenCalledWith("/repos/found/sub"));
+    expect(await screen.findByText("repo: /repos/found")).not.toBeNull();
+  });
+
+  it("populates existing branches, disabling the one held by another worktree", async () => {
+    stub({
+      projects: [project({ path: "/repos/a", name: "a" })],
+      branches: [
+        { name: "main", is_head: true },
+        { name: "feat/x", is_head: false, worktree: "/repos/other" },
+        { name: "feat/y", is_head: false },
+      ],
+    });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+    fireEvent.click(screen.getByText("a"));
+
+    fireEvent.click(screen.getByLabelText("Existing branch"));
+
+    const y = await screen.findByRole("option", { name: "feat/y" });
+    expect((y as HTMLOptionElement).disabled).toBe(false);
+    expect((screen.getByRole("option", { name: /main — held by the main checkout/ }) as HTMLOptionElement).disabled).toBe(
+      true,
+    );
+  });
+
+  it("submits the first pickable branch when the operator never opens the select", async () => {
+    stub({
+      projects: [project({ path: "/repos/a", name: "a" })],
+      branches: [
+        { name: "main", is_head: true },
+        { name: "feat/y", is_head: false },
+      ],
+    });
+    mockCreateSession.mockResolvedValue(session());
+    const onSuccess = vi.fn();
+    render(<SpawnForm onSuccess={onSuccess} />);
+    await settle();
+    openAdvanced();
+    fireEvent.click(screen.getByText("a"));
+    fireEvent.click(screen.getByLabelText("Existing branch"));
+    await screen.findByRole("option", { name: "feat/y" });
+
+    fireEvent.click(screen.getByRole("button", { name: "Spawn" }));
+
+    await waitFor(() => expect(onSuccess).toHaveBeenCalled());
+    expect(mockCreateSession).toHaveBeenCalledWith(
+      expect.objectContaining({ worktree: expect.objectContaining({ branch: "feat/y", create_branch: false }) }),
+    );
+  });
+});
+
+describe("SpawnForm structured view", () => {
+  it("defaults on for a resolved Claude Code command and off for an unsupported one", async () => {
+    stub();
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+
+    expect((screen.getByLabelText("Structured view") as HTMLInputElement).checked).toBe(true);
+
+    fireEvent.click(screen.getByRole("button", { name: /^Shell/ }));
+
+    expect(screen.queryByLabelText("Structured view")).toBeNull();
+  });
+
+  it("keeps an unchecked box unchecked across a command change between two supported tools", async () => {
+    stub();
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+    fireEvent.click(screen.getByLabelText("Structured view"));
+
+    fireEvent.click(screen.getByRole("button", { name: /opencode/ }));
+    fireEvent.click(screen.getByRole("button", { name: /^Claude/ }));
+
+    expect((screen.getByLabelText("Structured view") as HTMLInputElement).checked).toBe(false);
+  });
+});
+
+describe("SpawnForm submit", () => {
+  it("builds and posts the request, reporting the created session", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" })] });
+    const created = session();
+    mockCreateSession.mockResolvedValue(created);
+    const onSuccess = vi.fn();
+    render(<SpawnForm onSuccess={onSuccess} />);
+    await settle();
+    fireEvent.click(screen.getByText("a"));
+
+    fireEvent.click(screen.getByRole("button", { name: "Spawn" }));
+
+    await waitFor(() => expect(onSuccess).toHaveBeenCalledWith(created));
+    expect(mockCreateSession).toHaveBeenCalledWith(
+      expect.objectContaining({ cwd: "/repos/a", command: "claude" }),
+    );
+  });
+
+  it("shows the daemon's rejection and leaves the form open", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" })] });
+    mockCreateSession.mockRejectedValue(new Error("cwd is not a directory"));
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    fireEvent.click(screen.getByText("a"));
+
+    fireEvent.click(screen.getByRole("button", { name: "Spawn" }));
+
+    expect(await screen.findByText("cwd is not a directory")).not.toBeNull();
+  });
+
+  it("rejects an existing-branch worktree with nothing picked", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" })], branches: [] });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+    fireEvent.click(screen.getByText("a"));
+    fireEvent.click(screen.getByLabelText("Existing branch"));
+    await screen.findByText("No local branches found.");
+
+    fireEvent.click(screen.getByRole("button", { name: "Spawn" }));
+
+    expect(await screen.findByText("Pick an existing branch.")).not.toBeNull();
+    expect(mockCreateSession).not.toHaveBeenCalled();
+  });
+});
+
+describe("SpawnForm Enter-to-submit (#97)", () => {
+  it("submits from the session name field", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" })] });
+    mockCreateSession.mockResolvedValue(session());
+    const onSuccess = vi.fn();
+    render(<SpawnForm onSuccess={onSuccess} />);
+    await settle();
+    fireEvent.click(screen.getByText("a"));
+    openAdvanced();
+
+    fireEvent.keyDown(screen.getByPlaceholderText("named after your first prompt"), { key: "Enter" });
+
+    await waitFor(() => expect(onSuccess).toHaveBeenCalled());
+  });
+
+  it("first Enter picks a not-yet-active project box, the second submits", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" }), project({ path: "/repos/b", name: "b" })] });
+    mockCreateSession.mockResolvedValue(session());
+    const onSuccess = vi.fn();
+    render(<SpawnForm onSuccess={onSuccess} />);
+    await settle();
+
+    const boxB = screen.getByText("b").closest("button")!;
+    fireEvent.keyDown(boxB, { key: "Enter" });
+    expect(onSuccess).not.toHaveBeenCalled();
+    expect(boxB.getAttribute("data-active")).toBe("true");
+
+    fireEvent.keyDown(boxB, { key: "Enter" });
+    await waitFor(() => expect(onSuccess).toHaveBeenCalled());
+  });
+
+  it("toggles the worktree checkbox on Enter instead of submitting", async () => {
+    stub({ projects: [project({ path: "/repos/a", name: "a" })] });
+    render(<SpawnForm onSuccess={vi.fn()} />);
+    await settle();
+    openAdvanced();
+    fireEvent.click(screen.getByText("a"));
+    const checkbox = screen.getByLabelText("Create git worktree") as HTMLInputElement;
+    expect(checkbox.checked).toBe(true);
+
+    fireEvent.keyDown(checkbox, { key: "Enter" });
+
+    expect(checkbox.checked).toBe(false);
+    expect(mockCreateSession).not.toHaveBeenCalled();
+  });
+});

web/src/components/spawn/SpawnForm.tsx

@@ -0,0 +1,853 @@
+// React port of ../../spawnForm.ts: the spawn form itself — preset tiles,
+// two-step project picker, name, structured-view checkbox, worktree. Mounted
+// inside SpawnModal.
+//
+// Working-directory picker (#95), unchanged from the vanilla form:
+//  1. Step one is one box per repository (name, then its parent directory).
+//     A worktree is a box only when its main checkout is missing from the
+//     scan.
+//  2. The filter keeps a repository when the query matches it or any of its
+//     worktrees.
+//  3. Picking a box reveals step two: "+ new", then that repository's
+//     worktrees newest-first. "Other directory…" clears both steps.
+//  4. "+ new" is the default selection — except on a box that is itself a
+//     linked worktree, which defaults to that worktree.
+//  5. "+ new" means create: cwd is the repository, create-worktree on. An
+//     existing worktree means run in it: cwd is that worktree, create-worktree
+//     off (the daemon never adopts, docs/WORKTREES.md).
+//  6. Neither step probes /api/gitroot; only the free-text hatch does.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import {
+  createSession,
+  fetchBranches,
+  fetchNames,
+  getDaemonInfo,
+  gitRoot,
+  projects as fetchProjects,
+} from "../../api.js";
+import { parentDir } from "../../paths.js";
+import {
+  filterProjects,
+  groupProjects,
+  isStale,
+  sortProjects,
+  type ProjectGroup,
+} from "../../projectList.js";
+import {
+  buildSpawnRequest,
+  FALLBACK_PRESETS,
+  supportsStructuredView,
+  type SpawnFormSeed,
+  type SpawnFormValues,
+  type WorktreeBranchMode,
+} from "../../spawnForm.js";
+import { splitCommand, toolIconSvg, TOOL_LABELS } from "../../toolIcon.js";
+import { abbreviateCwd } from "../../types.js";
+import type { BranchInfo, Project, Session, SpawnPreset } from "../../types.js";
+import { BranchPicker } from "./BranchPicker.js";
+import { DirAutocomplete } from "./DirAutocomplete.js";
+
+/** Quiet period after raw-path typing before `/api/gitroot` fires (#74). Must
+ * stay equal to `GITROOT_PROBE_DEBOUNCE_MS` in crates/maestro-tui/src/draft.rs
+ * and to ../../spawnForm.ts's own constant, so every client debounces alike. */
+const GITROOT_PROBE_DEBOUNCE_MS = 250;
+
+/** "new" (create a worktree) or the path of an existing worktree to run in. */
+type WorktreeChoice = "new" | string;
+
+type BaseRepoResolution =
+  | { kind: "disabled" }
+  | { kind: "no-cwd" }
+  | { kind: "found"; repo: string }
+  | { kind: "probe" };
+
+function resolveBaseRepoFor(cwd: string, wtEnabled: boolean, discovered: Project[]): BaseRepoResolution {
+  if (!wtEnabled) return { kind: "disabled" };
+  if (!cwd) return { kind: "no-cwd" };
+  const project = discovered.find((p) => p.path === cwd);
+  if (project) return { kind: "found", repo: project.base_repo ?? project.path };
+  return { kind: "probe" };
+}
+
+/** Every worktree of a group, including the group's own box when the scan
+ * found no main checkout to nest it under. */
+function worktreesOf(group: ProjectGroup): Project[] {
+  return [group.main, ...group.worktrees].filter((p) => p.is_worktree);
+}
+
+/** Resolve a preset id to a tool icon id — the preset's command is the source
+ * of truth, the same way the sidebar derives one. The "Custom…" preset (empty
+ * command) has no tool to show. */
+function presetToolId(p: SpawnPreset): string | null {
+  if (!p.command) return null;
+  return splitCommand(p.command).tool;
+}
+
+function harnessIcon(toolId: string): string | null {
+  const small = toolIconSvg(toolId);
+  if (!small) return null;
+  // toolIconSvg renders at 13x13 (viewBox 0 0 16 16) for the sidebar; the
+  // harness card wants the same mark at 24x24 so it breathes.
+  return small.replace(/width="13"/g, 'width="24"').replace(/height="13"/g, 'height="24"');
+}
+
+function pickerButtonClass(active: boolean): string {
+  return `flex min-h-[32px] items-baseline justify-between gap-sp-3 rounded-r-2 border px-sp-3 py-1.5 text-left font-mono ${
+    active ? "border-accent bg-accent-tint" : "border-border bg-surface-2 hover:border-border-strong"
+  }`;
+}
+
+export interface SpawnFormProps {
+  seed?: SpawnFormSeed;
+  /** Fired whenever any value changes, once the form's initial seed settles. */
+  onChange?(values: SpawnFormValues): void;
+  onSuccess(session: Session): void;
+}
+
+export function SpawnForm({ seed, onChange, onSuccess }: SpawnFormProps) {
+  const prefill = useRef(seed ?? {}).current;
+
+  const formRef = useRef<HTMLFormElement>(null);
+  const filterInputRef = useRef<HTMLInputElement>(null);
+  const customCommandRef = useRef<HTMLInputElement>(null);
+  const rawCwdRef = useRef<HTMLInputElement>(null);
+  const destroyedRef = useRef(false);
+  useEffect(() => () => {
+    destroyedRef.current = true;
+  }, []);
+
+  // ---- harness / command -------------------------------------------------
+  const [homeDir, setHomeDir] = useState("");
+  const [infoLoading, setInfoLoading] = useState(true);
+  const [presets, setPresets] = useState<SpawnPreset[]>(FALLBACK_PRESETS);
+  const [selectedPresetId, setSelectedPresetId] = useState("");
+  const [command, setCommand] = useState("");
+  const [customCommand, setCustomCommand] = useState("");
+  const [commandTouched, setCommandTouched] = useState(false);
+  const [structuredView, setStructuredView] = useState(false);
+  const [structuredTouched, setStructuredTouched] = useState(false);
+
+  const activePreset = useMemo(() => presets.find((p) => p.id === selectedPresetId), [presets, selectedPresetId]);
+  const isCustomSelected = !activePreset || activePreset.command === "";
+
+  useEffect(() => {
+    if (commandTouched && isCustomSelected) customCommandRef.current?.focus();
+  }, [isCustomSelected, commandTouched]);
+
+  useEffect(() => {
+    let cancelled = false;
+    getDaemonInfo()
+      .then((info) => {
+        if (cancelled) return;
+        setHomeDir(info.home_dir ?? "");
+        if (info.presets?.length) setPresets(info.presets);
+      })
+      .catch(() => {
+        // keep fallbacks
+      })
+      .finally(() => {
+        if (!cancelled) setInfoLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // Pick a sensible starting command whenever the preset list changes and the
+  // operator hasn't touched it yet: a seed's command (matched to a preset, or
+  // dropped into custom), else the first non-custom preset.
+  useEffect(() => {
+    if (commandTouched) return;
+    const wanted = prefill.command;
+    if (wanted) {
+      const match = presets.find((p) => p.command === wanted && p.command !== "");
+      if (match) {
+        setSelectedPresetId(match.id);
+        setCommand(match.command);
+        return;
+      }
+      const custom = presets.find((p) => p.command === "");
+      setCustomCommand(wanted);
+      setSelectedPresetId(custom ? custom.id : "custom");
+      setCommand(wanted);
+      return;
+    }
+    const first = presets.find((p) => p.command !== "");
+    if (first) {
+      setSelectedPresetId(first.id);
+      setCommand(first.command);
+    }
+    // prefill is captured once at construction, not a reactive dependency.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [presets, commandTouched]);
+
+  const structuredSupported = useMemo(() => supportsStructuredView(command), [command]);
+  useEffect(() => {
+    if (!structuredSupported) setStructuredView(false);
+    else if (!structuredTouched) setStructuredView(true);
+  }, [structuredSupported, structuredTouched]);
+
+  // ---- project picker ------------------------------------------------------
+  const [discovered, setDiscovered] = useState<Project[]>([]);
+  const [projectsLoading, setProjectsLoading] = useState(true);
+  const [filterQuery, setFilterQuery] = useState("");
+  const [cwd, setCwd] = useState("");
+  const [cwdRawVisible, setCwdRawVisible] = useState(false);
+  const [rawFocusToken, setRawFocusToken] = useState(0);
+  const [selectedGroupPath, setSelectedGroupPath] = useState<string | null>(null);
+  const [worktreeChoice, setWorktreeChoice] = useState<WorktreeChoice>("new");
+
+  const groups = useMemo(() => groupProjects(sortProjects(discovered, new Date())), [discovered]);
+  const visibleGroups = useMemo(
+    () => groups.filter((g) => filterProjects([g.main, ...g.worktrees], filterQuery).length > 0),
+    [groups, filterQuery],
+  );
+  const selectedGroup = useMemo(
+    () => groups.find((g) => g.main.path === selectedGroupPath) ?? null,
+    [groups, selectedGroupPath],
+  );
+
+
+  useEffect(() => {
+    let cancelled = false;
+    fetchProjects()
+      .then((list) => {
+        if (!cancelled) setDiscovered(list);
+      })
+      .catch(() => {
+        if (!cancelled) setDiscovered([]);
+      })
+      .finally(() => {
+        if (!cancelled) setProjectsLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // ---- worktree (branch-only; base_repo inferred via scan or /gitroot) ----
+  const [wtEnabled, setWtEnabled] = useState(prefill.worktreeEnabled ?? true);
+  const [inferredBaseRepo, setInferredBaseRepo] = useState<string | null>(null);
+  const [wtHint, setWtHint] = useState<string | null>(null);
+  const [name, setName] = useState(prefill.name ?? "");
+  const [branchEdited, setBranchEdited] = useState(Boolean(prefill.worktreeBranchEdited));
+  const [branchMode, setBranchMode] = useState<WorktreeBranchMode>(prefill.worktreeBranchMode ?? "new");
+  const [newBranch, setNewBranch] = useState(prefill.worktreeBranch ?? "");
+  const [existingBranch, setExistingBranch] = useState("");
+  const [branchCache, setBranchCache] = useState<{ cwd: string; branches: BranchInfo[] } | null>(null);
+
+  const [advancedCollapsed, setAdvancedCollapsed] = useState(true);
+  const [error, setError] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const [ready, setReady] = useState(false);
+
+  const probeTokenRef = useRef(0);
+  const probeTimerRef = useRef<number | undefined>(undefined);
+
+  const applyBaseRepoResolution = useCallback((res: BaseRepoResolution) => {
+    switch (res.kind) {
+      case "disabled":
+        setInferredBaseRepo(null);
+        setWtHint(null);
+        return;
+      case "no-cwd":
+        setInferredBaseRepo(null);
+        setWtHint("Choose a working directory first.");
+        return;
+      case "found":
+        setInferredBaseRepo(res.repo);
+        setWtHint(null);
+        setBranchCache(null);
+        setExistingBranch("");
+        return;
+      case "probe":
+        return; // caller schedules the probe
+    }
+  }, []);
+
+  const probeGitRoot = useCallback(async (path: string) => {
+    const token = ++probeTokenRef.current;
+    if (!path) {
+      setInferredBaseRepo(null);
+      setWtHint("Choose a working directory first.");
+      return;
+    }
+    setWtHint("Checking for a git repository…");
+    let root: string | undefined;
+    try {
+      root = (await gitRoot(path)).root;
+    } catch {
+      root = undefined;
+    }
+    if (token !== probeTokenRef.current || destroyedRef.current) return; // a newer probe superseded us
+    if (root) {
+      setInferredBaseRepo(root);
+      setWtHint(null);
+      setBranchCache(null);
+      setExistingBranch("");
+    } else {
+      setInferredBaseRepo(null);
+      // Publish the untick too, or a later submit fails with an inferred repo
+      // that no longer matches an unticked box.
+      setWtEnabled(false);
+      setWtHint("Not inside a git repository — pick a dir in a repo to use a worktree.");
+    }
+  }, []);
+
+  const scheduleGitRootProbe = useCallback(
+    (path: string) => {
+      window.clearTimeout(probeTimerRef.current);
+      probeTimerRef.current = window.setTimeout(() => {
+        probeTimerRef.current = undefined;
+        void probeGitRoot(path);
+      }, GITROOT_PROBE_DEBOUNCE_MS);
+    },
+    [probeGitRoot],
+  );
+  useEffect(() => () => window.clearTimeout(probeTimerRef.current), []);
+
+  // Seed the form once the initial project scan and daemon info have both
+  // settled — mirrors createSpawnForm's `loadProjects()`. Computed from local
+  // values rather than reading state back, since the setState calls below
+  // won't have committed yet within this same effect.
+  const seededRef = useRef(false);
+  useEffect(() => {
+    if (infoLoading || projectsLoading || seededRef.current) return;
+    seededRef.current = true;
+
+    const seedCwd = prefill.cwd ?? null;
+    let finalCwd = "";
+    let finalCwdRawVisible = false;
+    let finalGroupPath: string | null = null;
+    let finalChoice: WorktreeChoice = "new";
+
+    const restore = (path: string): boolean => {
+      for (const group of groups) {
+        const wt = worktreesOf(group).find((p) => p.path === path);
+        const choice: WorktreeChoice | null = wt ? wt.path : group.main.path === path ? "new" : null;
+        if (choice === null) continue;
+        finalGroupPath = group.main.path;
+        finalChoice = choice;
+        return true;
+      }
+      return false;
+    };
+
+    if (seedCwd) {
+      if (prefill.cwdRawVisible === false) {
+        finalCwd = seedCwd;
+        if (!restore(seedCwd)) finalCwdRawVisible = true;
+      } else {
+        finalCwd = seedCwd;
+        finalCwdRawVisible = true;
+      }
+    } else if (discovered.length === 0) {
+      finalCwd = homeDir;
+      finalCwdRawVisible = true;
+    }
+
+    setCwd(finalCwd);
+    setCwdRawVisible(finalCwdRawVisible);
+    setSelectedGroupPath(finalGroupPath);
+    setWorktreeChoice(finalChoice);
+
+    const res = resolveBaseRepoFor(finalCwd, wtEnabled, discovered);
+    applyBaseRepoResolution(res);
+    if (res.kind === "probe") scheduleGitRootProbe(finalCwd);
+
+    setReady(true);
+    // groups/wtEnabled/discovered/homeDir are read for this one settle pass;
+    // re-running on their later changes would re-seed a form the operator
+    // has since edited.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [infoLoading, projectsLoading]);
+
+  // ---- name (also seeds the worktree branch) ------------------------------
+  const skipInitialBranchSync = useRef(Boolean(prefill.worktreeBranch));
+  useEffect(() => {
+    // One-time construction seeding, mirroring spawnForm.ts precedence: an
+    // explicit seed wins outright; otherwise the prefilled name; otherwise a
+    // freshly generated handle (#53).
+    if (prefill.worktreeBranch) return;
+    if (!branchEdited && branchMode === "new" && prefill.name) return; // handled below, mount-only
+    if (!branchEdited && branchMode === "new") {
+      void fetchNames(1)
+        .then((batch) => {
+          const handle = batch.names[0];
+          if (destroyedRef.current || !handle) return;
+          setNewBranch((cur) => cur || handle);
+        })
+        .catch(() => {
+          // the operator types their own branch
+        });
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    if (!skipInitialBranchSync.current && !branchEdited && branchMode === "new" && name) {
+      setNewBranch(name);
+    }
+    skipInitialBranchSync.current = false;
+    // A cleared name leaves the branch on its last value; only `name` changes
+    // (typed or the mount-time prefill) drive this sync.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [name]);
+
+  // ---- existing-branch picker (#61): fetch once per cwd -------------------
+  useEffect(() => {
+    if (branchMode !== "existing" || !cwd || !inferredBaseRepo) return;
+    if (branchCache?.cwd === cwd) return;
+    let cancelled = false;
+    const target = cwd;
+    fetchBranches(target)
+      .then((branches) => {
+        if (cancelled || destroyedRef.current) return;
+        setBranchCache({ cwd: target, branches });
+      })
+      .catch(() => {
+        // the picker just stays empty; "new" mode still works
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [branchMode, cwd, inferredBaseRepo, branchCache]);
+
+  const branchesForCwd = branchCache?.cwd === cwd ? branchCache.branches : undefined;
+
+  // A native <select> defaults its displayed (and reported) value to the
+  // first enabled option once nothing is explicitly selected. Derived at
+  // render/submit time rather than synced via an effect, so there is no
+  // window where the control shows one branch while state still holds "".
+  const effectiveExistingBranch =
+    existingBranch || branchesForCwd?.find((b) => !b.worktree && !b.is_head)?.name || "";
+
+  // ---- emit (#observability parity with spawnForm.ts's onChange) ---------
+  useEffect(() => {
+    if (!ready) return;
+    onChange?.({
+      command,
+      cwd,
+      name,
+      structuredView,
+      autoApprove: activePreset?.auto_approve ?? false,
+      worktreeEnabled: wtEnabled,
+      worktreeBranch: branchMode === "existing" ? effectiveExistingBranch : newBranch,
+      worktreeBranchEdited: branchEdited,
+      worktreeBranchMode: branchMode,
+      cwdRawVisible,
+    });
+  }, [
+    ready,
+    command,
+    cwd,
+    name,
+    structuredView,
+    activePreset,
+    wtEnabled,
+    branchMode,
+    effectiveExistingBranch,
+    newBranch,
+    branchEdited,
+    cwdRawVisible,
+    onChange,
+  ]);
+
+  // ---- handlers -------------------------------------------------------------
+  const selectPreset = useCallback(
+    (id: string) => {
+      setCommandTouched(true);
+      setSelectedPresetId(id);
+      const preset = presets.find((p) => p.id === id);
+      if (!preset || preset.command === "") setCommand(customCommand.trim());
+      else setCommand(preset.command);
+    },
+    [presets, customCommand],
+  );
+
+  const clearProjectSelection = useCallback(() => {
+    setSelectedGroupPath(null);
+    setWorktreeChoice("new");
+  }, []);
+
+  const showRawCwd = useCallback(
+    (prefillValue?: string, focus = true) => {
+      setCwdRawVisible(true);
+      if (prefillValue != null) setCwd(prefillValue);
+      clearProjectSelection();
+      if (focus) setRawFocusToken((t) => t + 1);
+    },
+    [clearProjectSelection],
+  );
+
+  useEffect(() => {
+    if (rawFocusToken === 0) return;
+    rawCwdRef.current?.focus();
+    rawCwdRef.current?.select();
+  }, [rawFocusToken]);
+
+  const applyWorktreeChoice = useCallback(
+    (group: ProjectGroup, choice: WorktreeChoice) => {
+      const target = choice === "new" ? group.main : worktreesOf(group).find((p) => p.path === choice);
+      if (!target) return;
+      setWorktreeChoice(choice);
+      setCwd(target.path);
+      setBranchCache(null);
+      setExistingBranch("");
+      if (choice === "new") {
+        setWtEnabled(true);
+        applyBaseRepoResolution({ kind: "found", repo: group.main.base_repo ?? group.main.path });
+      } else {
+        setWtEnabled(false);
+        applyBaseRepoResolution({ kind: "disabled" });
+      }
+    },
+    [applyBaseRepoResolution],
+  );
+
+  const selectProject = useCallback(
+    (group: ProjectGroup) => {
+      setSelectedGroupPath(group.main.path);
+      setCwdRawVisible(false);
+      // Rule 4: a box that is itself a linked worktree defaults to running there.
+      applyWorktreeChoice(group, group.main.is_worktree ? group.main.path : "new");
+    },
+    [applyWorktreeChoice],
+  );
+
+  const onWtEnabledChange = useCallback(
+    (next: boolean) => {
+      setWtEnabled(next);
+      const res = resolveBaseRepoFor(cwd, next, discovered);
+      applyBaseRepoResolution(res);
+      if (res.kind === "probe") scheduleGitRootProbe(cwd);
+    },
+    [cwd, discovered, applyBaseRepoResolution, scheduleGitRootProbe],
+  );
+
+  const onRawCwdChange = useCallback(
+    (v: string) => {
+      setCwd(v);
+      setBranchCache(null);
+      setExistingBranch("");
+      if (wtEnabled) scheduleGitRootProbe(v);
+    },
+    [wtEnabled, scheduleGitRootProbe],
+  );
+
+  const onSubmit = useCallback(
+    async (e: React.FormEvent<HTMLFormElement>) => {
+      e.preventDefault();
+      setError("");
+      const values: SpawnFormValues = {
+        command,
+        cwd,
+        name,
+        structuredView,
+        autoApprove: activePreset?.auto_approve ?? false,
+        worktreeEnabled: wtEnabled,
+        worktreeBranch: branchMode === "existing" ? effectiveExistingBranch : newBranch,
+        worktreeBranchEdited: branchEdited,
+        worktreeBranchMode: branchMode,
+      };
+      const built = buildSpawnRequest(values, inferredBaseRepo);
+      if ("error" in built) {
+        setError(built.error);
+        return;
+      }
+      setSubmitting(true);
+      try {
+        const session = await createSession(built.req);
+        onSuccess(session);
+      } catch (err) {
+        setError((err as Error).message);
+        setSubmitting(false);
+      }
+    },
+    [
+      command,
+      cwd,
+      name,
+      structuredView,
+      activePreset,
+      wtEnabled,
+      branchMode,
+      effectiveExistingBranch,
+      newBranch,
+      branchEdited,
+      inferredBaseRepo,
+      onSuccess,
+    ],
+  );
+
+  // ---- Enter submits from anywhere (#97) ------------------------------------
+  const onFormKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLFormElement>) => {
+      if (e.key !== "Enter" || e.defaultPrevented) return;
+      const target = e.target as HTMLElement;
+
+      if (target.dataset.role === "toggle") {
+        e.preventDefault();
+        (target as HTMLInputElement).click();
+        return;
+      }
+
+      if (target instanceof HTMLButtonElement && target.dataset.picker) {
+        e.preventDefault();
+        if (target.dataset.active === "true") {
+          formRef.current?.requestSubmit();
+        } else {
+          target.click();
+        }
+        return;
+      }
+
+      e.preventDefault();
+      if (target === filterInputRef.current) {
+        // Resolve the filter to a project only when the current pick isn't
+        // one of the matches: a filter typed past it means the operator
+        // moved on, while a pick that still matches keeps its worktree choice.
+        const stillMatches =
+          selectedGroup != null && visibleGroups.some((g) => g.main.path === selectedGroup.main.path);
+        if (!stillMatches && visibleGroups[0]) selectProject(visibleGroups[0]);
+      }
+      formRef.current?.requestSubmit();
+    },
+    [selectedGroup, visibleGroups, selectProject],
+  );
+
+  return (
+    <form
+      ref={formRef}
+      onSubmit={onSubmit}
+      onKeyDown={onFormKeyDown}
+      className="mx-auto flex w-full max-w-[60ch] flex-col gap-sp-2 overflow-auto p-sp-3"
+    >
+      <div className="flex flex-col gap-sp-2">
+        <span className="text-fs-13 text-ink">Harness</span>
+        <div className="grid grid-cols-[repeat(auto-fill,minmax(120px,1fr))] gap-sp-2">
+          {presets.map((p) => {
+            const isCustom = p.command === "";
+            const toolId = presetToolId(p);
+            const icon = isCustom ? null : toolId ? harnessIcon(toolId) : harnessIcon("shell");
+            const label = TOOL_LABELS[toolId ?? ""] ?? p.label;
+            const active = p.id === selectedPresetId;
+            return (
+              <button
+                key={p.id}
+                type="button"
+                className={`flex flex-col items-center gap-sp-2 rounded-r-2 border px-sp-2 py-sp-3 text-center ${
+                  active
+                    ? "border-accent bg-accent-tint"
+                    : isCustom
+                      ? "border-dashed border-border text-muted"
+                      : "border-border bg-surface-2 hover:border-border-strong"
+                }`}
+                onClick={() => selectPreset(p.id)}
+              >
+                <span
+                  className={`flex h-8 w-8 items-center justify-center ${active ? "text-ink" : "text-muted"}`}
+                  aria-hidden={icon ? undefined : true}
+                  dangerouslySetInnerHTML={icon ? { __html: icon } : undefined}
+                >
+                  {icon ? undefined : "…"}
+                </span>
+                <span className="max-w-full truncate text-fs-13 font-semibold">
+                  {isCustom ? "Custom…" : label}
+                </span>
+              </button>
+            );
+          })}
+        </div>
+        <input
+          ref={customCommandRef}
+          className="w-full rounded-r-2 border border-border bg-surface-2 px-sp-3 py-2.5 font-mono text-fs-15 text-ink"
+          name="command_raw"
+          type="text"
+          hidden={!isCustomSelected}
+          placeholder="bash -l"
+          autoComplete="off"
+          value={customCommand}
+          onChange={(e) => {
+            const v = e.currentTarget.value;
+            setCustomCommand(v);
+            if (isCustomSelected) {
+              setCommandTouched(true);
+              setCommand(v.trim());
+            }
+          }}
+        />
+      </div>
+
+      <div className="flex flex-col gap-sp-2">
+        <span className="text-fs-13 text-ink">Project</span>
+        <input
+          ref={filterInputRef}
+          className="w-full rounded-r-2 border border-border bg-surface-2 px-sp-3 py-2.5 font-mono text-fs-15 text-ink"
+          type="text"
+          placeholder="Filter projects…"
+          autoComplete="off"
+          value={filterQuery}
+          onChange={(e) => setFilterQuery(e.currentTarget.value)}
+        />
+        {!ready ? (
+          <p className="m-0 px-sp-3 py-1.5 text-fs-13 text-faint">Loading projects…</p>
+        ) : (
+          <div className="grid max-h-[300px] grid-cols-2 gap-sp-2 overflow-y-auto p-px">
+            {visibleGroups.map((group) => {
+              const active = selectedGroup?.main.path === group.main.path;
+              return (
+                <button
+                  key={group.main.path}
+                  type="button"
+                  data-picker="project"
+                  data-active={active || undefined}
+                  className={`flex min-w-0 flex-col gap-0.5 rounded-r-2 border px-sp-3 py-sp-2 text-left ${
+                    active ? "border-accent bg-accent-tint" : "border-border bg-surface-2 hover:border-border-strong"
+                  } ${isStale(group.main, new Date()) ? "opacity-55" : ""}`}
+                  onClick={() => selectProject(group)}
+                >
+                  <span className="truncate text-fs-13 font-semibold text-ink">{group.main.name}</span>
+                  <span className="break-words font-mono text-fs-12 text-muted">
+                    {abbreviateCwd(parentDir(group.main.path), homeDir)}
+                  </span>
+                </button>
+              );
+            })}
+            {discovered.length > 0 && visibleGroups.length === 0 && (
+              <p className="col-span-2 m-0 px-sp-3 py-1.5 text-fs-13 text-faint">No projects match.</p>
+            )}
+          </div>
+        )}
+        <button
+          type="button"
+          className="self-start bg-transparent px-0 py-1 text-fs-13 italic text-muted hover:text-ink"
+          onClick={() => showRawCwd(cwd || homeDir)}
+        >
+          Other directory…
+        </button>
+        {cwdRawVisible && (
+          <DirAutocomplete
+            inputRef={rawCwdRef}
+            className="w-full rounded-r-2 border border-border bg-surface-2 px-sp-3 py-2.5 font-mono text-fs-15 text-ink"
+            name="cwd_raw"
+            type="text"
+            placeholder="/home/user/project"
+            value={cwd}
+            onChange={onRawCwdChange}
+          />
+        )}
+      </div>
+
+      <div className="flex flex-col border-t border-border pt-sp-2">
+        <button
+          type="button"
+          className="flex w-full items-center gap-sp-1 py-sp-2 text-left text-fs-11 text-muted"
+          aria-expanded={!advancedCollapsed}
+          onClick={() => setAdvancedCollapsed((c) => !c)}
+        >
+          <span className={`inline-block transition-transform ${advancedCollapsed ? "-rotate-90" : ""}`}>▾</span>
+          <span className="font-semibold">Advanced</span>
+          <span className="ml-auto text-fs-12 text-muted">{wtEnabled ? "creates a worktree" : "no worktree"}</span>
+        </button>
+        {!advancedCollapsed && (
+          <div className="flex flex-col gap-sp-3 py-sp-2">
+            <label className="flex flex-col gap-1 text-fs-12 text-muted">
+              Session name
+              <input
+                name="name"
+                type="text"
+                autoComplete="off"
+                placeholder="named after your first prompt"
+                className="w-full rounded-r-2 border border-border bg-surface-2 px-sp-3 py-2.5 font-mono text-fs-15 text-ink"
+                value={name}
+                onChange={(e) => setName(e.currentTarget.value)}
+              />
+            </label>
+
+            {structuredSupported && (
+              <label className="flex cursor-pointer items-center gap-sp-2 text-fs-14 text-ink">
+                <input
+                  type="checkbox"
+                  data-role="toggle"
+                  className="size-[18px] accent-accent"
+                  checked={structuredView}
+                  onChange={(e) => {
+                    setStructuredTouched(true);
+                    setStructuredView(e.currentTarget.checked);
+                  }}
+                />
+                Structured view
+              </label>
+            )}
+
+            {selectedGroup && (
+              <div className="flex flex-col gap-sp-2">
+                <span className="text-fs-13 text-ink">Worktree</span>
+                <div className="flex max-h-[200px] flex-col gap-sp-1 overflow-y-auto">
+                  <button
+                    type="button"
+                    data-picker="worktree"
+                    data-active={worktreeChoice === "new" || undefined}
+                    className={pickerButtonClass(worktreeChoice === "new")}
+                    onClick={() => applyWorktreeChoice(selectedGroup, "new")}
+                  >
+                    <span className="text-fs-13 font-semibold text-accent">+ new</span>
+                    <span className="text-right text-fs-12 text-muted">
+                      new worktree of {selectedGroup.main.name}
+                    </span>
+                  </button>
+                  {worktreesOf(selectedGroup).map((wt) => (
+                    <button
+                      key={wt.path}
+                      type="button"
+                      data-picker="worktree"
+                      data-active={worktreeChoice === wt.path || undefined}
+                      className={pickerButtonClass(worktreeChoice === wt.path)}
+                      onClick={() => applyWorktreeChoice(selectedGroup, wt.path)}
+                    >
+                      <span className="text-fs-13 font-semibold text-ink">{wt.name}</span>
+                      <span className="text-right text-fs-12 text-muted">{wt.path}</span>
+                    </button>
+                  ))}
+                </div>
+              </div>
+            )}
+
+            <BranchPicker
+              enabled={wtEnabled}
+              onToggleEnabled={onWtEnabledChange}
+              hint={wtHint}
+              baseRepo={inferredBaseRepo}
+              mode={branchMode}
+              onModeChange={setBranchMode}
+              newBranch={newBranch}
+              onNewBranchChange={(v) => {
+                setBranchEdited(true);
+                setNewBranch(v);
+              }}
+              branches={branchesForCwd}
+              existingBranch={effectiveExistingBranch}
+              onExistingBranchChange={setExistingBranch}
+            />
+          </div>
+        )}
+      </div>
+
+      <p role="alert" aria-live="polite" className={`m-0 text-fs-13 text-danger ${error ? "rounded-r-2 bg-danger-tint px-sp-3 py-sp-2" : "min-h-[1.2em]"}`}>
+        {error}
+      </p>
+      <div className="flex justify-end">
+        <button
+          type="submit"
+          disabled={submitting}
+          className="rounded-r-1 bg-accent px-sp-4 py-sp-2 text-fs-13 font-semibold text-accent-ink disabled:opacity-60"
+        >
+          Spawn
+        </button>
+      </div>
+    </form>
+  );
+}

web/src/components/spawn/SpawnModal.test.tsx

@@ -0,0 +1,108 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { DaemonInfo, Project, Session } from "../../types.js";
+import { SpawnModal } from "./SpawnModal.js";
+
+vi.mock("../../api.js", () => ({
+  createSession: vi.fn(),
+  fetchBranches: vi.fn(),
+  fetchNames: vi.fn(),
+  getDaemonInfo: vi.fn(),
+  gitRoot: vi.fn(),
+  listDir: vi.fn(),
+  projects: vi.fn(),
+}));
+
+import { createSession, fetchNames, getDaemonInfo, listDir, projects as fetchProjects } from "../../api.js";
+
+function info(): DaemonInfo {
+  return { hostname: "h", version: "1", home_dir: "/home/n", presets: [{ id: "claude", label: "Claude", command: "claude" }] };
+}
+
+function project(over: Partial<Project> = {}): Project {
+  return { path: "/repos/p", name: "p", ...over };
+}
+
+beforeEach(() => {
+  vi.mocked(getDaemonInfo).mockResolvedValue(info());
+  vi.mocked(fetchProjects).mockResolvedValue([project()]);
+  vi.mocked(fetchNames).mockResolvedValue({ names: ["amber-fox"] });
+  vi.mocked(listDir).mockResolvedValue({ path: "", entries: [] });
+});
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+async function settle() {
+  await waitFor(() => expect(screen.queryByText("Loading projects…")).toBeNull());
+}
+
+describe("SpawnModal", () => {
+  it("mounts the spawn form inside a dialog", async () => {
+    render(<SpawnModal onSuccess={vi.fn()} onClose={vi.fn()} />);
+    await settle();
+
+    expect(screen.getByRole("dialog")).not.toBeNull();
+    expect(screen.getByRole("button", { name: "Spawn" })).not.toBeNull();
+  });
+
+  it("titles a seeded open as a clone", async () => {
+    render(<SpawnModal seed={{ command: "claude" }} onSuccess={vi.fn()} onClose={vi.fn()} />);
+    await settle();
+
+    expect(screen.getByText("Spawn similar")).not.toBeNull();
+  });
+
+  it("titles a plain open as a new session", async () => {
+    render(<SpawnModal onSuccess={vi.fn()} onClose={vi.fn()} />);
+    await settle();
+
+    expect(screen.getByText("Spawn session")).not.toBeNull();
+  });
+
+  it("closes on Escape, on Cancel and on a backdrop click", async () => {
+    const onClose = vi.fn();
+    const { unmount } = render(<SpawnModal onSuccess={vi.fn()} onClose={onClose} />);
+    await settle();
+
+    fireEvent.keyDown(screen.getByRole("dialog"), { key: "Escape" });
+    expect(onClose).toHaveBeenCalledTimes(1);
+
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+    expect(onClose).toHaveBeenCalledTimes(2);
+    unmount();
+
+    render(<SpawnModal onSuccess={vi.fn()} onClose={onClose} />);
+    await settle();
+    fireEvent.click(document.querySelector(".modal-backdrop")!);
+    expect(onClose).toHaveBeenCalledTimes(3);
+  });
+
+  it("closes before handing the created session to its caller", async () => {
+    const created: Session = {
+      id: "s1",
+      cwd: "/repos/p",
+      command: "claude",
+      env: {},
+      metadata: {},
+      status: "Running",
+      created_at: "2026-01-01T00:00:00Z",
+    };
+    vi.mocked(createSession).mockResolvedValue(created);
+    const calls: string[] = [];
+    const onClose = vi.fn(() => calls.push("close"));
+    const onSuccess = vi.fn(() => calls.push("success"));
+    render(<SpawnModal onSuccess={onSuccess} onClose={onClose} />);
+    await settle();
+    fireEvent.click(screen.getByText("p"));
+
+    fireEvent.click(screen.getByRole("button", { name: "Spawn" }));
+
+    await waitFor(() => expect(onSuccess).toHaveBeenCalledWith(created));
+    expect(calls).toEqual(["close", "success"]);
+  });
+});

web/src/components/spawn/SpawnModal.tsx

@@ -0,0 +1,82 @@
+// React port of ../../spawnModal.ts: dialog chrome around SpawnForm. Escape,
+// the ✕ and a click on the backdrop all close it; SpawnForm's own DirAutocomplete
+// swallows Escape first, so dismissing a dropdown never also discards the form.
+
+import { useEffect, useRef } from "react";
+import { createPortal } from "react-dom";
+
+import type { Session } from "../../types.js";
+import { SpawnForm, type SpawnFormProps } from "./SpawnForm.js";
+
+export interface SpawnModalProps {
+  seed?: SpawnFormProps["seed"];
+  /** Called with the created session after a successful submit — the modal
+   * has already closed by then, so the caller decides where it lands. */
+  onSuccess(session: Session): void;
+  onClose(): void;
+}
+
+export function SpawnModal({ seed, onSuccess, onClose }: SpawnModalProps) {
+  const filterInputRef = useRef<HTMLInputElement>(null);
+
+  const handleSuccess = (session: Session) => {
+    onClose();
+    onSuccess(session);
+  };
+
+  // The project filter owns the keyboard on open: typing narrows the list and
+  // Tab from here reaches the harness tiles, matching the TUI's draft pane.
+  useEffect(() => {
+    const host = filterInputRef.current;
+    host?.querySelector<HTMLInputElement>("input[placeholder='Filter projects…']")?.focus();
+  }, []);
+
+  return createPortal(
+    <div
+      className="modal-backdrop fixed inset-0 z-modal flex items-center justify-center bg-bg/70 backdrop-blur-sm"
+      onClick={(e) => {
+        if (e.target === e.currentTarget) onClose();
+      }}
+    >
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="spawn-title"
+        className="flex max-h-[92vh] w-full max-w-[560px] flex-col rounded-r-3 border border-border bg-surface shadow-2"
+        onKeyDown={(e) => {
+          if (e.key === "Escape" && !e.defaultPrevented) {
+            e.preventDefault();
+            onClose();
+          }
+        }}
+      >
+        <header className="flex items-center justify-between border-b border-border p-sp-3">
+          <h2 id="spawn-title" className="m-0 text-fs-15 font-semibold text-ink">
+            {seed ? "Spawn similar" : "Spawn session"}
+          </h2>
+          <button
+            type="button"
+            aria-label="Close"
+            className="rounded-r-1 px-sp-2 py-1 text-fs-15 text-muted hover:text-ink"
+            onClick={onClose}
+          >
+            ✕
+          </button>
+        </header>
+        <div ref={filterInputRef} className="min-h-0 flex-1 overflow-auto">
+          <SpawnForm seed={seed} onSuccess={handleSuccess} />
+        </div>
+        <div className="flex justify-end gap-sp-2 border-t border-border p-sp-3">
+          <button
+            type="button"
+            className="rounded-r-1 border border-border px-sp-3 py-sp-1 text-fs-12 text-ink"
+            onClick={onClose}
+          >
+            Cancel
+          </button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}

web/src/components/spawn/index.ts

@@ -0,0 +1,8 @@
+export { SpawnModal, type SpawnModalProps } from "./SpawnModal.js";
+export { SpawnForm, type SpawnFormProps } from "./SpawnForm.js";
+export { DirAutocomplete, type DirAutocompleteProps } from "./DirAutocomplete.js";
+export { BranchPicker, type BranchPickerProps } from "./BranchPicker.js";
+export { useFastForward, type UseFastForwardOptions } from "./useFastForward.js";
+// spawnSimilar.ts is pure seed-building logic with no DOM dependency — reused
+// as-is rather than re-implemented for React (#248).
+export { spawnSimilarSeed, spawnSimilarProjectSeed } from "../../spawnSimilar.js";

web/src/components/spawn/useFastForward.test.ts

@@ -0,0 +1,114 @@
+// @vitest-environment happy-dom
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { Project, Session, SpawnPreset } from "../../types.js";
+import { useFastForward } from "./useFastForward.js";
+
+vi.mock("../../api.js", () => ({
+  createSession: vi.fn(),
+  fetchNames: vi.fn(),
+  getDaemonInfo: vi.fn(),
+  projects: vi.fn(),
+}));
+
+import { createSession, fetchNames, getDaemonInfo, projects as fetchProjects } from "../../api.js";
+
+const mockCreateSession = vi.mocked(createSession);
+const mockFetchNames = vi.mocked(fetchNames);
+const mockGetDaemonInfo = vi.mocked(getDaemonInfo);
+const mockFetchProjects = vi.mocked(fetchProjects);
+
+const presets: SpawnPreset[] = [{ id: "claude", label: "Claude", command: "claude" }];
+
+function project(over: Partial<Project> = {}): Project {
+  return { path: "/repos/p", name: "p", base_repo: "/repos/p", last_command: "claude", ...over };
+}
+
+function session(): Session {
+  return {
+    id: "s1",
+    cwd: "/repos/p",
+    command: "claude",
+    env: {},
+    metadata: {},
+    status: "Running",
+    created_at: "2026-01-01T00:00:00Z",
+  };
+}
+
+afterEach(() => vi.clearAllMocks());
+
+describe("useFastForward", () => {
+  it("spawns immediately once every default resolves", async () => {
+    mockFetchProjects.mockResolvedValue([project()]);
+    mockFetchNames.mockResolvedValue({ names: ["amber-fox"] });
+    mockGetDaemonInfo.mockResolvedValue({ hostname: "h", version: "1", presets });
+    const created = session();
+    mockCreateSession.mockResolvedValue(created);
+    const onSpawned = vi.fn();
+    const onFallback = vi.fn();
+
+    const { result } = renderHook(() => useFastForward({ onSpawned, onFallback }));
+    await act(() => result.current());
+
+    expect(mockCreateSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cwd: "/repos/p",
+        command: "claude",
+        worktree: { base_repo: "/repos/p", branch: "amber-fox", create_branch: true },
+      }),
+    );
+    expect(onSpawned).toHaveBeenCalledWith(created);
+    expect(onFallback).not.toHaveBeenCalled();
+  });
+
+  it("falls back to a pre-filled seed when the daemon rejects the spawn", async () => {
+    mockFetchProjects.mockResolvedValue([project()]);
+    mockFetchNames.mockResolvedValue({ names: ["amber-fox"] });
+    mockGetDaemonInfo.mockResolvedValue({ hostname: "h", version: "1", presets });
+    mockCreateSession.mockRejectedValue(new Error("boom"));
+    const onSpawned = vi.fn();
+    const onFallback = vi.fn();
+
+    const { result } = renderHook(() => useFastForward({ onSpawned, onFallback }));
+    await act(() => result.current());
+
+    expect(onSpawned).not.toHaveBeenCalled();
+    expect(onFallback).toHaveBeenCalledWith(
+      expect.objectContaining({ cwd: "/repos/p", command: "claude", worktreeBranch: "amber-fox" }),
+    );
+  });
+
+  it("falls back when nothing is known yet (no projects, no handle)", async () => {
+    mockFetchProjects.mockResolvedValue([]);
+    mockFetchNames.mockRejectedValue(new Error("exhausted"));
+    mockGetDaemonInfo.mockResolvedValue({ hostname: "h", version: "1", presets });
+    const onSpawned = vi.fn();
+    const onFallback = vi.fn();
+
+    const { result } = renderHook(() => useFastForward({ onSpawned, onFallback }));
+    await act(() => result.current());
+
+    expect(mockCreateSession).not.toHaveBeenCalled();
+    expect(onFallback).toHaveBeenCalledWith(expect.objectContaining({ cwd: "" }));
+  });
+
+  it("prefers the focused session's project over the freshest one", async () => {
+    mockFetchProjects.mockResolvedValue([
+      project({ path: "/repos/fresh", name: "fresh" }),
+      project({ path: "/repos/current", name: "current", last_activity: "2020-01-01T00:00:00Z" }),
+    ]);
+    mockFetchNames.mockResolvedValue({ names: ["h"] });
+    mockGetDaemonInfo.mockResolvedValue({ hostname: "h", version: "1", presets });
+    mockCreateSession.mockResolvedValue(session());
+    const onSpawned = vi.fn();
+
+    const { result } = renderHook(() =>
+      useFastForward({ focusedCwd: "/repos/current", onSpawned, onFallback: vi.fn() }),
+    );
+    await act(() => result.current());
+
+    expect(mockCreateSession).toHaveBeenCalledWith(expect.objectContaining({ cwd: "/repos/current" }));
+  });
+});

web/src/components/spawn/useFastForward.ts

@@ -0,0 +1,57 @@
+// React port of main.ts's `requestFastForward` (#67): one keystroke, every
+// spawn default resolved — most recent project (or the one the operator is
+// on), its last command, a fresh generated branch handle, worktree on with a
+// new branch. A failed POST, or any missing default, falls back to the same
+// pre-filled form `onFallback` opens, rather than a dead keystroke.
+
+import { useCallback } from "react";
+
+import { createSession, fetchNames, getDaemonInfo, projects as fetchProjects } from "../../api.js";
+import { buildFastForwardRequest, fastForwardSeed, resolveFastForward } from "../../fastForward.js";
+import { FALLBACK_PRESETS, type SpawnFormSeed } from "../../spawnForm.js";
+import type { Project, Session, SpawnPreset } from "../../types.js";
+
+export interface UseFastForwardOptions {
+  /** The project of the session the operator is currently on, if any — its
+   * base repo for a worktree session, else its cwd. Same rule the plain
+   * spawn modal's seed uses, so `N` lands where the operator currently is. */
+  focusedCwd?: string;
+  onSpawned(session: Session): void;
+  onFallback(seed: SpawnFormSeed): void;
+}
+
+async function resolvePresets(): Promise<SpawnPreset[]> {
+  try {
+    const info = await getDaemonInfo();
+    if (info.presets?.length) return info.presets;
+  } catch {
+    // keep fallbacks
+  }
+  return FALLBACK_PRESETS;
+}
+
+/** Returns a function to call on the fast-forward keystroke. */
+export function useFastForward(opts: UseFastForwardOptions): () => Promise<void> {
+  const { focusedCwd, onSpawned, onFallback } = opts;
+
+  return useCallback(async () => {
+    const [discovered, handle] = await Promise.all([
+      fetchProjects().catch(() => [] as Project[]),
+      fetchNames(1)
+        .then((batch) => batch.names[0])
+        .catch(() => undefined),
+    ]);
+    const presets = await resolvePresets();
+    const resolved = resolveFastForward(discovered, presets, handle, focusedCwd);
+    const req = buildFastForwardRequest(resolved);
+    if (req) {
+      try {
+        onSpawned(await createSession(req));
+        return;
+      } catch {
+        // degrades to the pre-filled form below, never a silent dead key
+      }
+    }
+    onFallback(fastForwardSeed(resolved));
+  }, [focusedCwd, onSpawned, onFallback]);
+}

web/src/sidebarSearch.test.ts

@@ -7,7 +7,7 @@ import { beforeAll, describe, expect, it } from "vitest";
 
 import { OPEN_COMMAND_BAR_EVENT, renderSidebar } from "./catalog.js";
 import { sessionBarCandidates } from "./commandBar.js";
-import { matchAndRank } from "./matcher.js";
+import { matchAndRank } from "./utils/matcher.js";
 import type { CatalogListener, CatalogStore } from "./events.js";
 import type { Session } from "./types.js";
 

web/src/spawnForm.ts

@@ -15,9 +15,9 @@ import { splitCommand, toolIconSvg, TOOL_LABELS } from "./toolIcon.js";
 import { abbreviateCwd } from "./types.js";
 import type { BranchInfo, CreateSessionRequest, Project, Session, SpawnPreset } from "./types.js";
 
-const STRUCTURED_VIEW_TOOLS = new Set(["claude", "codex"]);
+export const STRUCTURED_VIEW_TOOLS = new Set(["claude", "codex"]);
 
-function supportsStructuredView(command: string): boolean {
+export function supportsStructuredView(command: string): boolean {
   const tool = splitCommand(command).tool;
   return tool !== null && STRUCTURED_VIEW_TOOLS.has(tool);
 }