docs(maestro): add SIDEBAR.md session card contract

Pressing Spawn while reading a session split that pane in half. It now
opens the draft in its own tab, leaving the current tab untouched.

Scoped to the explicit Spawn affordances (the header button and the
sidebar empty state, both via OPEN_SPAWN_EVENT). "Spawn similar" and the
fast-forward key deliberately keep splitting: both act on the session in
front of you, so a pane beside it is the point. Reusing an empty pane
(#72) is unchanged — that path never split anything.

Closes #100

.gitea/workflows/ci.yml

@@ -106,14 +106,24 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # The runner container is root with no `nixbld` group, but the installer
+      # writes `build-users-group = nixbld` anyway and then fails on it, so the
+      # config goes in first. Flakes are off by default and `nix build .#…`
+      # needs them. Written again afterwards in case the installer replaced it.
       - name: Install nix
         run: |
-          curl -fsSL https://nixos.org/nix/install | sh -s -- --daemon --yes
-          echo "/nix/var/nix/profiles/default/bin" >> "$GITHUB_PATH"
+          mkdir -p /etc/nix
+          printf 'build-users-group =\nexperimental-features = nix-command flakes\n' > /etc/nix/nix.conf
+          curl -fsSL https://nixos.org/nix/install | sh -s -- --no-daemon --yes
+          printf 'build-users-group =\nexperimental-features = nix-command flakes\n' > /etc/nix/nix.conf
+          echo "$HOME/.nix-profile/bin" >> "$GITHUB_PATH"
 
+      # The installer does not enable flakes, so `nix build .#…` needs the
+      # features passed explicitly — a local machine that has them in
+      # nix.conf will build fine while CI fails without this.
       - name: build flake packages
         run: |
-          nix build \
+          nix --extra-experimental-features "nix-command flakes" build \
             .#webFrontend \
             .#maestro \
             .#maestro-web \

CLAUDE.md

@@ -66,6 +66,10 @@ See `docs/INSTALL.md` for end-user install instructions.
 collisions, what blocks a kill, what `--force` retains, and what reclaim
 touches. Read it before changing anything that creates or removes one.
 
+`docs/SIDEBAR.md` is the contract for session cards in the web and TUI
+sidebars — line layout, activity colours, duration format, state precedence.
+Read it before changing sidebar rendering.
+
 `nix run .#dev` (or `just dev`) brings up the whole local stack under
 process-compose: a debug daemon on 127.0.0.1:7071, then Vite on :5173 once the
 daemon answers `/api/info`. The SPA proxies `/api/*` back to the daemon, so only

crates/maestro-daemon/src/session.rs

@@ -278,7 +278,11 @@ impl SessionManager {
                     self.inner.worktree_mgr.add_existing(base_repo, branch)
                 }
                 .map_err(SessionError::Worktree)?;
-                (path.clone(), Some(path), Some(base_repo.clone()))
+                // Record the repository, not whatever the request named: a
+                // spawn from inside a linked worktree passes that worktree as
+                // `base_repo`, and clients group sessions by this path (#99).
+                let repo = crate::worktree::main_checkout_of(base_repo);
+                (path.clone(), Some(path), Some(repo))
             }
             None => (req.cwd.clone(), None, None),
         };

crates/maestro-daemon/src/worktree.rs

@@ -174,6 +174,13 @@ impl WorktreeManager {
 /// The repository's main checkout. `--git-common-dir` points at the shared
 /// `.git` for every linked worktree, so its parent is the main tree. Falls
 /// back to the input when git can't answer.
+/// The repository a path belongs to: the main checkout, even when `path` is a
+/// linked worktree. Clients group sessions by this (#99), and placement uses it
+/// so a worktree is never nested inside another.
+pub fn main_checkout_of(path: &Path) -> PathBuf {
+    main_checkout(path)
+}
+
 fn main_checkout(path: &Path) -> PathBuf {
     let out = Command::new("git")
         .arg("-C")

crates/maestro-daemon/tests/session_manager.rs

@@ -947,3 +947,60 @@ async fn liveness_watcher_leaves_running_sessions_alone() {
 
     fx.manager.kill(s.id, false).await.unwrap();
 }
+
+/// #99: clients group a session under `worktree.base_repo`, so that field has
+/// to name the repository even when the spawn request pointed at a linked
+/// worktree. Recording the request verbatim put the session in a folder of its
+/// own — `<repo>/worktrees/<branch>` — instead of under the repo.
+#[tokio::test]
+async fn worktree_base_repo_records_the_main_checkout_not_the_request() {
+    let fx = DaemonFixture::new();
+    let repo = TempDir::new().unwrap();
+    init_repo(repo.path());
+
+    // A linked worktree of that repo, then a spawn whose `base_repo` names it
+    // rather than the main checkout — what happens when the operator spawns
+    // from inside a worktree.
+    let first = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: repo.path().to_path_buf(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: repo.path().to_path_buf(),
+                branch: "feat/one".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .expect("create first");
+    let inner_worktree = first.worktree.expect("first has a worktree").path;
+
+    let second = fx
+        .manager
+        .create(CreateSessionRequest {
+            cwd: inner_worktree.clone(),
+            command: "sleep 30".into(),
+            env: HashMap::new(),
+            metadata: HashMap::new(),
+            worktree: Some(WorktreeSpec {
+                base_repo: inner_worktree.clone(),
+                branch: "feat/two".into(),
+                create_branch: true,
+            }),
+        })
+        .await
+        .expect("create second");
+
+    let wt = second.worktree.expect("second has a worktree");
+    assert_eq!(
+        wt.base_repo,
+        repo.path()
+            .canonicalize()
+            .unwrap_or_else(|_| repo.path().to_path_buf()),
+        "base_repo must be the repository, not the worktree the request named",
+    );
+    assert_ne!(wt.base_repo, inner_worktree, "the worktree is not the repo");
+}

docs/SIDEBAR.md

@@ -0,0 +1,92 @@
+# SIDEBAR.md — the session card contract
+
+One rule for how a session is rendered as a card in the sidebar, so the web
+sidebar (#107) and the TUI sidebar (#108) describe a session the same way.
+Read this before changing either. Both clients implement exactly what is
+written here; if it needs to change, change it here first.
+
+A card has **line 1** always and **line 2** only when line 2 has something to
+say.
+
+## Line 1 — name + actions
+
+- Left: the session name — `metadata.name` if present, else the command line
+  (same fallback both clients already use).
+- Right: two actions anchored to the top-right corner: **spawn similar**
+  (`⧉`) and **kill** (`✕`). In the TUI these are keyboard affordances shown on
+  the highlighted row; in the web they are buttons. The glyphs are shared so
+  muscle memory transfers.
+- Actions reserve their fixed width; the name truncates with `…` before it can
+  ever reach them. **Overlap between the name and the actions is a defect** —
+  that overlap is what started this milestone.
+
+Line 1 carries no badges. The `⚠ blocked work` badge (#83) and the `exited`
+badge move off this row into line 2.
+
+## Line 2 — meta line (adaptive)
+
+Rendered only when at least one of these holds:
+
+1. The session has been held in its current activity state longer than
+   **30 seconds** (`activity_since` from #102). A freshly-active session
+   stays one line.
+2. Its worktree holds blocked work: `blocked_work` is `Some` and not clear
+   (`InTheWay::is_clear()`), rendered in `formatInTheWay`'s phrasing on web
+   and as `⚠ <summary>` on the TUI.
+3. It has exited: `status == Dead`.
+4. An agent-reported state (#105) of `Error` is in force (see Precedence).
+
+Otherwise line 2 is absent — never an empty placeholder row.
+
+When present, line 2 reads left to right:
+
+```
+<duration> [<state badge>] [<blocked work> | exited]
+```
+
+## Colour per activity state
+
+The state word is never spelled out — the colour carries it.
+
+| Activity state   | Web token | ratatui colour    |
+| ---------------- | --------- | ----------------- |
+| `Active`         | `--live`  | `Color::Green`    |
+| `Idle`           | `--muted` | `Color::DarkGray` |
+| `AwaitingInput`  | `--warn`  | `Color::Yellow`   |
+| `Error`          | `--danger`| `Color::Red`      |
+
+Web tokens resolve per theme automatically (`styles.css` defines dark, light,
+and `prefers-color-scheme` variants for each). The TUI uses the plain ratatui
+named colours above; do not introduce RGB values or a new palette module for
+this.
+
+The duration text inherits its state's colour; the blocked-work and exited
+fragments use the muted colour (`--faint` / default style), since the ⚠ glyph
+already signals severity.
+
+## Duration format
+
+Time spent in the **current activity state**, sourced from `activity_since`
+(#102) — *not* time since spawn, and *not* time since last PTY output
+(`last_activity_at`). Both clients compute it identically:
+
+- `< 60s` → whole seconds, floored: `30s`
+- `< 60m` → whole minutes, floored: `4m`
+- `≥ 60m` → whole hours, floored: `2h`
+
+No days unit, no seconds inside minutes, no rounding up. Floor everywhere so
+the counter never shows a duration the state hasn't actually reached yet.
+Clock granularity: re-render at least once every 30s while visible so the
+cutover points land within one tick.
+
+## Precedence
+
+An agent-reported `ActivityState` (#105) overrides the daemon's inference for
+the TTL the report carries; when the TTL expires, inference resumes. Clients
+never blend the two: whichever source is in force supplies both the colour and
+the clock for `activity_since`.
+
+If a client receives an `ActivityState` variant it does not know, it must not
+fail rendering: treat it as `Idle` (neutral/dim, line-2 rules apply as usual)
+until the daemon sends a variant it does know. Rust clients deserialize
+activity leniently for the same reason.

web/src/main.ts

@@ -272,7 +272,11 @@ function showMultiView(): void {
 // cloned session's dir + command.
 function requestOpenSpawn(): void {
   showMultiView();
-  mv.openDraft();
+  // A new tab, not a split of the pane you were reading (#100). "Spawn
+  // similar" and the fast-forward key below deliberately keep the old
+  // behaviour: both act on the session in front of you, so a split beside it
+  // is the point.
+  mv.openDraft(undefined, { newTab: true });
 }
 document.addEventListener(OPEN_SPAWN_EVENT, () => requestOpenSpawn());
 document.addEventListener("catalog-spawn-similar", (ev) => {

web/src/multiview.test.ts

@@ -282,3 +282,54 @@ describe("multiview pane-drag swap (#73)", () => {
     expect(nameInputOf(leaf2).value).toBe("west");
   });
 });
+
+describe("openDraft newTab (#100)", () => {
+  beforeEach(() => {
+    stubFetch();
+    document.body.replaceChildren();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("opens its own tab instead of splitting the focused session", async () => {
+    const layout = emptyLayout();
+    const tab = layout.tabs[0];
+    const first = splitLeaf(tab, "", "s1", "row", true);
+    tab.focusedLeafId = first;
+    const mv = makeMv(layout);
+    document.body.appendChild(mv.el);
+    mv.render();
+
+    mv.openDraft(undefined, { newTab: true });
+    await flush();
+
+    expect(layout.tabs).toHaveLength(2);
+    // The tab you were reading is untouched: still one pane, still its session.
+    const original = leaves(layout.tabs[0].root);
+    expect(original).toHaveLength(1);
+    expect(original[0].sessionId).toBe("s1");
+    // The draft is alone in the new, now-active tab.
+    const fresh = leaves(layout.tabs[1].root);
+    expect(fresh).toHaveLength(1);
+    expect(fresh[0].sessionId).toBeNull();
+    expect(fresh[0].draft).not.toBeNull();
+    expect(layout.activeTabId).toBe(layout.tabs[1].id);
+  });
+
+  it("still splits when newTab is not asked for", async () => {
+    const layout = emptyLayout();
+    const tab = layout.tabs[0];
+    tab.focusedLeafId = splitLeaf(tab, "", "s1", "row", true);
+    const mv = makeMv(layout);
+    document.body.appendChild(mv.el);
+    mv.render();
+
+    mv.openDraft();
+    await flush();
+
+    expect(layout.tabs).toHaveLength(1);
+    expect(leaves(tab.root)).toHaveLength(2);
+  });
+});

web/src/multiview.ts

@@ -57,7 +57,7 @@ export interface MultiView {
   /** Open a draft pane (issue #62): reuse the focused pane if it is already
    *  empty, otherwise split the focused pane. `seed` pre-fills the form
    *  ("Spawn similar" clones a session's cwd + command). */
-  openDraft: (seed?: Partial<Draft>) => void;
+  openDraft: (seed?: Partial<Draft>, opts?: { newTab?: boolean }) => void;
   /** Start dragging a sidebar session into the canvas (issue #32). The
    *  controller owns drag-vs-tap: a tap lets the row's normal click open it, a
    *  drag shows drop zones to place it. */
@@ -412,9 +412,18 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     opts.onOpenSessionsChange?.();
   }
 
-  function openDraft(seed?: Partial<Draft>): void {
-    const tab = activeTab(layout);
+  function openDraft(seed?: Partial<Draft>, opts?: { newTab?: boolean }): void {
     const draft = (): Draft => ({ command: "", cwd: "", name: "", ...seed });
+    if (opts?.newTab) {
+      // Spawn opens its own tab rather than halving whatever you were reading
+      // (#100). The empty-pane reuse below still applies within a tab.
+      const fresh = addTab(layout);
+      fresh.focusedLeafId = splitLeaf(fresh, "", null, "row", true);
+      findLeaf(fresh.root!, fresh.focusedLeafId)!.draft = draft();
+      render();
+      return;
+    }
+    const tab = activeTab(layout);
     if (!tab.root || !tab.focusedLeafId || !findLeaf(tab.root, tab.focusedLeafId)) {
       // Empty tab (or stale focus): the draft becomes the first pane.
       tab.focusedLeafId = splitLeaf(tab, "", null, "row", true);

web/src/tree.test.ts

@@ -95,3 +95,59 @@ describe("mergeLinear", () => {
     expect(merged.path).toBe("a/b");
   });
 });
+
+describe("worktree sessions group under their repository (#99)", () => {
+  /** A session the daemon spawned into a worktree of `repo`. */
+  function worktreeSession(id: string, repo: string, wt: string): Session {
+    return { ...session(id, wt), worktree: { path: wt, base_repo: repo } } as Session;
+  }
+
+  /** Top-level folder names, after linear chains are collapsed. */
+  function topFolders(root: TreeFolder): string[] {
+    return root.children.filter((c) => c.kind === "folder").map((c) => (c as TreeFolder).name);
+  }
+
+  it("nests under the repo, not the worktree directory", () => {
+    const root = buildTree(
+      [
+        worktreeSession(
+          "a",
+          "/home/n/tea/agent-skills",
+          "/home/n/tea/agent-skills/worktrees/largo-clarinet",
+        ),
+      ],
+      "/home/n",
+      "",
+    ) as TreeFolder;
+
+    expect(topFolders(root)).toEqual(["~/tea/agent-skills"]);
+    const repo = root.children[0] as TreeFolder;
+    expect(repo.children).toHaveLength(1);
+    expect(repo.children[0].kind).toBe("leaf");
+  });
+
+  it("puts a repo's plain and worktree sessions side by side", () => {
+    const root = buildTree(
+      [
+        session("plain", "/home/n/tea/agent-skills"),
+        worktreeSession(
+          "wt",
+          "/home/n/tea/agent-skills",
+          "/home/n/tea/agent-skills/worktrees/largo-clarinet",
+        ),
+      ],
+      "/home/n",
+      "",
+    ) as TreeFolder;
+
+    expect(topFolders(root)).toEqual(["~/tea/agent-skills"]);
+    const repo = root.children[0] as TreeFolder;
+    expect(repo.children).toHaveLength(2);
+    expect(repo.children.every((c) => c.kind === "leaf")).toBe(true);
+  });
+
+  it("leaves a session without a worktree where it is", () => {
+    const root = buildTree([session("a", "/home/n/tea/arr")], "/home/n", "") as TreeFolder;
+    expect(topFolders(root)).toEqual(["~/tea/arr"]);
+  });
+});

web/src/tree.ts

@@ -2,7 +2,7 @@
 // so it can be tested directly.
 
 import type { Session } from "./types.js";
-import { abbreviateCwd, sessionCwd, sessionName } from "./types.js";
+import { abbreviateCwd, sessionName, sessionTreePath } from "./types.js";
 
 export interface TreeFolder {
   kind: "folder";
@@ -30,7 +30,9 @@ export function buildTree(sessions: Session[], home: string | undefined, filter:
   const lc = filter.trim().toLowerCase();
 
   for (const s of sessions) {
-    const cwd = sessionCwd(s);
+    // Grouped by repository, so a worktree session lands under its repo
+    // rather than in a folder of its own (#99).
+    const cwd = sessionTreePath(s);
     const dir = cwd ? abbreviateCwd(cwd, home) : "";
     if (lc) {
       const haystack = `${sessionName(s)} ${dir}`.toLowerCase();

web/src/types.ts

@@ -36,6 +36,16 @@ export interface Session {
    * without a worktree; all counts default to 0 on the wire for older
    * daemons. */
   blocked_work?: InTheWay | null;
+  /** The worktree the daemon created for this session, absent when it did not
+   * create one. `base_repo` is the repository's main checkout, which is what
+   * the session tree groups by (#99). */
+  worktree?: SessionWorktree | null;
+}
+
+/** A session's daemon-created worktree (`SessionWorktree` on the wire). */
+export interface SessionWorktree {
+  path: string;
+  base_repo: string;
 }
 
 /** One directory's immediate subdirectories (NAP-329). */
@@ -231,12 +241,23 @@ export function sessionName(s: Session): string {
 }
 
 /** The directory a session lives in: its live `current_cwd` if the daemon has
- * observed one, else the spawn `cwd`. Drives the directory-based session tree. */
+ * observed one, else the spawn `cwd`. */
 export function sessionCwd(s: Session): string | undefined {
   if (typeof s.current_cwd === "string" && s.current_cwd) return s.current_cwd;
   return s.cwd || undefined;
 }
 
+/** Where a session sits in the directory tree. A worktree session belongs to
+ * its repository, not to the worktree (#99): otherwise `~/tea/agent-skills`
+ * grows a `~/tea/agent-skills/worktrees/largo-clarinet` folder holding one
+ * session of the same name, and the repository stops being where you look for
+ * the work. `base_repo` is the main checkout — the daemon resolves it. */
+export function sessionTreePath(s: Session): string | undefined {
+  const repo = s.worktree?.base_repo;
+  if (typeof repo === "string" && repo) return repo;
+  return sessionCwd(s);
+}
+
 /** Collapse a daemon's home dir to `~`. `home` comes from `DaemonInfo.home_dir`;
  * absent/empty leaves the path untouched. Mirrors the CLI's `abbreviate_dir`. */
 export function abbreviateCwd(cwd: string, home?: string): string {