moshcode 0.35.0 → 0.36.0

package/README.md

@@ -125,37 +125,81 @@ moshcode attach api                      # step in; Ctrl-b d steps back out
 moshcode kill api                        # end it
 ```
 
-### The clickable list
+### Everything on screen at once
 
 ```sh
-moshcode herd ui
+moshcode herd tile
 ```
 
 ```
-  moshcode herd   3 members   1 waiting on you
+┌─ work ──────────────────┬─ logs ──────────────────┐
+│ $ npm test              │ tailing deploy.log      │
+│ ✓ 1492 passing          │ 12:04 build ok          │
+├─ api ───────────────────┴─────────────────────────┤
+│ claude — Do you want to proceed?                  │
+│ ❯ 1. Yes    2. No                                 │
+└───────────────────────────────────────────────────┘
+ herd            S:shell A:agent X:stop B:pop out z:zoom
+```
+
+Every member becomes a tile in one window. Click a tile to focus it, `Ctrl-b z`
+to blow it up full-screen and again to come back, `Ctrl-b d` to leave the lot
+running. Start and stop without leaving:
 
-  MAIN (2)
-   ▸ ! api          claude     blocked  ~/src/coinpay
-     · work         shell      idle     ~/src/coinpay
+| key | |
+|---|---|
+| `Ctrl-b S` | new shell tile |
+| `Ctrl-b A` | new claude tile |
+| `Ctrl-b X` | stop the focused tile |
+| `Ctrl-b B` | pop it out into its own session |
+| `Ctrl-b z` | zoom / unzoom |
 
-  SCRATCH (1)
-     · logs         shell      idle     ~/src/ugig.net
+`moshcode herd untile` puts them all back in their own sessions. Tiling is just
+a view — the processes never restart, and a tiled member stays on `moshcode ps`
+and answers `read`, `prompt` and `wait` exactly as before.
 
-  click or ↑↓ to choose · enter to go in · r refresh · q quit
-```
+Needs tmux. The `script(1)` fallback gives each session its own pty with no way
+to lay them out together, so it says so and points at the list instead.
 
-Click a member to go into it; detach and you land back on the list. Group
-sessions with `--herd <name>` when you start them; anything without one is in
-`main`.
+### The workspace
 
-It hands the terminal to a **real** attach rather than drawing the session
-itself, so what you get inside is a genuine terminal — full colour, real cursor,
-the agent's own mouse handling. The cost is that the list is not on screen at
-the same time as the session. tmux's model is session → window → pane and a pane
-belongs to exactly one window, so nothing can persist across a switch; a pinned
-sidebar would mean rendering every session from polled snapshots and losing all
-of the above. Once you are attached, `Ctrl-b s` is a clickable picker and the
-status line is a clickable list.
+```sh
+moshcode herd ui
+```
+
+```
+┌ herd ──────┬─ api ─────────────────────────────┐
+│ herd       │                                   │
+│            │  claude                           │
+│ MAIN       │  Do you want to proceed?          │
+│ ▸ ! api    │  ❯ 1. Yes                         │
+│   · work   │    2. No                          │
+│ SCRATCH    │                                   │
+│   · logs   │                                   │
+│            │                                   │
+│ ACTIONS    │                                   │
+│   + shell  │                                   │
+│   + agent  │                                   │
+│   ✕ stop   │                                   │
+│   ⊞ tile   │                                   │
+│   ← detach │                                   │
+└────────────┴───────────────────────────────────┘
+```
+
+Members and actions down the left, the selected member's **real terminal** on
+the right. Click a member to show it; click an action to start a shell, start an
+agent, or stop the selected one. `q` detaches and leaves everything running.
+
+The right-hand pane is not a picture of a session — it *is* the session's pane,
+moved in. tmux's model is session → window → pane, so moving between *windows*
+cannot keep anything on screen; but `join-pane` moves a running pane into an
+existing window, so swapping only the content pane leaves the sidebar untouched.
+Both panes keep their process and their scrollback because tmux is moving the
+real thing, not redrawing it.
+
+Group sessions with `--herd <name>` when you start them; anything without one is
+in `main`. Without tmux there is nothing to swap panes with, so `herd ui` falls
+back to a plain clickable list.
 
 ### A workspace: a few shells and an agent
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moshcode",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "type": "module",
   "description": "moshcode — a metal wrapper for coding engines and native UGig/CoinPay workflow CLIs, with OpenPRD and moshscript",
   "repository": {

package/src/cli-schema.mjs

@@ -738,9 +738,16 @@ export const HERD_VERBS = [
       ["--agent", "autonomous mode — bypasses the engine's approvals", ""],
       ["--json", "machine-readable", ""],
     ] },
-  { name: "ui", description: "the clickable list of herds and their members",
-    synopsis: [["moshcode herd ui", "click or ↑↓ to choose, enter to go in, q to quit"]],
-    flags: [] },
+  { name: "tile", description: "every member on screen at once, in a tiled window",
+    synopsis: [["moshcode herd tile [herd]", "click a tile to focus · Ctrl-b z zooms · Ctrl-b d leaves them running"]],
+    flags: [],
+    examples: [["moshcode herd tile", "all of them"], ["moshcode herd tile scratch", "one herd"]] },
+  { name: "untile", description: "put tiled members back in their own sessions",
+    synopsis: [["moshcode herd untile", ""]] },
+  { name: "ui", description: "sidebar of members and actions, selected one beside it",
+    synopsis: [["moshcode herd ui", "click a member to show it · s shell · a agent · x stop · q detach"]],
+    flags: [],
+    examples: [["moshcode herd ui", "the workspace — start here"]] },
   { name: "run", description: "run ANY command in the herd — an agent moshcode does not ship, a build, a script",
     synopsis: [["moshcode herd run [--name <slug>] -- <command…>", "everything after -- is the command"]],
     flags: [

package/src/herd-cli.mjs

@@ -725,7 +725,12 @@ export function herdStop(argv, { write = console.log } = {}) {
 const VERBS = {
   // Lazy import: the UI pulls in escape-sequence machinery and only matters
   // when someone asks for it, and herd-ui imports roster() from this file.
-  ui: async (argv, options) => (await import("./herd-ui.mjs")).herdUi(options),
+  // `ui` is the sidebar workspace; the old modal list lives on as the fallback
+  // inside it for machines with no tmux to swap panes on.
+  ui: async (argv, options) => (await import("./herd-workspace.mjs")).herdUi(argv, options),
+  sidebar: async (argv, options) => (await import("./herd-workspace.mjs")).herdSidebar(options),
+  tile: async (argv, options) => (await import("./herd-tile.mjs")).herdTile(argv, options),
+  untile: async (argv, options) => (await import("./herd-tile.mjs")).herdUntile(argv, options),
   ps: herdPs, list: herdPs, status: herdStatus,
   start: herdStart, run: herdRun, shell: herdShell,
   attach: herdAttach, kill: herdKill, prune: herdPrune,

package/src/herd-tile.mjs

@@ -0,0 +1,168 @@
+// `moshcode herd tile` — every member on screen at once, in a tiled window.
+//
+// The clickable list was modal: you saw the herd OR a session, never both, and
+// nothing on it could start or stop anything. This is the other shape — all
+// members visible, click one to focus it, Ctrl-b z to blow it up, keys to start
+// and stop without leaving.
+//
+// It is tmux doing the work, not us. `join-pane` moves a running pane out of
+// its own session and into a shared window with its content and process intact;
+// `select-layout tiled` arranges them; `break-pane` puts one back. Every pane
+// stays a real terminal the whole time, which is the thing a hand-rolled
+// side-by-side renderer cannot promise.
+//
+// This is why a member is identified by its pane title rather than its session
+// (see paneIndex in herd.mjs): a tiled member's session no longer exists, and
+// the roster, `read`, `prompt` and `wait` all have to keep working anyway.
+import { spawn, spawnSync } from "node:child_process";
+
+import { HERD_SOCKET, detectSubstrate, paneIndex, readManifest, tmux } from "./herd.mjs";
+import { acid, ash, err, info, ok } from "./ui.mjs";
+
+/** The window every tiled member is gathered into. */
+export const TILE_SESSION = "tile";
+
+/**
+ * Keys bound inside the tiled window.
+ *
+ * Bound on moshcode's own server, which starts from no config, so this
+ * overrides nobody's preference. They are deliberately shifted letters: tmux's
+ * own lowercase bindings (z zoom, x kill, arrows, o next) still work, and this
+ * only adds what tmux has no opinion about.
+ */
+export function tileBindings({ moshcode = "moshcode" } = {}) {
+  return [
+    // Start: a shell, or an agent, as a new tile in the same directory.
+    ["S", `split-window -c "#{pane_current_path}" ; select-layout tiled`],
+    ["A", `split-window -c "#{pane_current_path}" ${moshcode} agents claude ; select-layout tiled`],
+    // Stop, without the confirm-before-kill prompt tmux puts on lowercase x —
+    // this is a tile you are looking at, not a blind target.
+    ["X", "kill-pane ; select-layout tiled"],
+    // Send the focused member back to a session of its own.
+    ["B", "break-pane"],
+    // Re-tile after any manual resize.
+    ["T", "select-layout tiled"],
+  ];
+}
+
+const STATUS_LEFT = ` ${" "}#[bold]herd#[default] `;
+const STATUS_RIGHT = " S:shell  A:agent  X:stop  B:pop out  z:zoom  T:re-tile ";
+
+/**
+ * Gather every live member into one tiled window and attach to it.
+ *
+ * Members already in the tile window are left alone, so running this twice is
+ * not destructive and picks up anything started since.
+ */
+export async function herdTile(argv = [], { write = console.log, spawner = spawn, runner = spawnSync } = {}) {
+  const substrate = detectSubstrate();
+  if (substrate !== "tmux") {
+    write(err("tiling needs tmux."));
+    write(info(substrate === "pty"
+      ? "the script(1) fallback has one pty per session and no way to lay them out together — `moshcode herd ui` still works."
+      : "install tmux, or use `moshcode ps`."));
+    return 1;
+  }
+
+  const wanted = argv.find((a) => !a.startsWith("-")) || null;
+  const manifest = readManifest();
+  const panes = paneIndex({ runner });
+  const members = [...panes.entries()]
+    .filter(([name]) => name in manifest.sessions)
+    .filter(([name]) => !wanted || (manifest.sessions[name].herd || "main") === wanted);
+
+  if (!members.length) {
+    write(info("nothing to tile — start something with `moshcode herd shell` or `moshcode agents claude -d`."));
+    return 0;
+  }
+
+  // The window everything lands in. Created from the first member rather than
+  // as an empty shell, so the tile has no spare pane sitting in it doing
+  // nothing. If it already exists we just join into it.
+  const existing = tmux(["has-session", "-t", TILE_SESSION], { runner });
+  if (!existing.ok) {
+    const [firstName, first] = members[0];
+    const made = tmux(["new-session", "-d", "-s", TILE_SESSION, "-n", "herd"], { runner });
+    if (!made.ok) { write(err(made.stderr.trim() || "could not create the tile window")); return 1; }
+    tmux(["join-pane", "-s", first.paneId, "-t", `${TILE_SESSION}:herd`], { runner });
+    // new-session made a placeholder pane; the first member replaced nothing,
+    // so drop the placeholder now that there is something real beside it.
+    const inWindow = tmux(["list-panes", "-t", `${TILE_SESSION}:herd`, "-F", "#{pane_id}\t#{pane_title}"], { runner });
+    for (const line of inWindow.stdout.split("\n")) {
+      const [paneId, title] = line.split("\t");
+      if (paneId && title !== firstName && !manifest.sessions[title]) {
+        tmux(["kill-pane", "-t", paneId], { runner });
+      }
+    }
+  }
+
+  let joined = 0;
+  for (const [, pane] of members) {
+    if (pane.session === TILE_SESSION) continue; // already on the layout
+    const r = tmux(["join-pane", "-s", pane.paneId, "-t", `${TILE_SESSION}:herd`], { runner });
+    if (r.ok) joined++;
+  }
+
+  for (const [key, command] of tileBindings()) {
+    tmux(["bind-key", "-T", "prefix", key, ...command.split(" ")], { runner });
+  }
+  tmux(["set-option", "-t", TILE_SESSION, "mouse", "on"], { runner });
+  tmux(["set-option", "-t", TILE_SESSION, "pane-border-status", "top"], { runner });
+  // The border carries the member's name, so a tiled screen is readable without
+  // a legend anywhere else.
+  tmux(["set-option", "-t", TILE_SESSION, "pane-border-format", " #{pane_title} "], { runner });
+  tmux(["set-option", "-t", TILE_SESSION, "status-left-length", "20"], { runner });
+  tmux(["set-option", "-t", TILE_SESSION, "status-right-length", "80"], { runner });
+  tmux(["set-option", "-t", TILE_SESSION, "status-left", STATUS_LEFT], { runner });
+  tmux(["set-option", "-t", TILE_SESSION, "status-right", STATUS_RIGHT], { runner });
+  tmux(["select-layout", "-t", `${TILE_SESSION}:herd`, "tiled"], { runner });
+
+  write(ok(`tiling ${members.length} member${members.length === 1 ? "" : "s"}${joined ? "" : " (already laid out)"} — Ctrl-b d to leave them running`));
+
+  return new Promise((resolve) => {
+    let child;
+    try { child = spawner("tmux", ["-L", HERD_SOCKET, "attach-session", "-t", TILE_SESSION], { stdio: "inherit" }); }
+    catch (error) { write(err(String(error.message || error))); resolve(1); return; }
+    child.on("error", (error) => { write(err(String(error.message || error))); resolve(1); });
+    child.on("exit", () => {
+      write(info(`detached — everything is still running. ${acid("moshcode ps")} · ${acid("moshcode herd tile")}`));
+      resolve(0);
+    });
+  });
+}
+
+/**
+ * Put every tiled member back into a session of its own.
+ *
+ * The inverse of tiling, and worth having explicitly: a layout is a view, and
+ * anyone who wants their sessions back should not have to know that
+ * `break-pane` is the word for it.
+ */
+export function herdUntile(argv = [], { write = console.log, runner = spawnSync } = {}) {
+  if (detectSubstrate() !== "tmux") { write(err("tiling needs tmux.")); return 1; }
+  const manifest = readManifest();
+  const tiled = [...paneIndex({ runner }).entries()]
+    .filter(([name, pane]) => pane.session === TILE_SESSION && name in manifest.sessions);
+  if (!tiled.length) { write(info("nothing is tiled.")); return 0; }
+
+  // `break-pane` moves a pane into a new *window*, always in a session that
+  // already exists — its `-t` is a destination window, not a name to create.
+  // Getting a pane into a session of its own is therefore the same dance as
+  // tiling, run backwards: make the session, join the pane into it, then drop
+  // the placeholder pane the new session was born with.
+  let restored = 0;
+  for (const [name, pane] of tiled) {
+    const made = tmux(["new-session", "-d", "-s", name, "-n", name], { runner });
+    if (!made.ok) { write(err(`${name}: ${made.stderr.trim() || "could not recreate its session"}`)); continue; }
+    const placeholder = tmux(["list-panes", "-t", name, "-F", "#{pane_id}"], { runner }).stdout.trim();
+    const joined = tmux(["join-pane", "-s", pane.paneId, "-t", `${name}:${name}`], { runner });
+    if (!joined.ok) { write(err(`${name}: ${joined.stderr.trim() || "could not move it back"}`)); continue; }
+    if (placeholder) tmux(["kill-pane", "-t", placeholder], { runner });
+    restored++;
+  }
+  // Nothing is left in it, and an empty tile window on the roster is confusing.
+  tmux(["kill-session", "-t", TILE_SESSION], { runner });
+  write(ok(`${restored} member${restored === 1 ? "" : "s"} back in their own sessions.`));
+  write(info(`${ash("attach one with")} ${acid("moshcode attach <name>")}`));
+  return 0;
+}

package/src/herd-ui.mjs

@@ -121,7 +121,12 @@ export function render(rows, { selected = 0, width = 80, substrate = "tmux" } =
     out.push(`  ${ash("start something with")} ${acid("moshcode herd shell")} ${ash("or")} ${acid("moshcode agents claude -d")}`);
   }
   out.push("");
-  out.push(`  ${dim("click or ↑↓ to choose · enter to go in · r refresh · q quit")}`);
+  // Two lines, grouped by what they do, and the way *back* stated before you
+  // ever go in. The old single crammed line never mentioned it at all, so
+  // clicking into a session was a one-way door as far as the screen was
+  // concerned.
+  out.push(`  ${ash("move")}  ${dim("click · ↑↓ · wheel")}     ${ash("open")}  ${dim("enter or double-click")}`);
+  out.push(`  ${ash("back")}  ${dim("Ctrl-b d from inside")}   ${ash("also")}  ${dim("t tile all · r refresh · q quit")}`);
   if (substrate !== "tmux") out.push(`  ${dim(substrateNote(substrate) || "")}`);
   return out.join("\r\n");
 }
@@ -161,7 +166,7 @@ export function parseInput(buffer) {
     if (parsed) events.push(parsed);
   }
   if (events.length) return events;
-  for (const key of ["\x1b[A", "\x1b[B", "\r", "\n", "q", "\x03", "r", "j", "k"]) {
+  for (const key of ["\x1b[A", "\x1b[B", "\r", "\n", "q", "\x03", "r", "t", "j", "k"]) {
     if (text.includes(key)) events.push({ kind: "key", key });
   }
   return events;
@@ -268,13 +273,30 @@ export async function herdUi({
         if (event.kind === "key" && (event.key === "\x1b[A" || event.key === "k")) selected = moveSelection(rows, selected, -1);
         else if (event.kind === "key" && (event.key === "\x1b[B" || event.key === "j")) selected = moveSelection(rows, selected, 1);
         else if (event.kind === "key" && event.key === "r") { refresh(); continue; }
+        else if (event.kind === "key" && event.key === "t") {
+          // The list and the tiled layout are two views of one herd, so getting
+          // between them should not mean quitting and typing another command.
+          restore();
+          const { herdTile } = await import("./herd-tile.mjs");
+          await herdTile([], { write: (s) => process.stdout.write(`${s}\n`) });
+          if (done) return;
+          enter();
+          refresh();
+          continue;
+        }
         else if (event.kind === "wheel") selected = moveSelection(rows, selected, event.direction);
         else if (event.kind === "click") {
           const hit = rows.find((r) => r.kind === "session" && r.line === event.row);
           if (!hit) continue;
-          selected = rows.indexOf(hit);
+          const index = rows.indexOf(hit);
+          // A single click SELECTS; only a second click on the row already
+          // selected opens it. Opening on first click made one stray click a
+          // one-way trip into a session, which is most of why this felt bad to
+          // navigate — you could not point at a row to read it.
+          const opening = index === selected;
+          selected = index;
           draw();
-          await openSelected();
+          if (opening) await openSelected();
           continue;
         }
         else if (event.kind === "key") { await openSelected(); continue; }

package/src/herd-workspace.mjs

@@ -0,0 +1,292 @@
+// `moshcode herd ui` — a sidebar of members and actions, with the selected
+// member's real terminal beside it.
+//
+// This replaces the modal list, which was the wrong answer to the question.
+// The list showed you the herd OR a session and never both, so getting into one
+// was a one-way trip and nothing on the list could start or stop anything.
+//
+// HOW THE SIDEBAR SURVIVES A SWITCH. tmux's model is session > window > pane,
+// and a pane belongs to exactly one window — which is why moving between
+// *windows* cannot keep anything on screen. But `join-pane` moves a running
+// pane into an existing window, so swapping only the *content* pane leaves the
+// sidebar untouched. Selecting a member parks the current content pane back
+// into a session of its own and joins the new one in; both keep their processes
+// and their scrollback, because tmux is moving the real pane rather than
+// redrawing a picture of it.
+//
+// Two processes, therefore: the launcher below builds the window and attaches,
+// and `herdSidebar` is what runs *inside* the left pane doing the swapping.
+import { spawn, spawnSync } from "node:child_process";
+
+import { HERD_SOCKET, detectSubstrate, paneIndex, readManifest, tmux } from "./herd.mjs";
+import { roster } from "./herd-cli.mjs";
+import { groupByHerd, parseInput } from "./herd-ui.mjs";
+import { acid, amber, ash, bone, danger, dim, err, info, ok } from "./ui.mjs";
+
+export const WORKSPACE = "herd";
+export const WINDOW = "ui";
+export const TARGET = `${WORKSPACE}:${WINDOW}`;
+const SIDEBAR_WIDTH = 26;
+
+/** The rows in the sidebar that are not members. */
+export const ACTIONS = [
+  { key: "s", label: "+ shell", run: "shell" },
+  { key: "a", label: "+ agent", run: "agent" },
+  { key: "x", label: "✕ stop", run: "stop" },
+  { key: "t", label: "⊞ tile all", run: "tile" },
+  { key: "q", label: "← detach", run: "detach" },
+];
+
+/* -------------------------------------------------------------- the layout */
+
+/**
+ * Build the window and attach to it.
+ *
+ * Falls back to the plain list where there is no tmux, because the swap this
+ * is built on is a tmux operation and the script(1) substrate has one pty per
+ * session with no way to put two of them side by side.
+ */
+export async function herdUi(argv = [], { write = console.log, spawner = spawn, runner = spawnSync } = {}) {
+  const substrate = detectSubstrate();
+  if (substrate !== "tmux") {
+    const { herdUi: list } = await import("./herd-ui.mjs");
+    return list({});
+  }
+
+  const existing = tmux(["has-session", "-t", WORKSPACE], { runner });
+  if (!existing.ok) {
+    const self = process.argv[1];
+    const sidebar = `${process.execPath} ${self} herd sidebar`;
+    const made = tmux(["new-session", "-d", "-s", WORKSPACE, "-n", WINDOW, sidebar], { runner });
+    if (!made.ok) { write(err(made.stderr.trim() || "could not open the workspace")); return 1; }
+    // The sidebar is the "main" pane of a main-vertical layout, which is what
+    // pins it to the left at a fixed width while the content pane takes the
+    // rest and follows the terminal when it resizes.
+    tmux(["set-option", "-t", WORKSPACE, "main-pane-width", String(SIDEBAR_WIDTH)], { runner });
+    tmux(["set-option", "-t", WORKSPACE, "mouse", "on"], { runner });
+    tmux(["set-option", "-t", WORKSPACE, "status", "off"], { runner });
+    tmux(["set-option", "-t", WORKSPACE, "pane-border-status", "top"], { runner });
+    tmux(["set-option", "-t", WORKSPACE, "pane-border-format", " #{pane_title} "], { runner });
+    tmux(["select-pane", "-t", `${TARGET}.0`, "-T", "herd"], { runner });
+  }
+
+  return new Promise((resolve) => {
+    let child;
+    try { child = spawner("tmux", ["-L", HERD_SOCKET, "attach-session", "-t", WORKSPACE], { stdio: "inherit" }); }
+    catch (error) { write(err(String(error.message || error))); resolve(1); return; }
+    child.on("error", (error) => { write(err(String(error.message || error))); resolve(1); });
+    child.on("exit", () => {
+      write(info(`detached — everything is still running. ${acid("moshcode ps")} · ${acid("moshcode herd ui")}`));
+      resolve(0);
+    });
+  });
+}
+
+/* ------------------------------------------------------------- the swapping */
+
+/** The content pane currently on the right, if there is one. */
+export function contentPane({ runner = spawnSync, me = process.env.TMUX_PANE } = {}) {
+  const r = tmux(["list-panes", "-t", TARGET, "-F", "#{pane_id}\t#{pane_title}"], { runner });
+  if (!r.ok) return null;
+  for (const line of r.stdout.split("\n")) {
+    const [paneId, title] = line.split("\t");
+    if (!paneId || paneId === me) continue;
+    return { paneId, title };
+  }
+  return null;
+}
+
+/**
+ * Send a pane back to a session of its own.
+ *
+ * `break-pane` cannot do this: its `-t` is a destination window that has to
+ * exist already, not a name to create. So it is the join dance backwards —
+ * make the session, move the pane in, drop the placeholder the session was
+ * born with.
+ */
+export function parkPane(paneId, name, { runner = spawnSync } = {}) {
+  if (!name) return false;
+  const made = tmux(["new-session", "-d", "-s", name, "-n", name], { runner });
+  if (!made.ok && !/duplicate session/i.test(made.stderr || "")) return false;
+  const placeholder = made.ok
+    ? tmux(["list-panes", "-t", name, "-F", "#{pane_id}"], { runner }).stdout.trim().split("\n")[0]
+    : null;
+  const joined = tmux(["join-pane", "-s", paneId, "-t", `${name}:${name}`], { runner });
+  if (!joined.ok) return false;
+  if (placeholder) tmux(["kill-pane", "-t", placeholder], { runner });
+  return true;
+}
+
+/** Put `name` in the content pane, parking whatever was there. */
+export function showMember(name, { runner = spawnSync, me = process.env.TMUX_PANE } = {}) {
+  const current = contentPane({ runner, me });
+  if (current?.title === name) return true; // already showing
+  const panes = paneIndex({ runner });
+  const wanted = panes.get(name);
+  if (!wanted) return false;
+
+  if (current) parkPane(current.paneId, current.title, { runner });
+  const joined = tmux(["join-pane", "-s", wanted.paneId, "-t", TARGET], { runner });
+  if (!joined.ok) return false;
+  tmux(["select-layout", "-t", TARGET, "main-vertical"], { runner });
+  // main-vertical resets the main pane's width from the option, so re-assert it
+  // after every swap or the sidebar creeps wider each time.
+  tmux(["set-option", "-t", WORKSPACE, "main-pane-width", String(SIDEBAR_WIDTH)], { runner });
+  tmux(["select-pane", "-t", me], { runner });
+  return true;
+}
+
+/* --------------------------------------------------------------- the render */
+
+const MARK = { blocked: "!", working: "~", done: "✓", idle: "·", gone: "×", unknown: "?" };
+const paintState = (state, text) =>
+  state === "blocked" ? amber(text)
+  : state === "working" ? acid(text)
+  : state === "done" ? bone(text)
+  : state === "gone" ? danger(text)
+  : ash(text);
+
+/**
+ * The sidebar's rows, and the line each one sits on — one list so a click and
+ * the highlight cannot disagree (the bug that made the first list send every
+ * click to the row below the pointer).
+ */
+export function sidebarRows(sessions) {
+  const rows = [{ kind: "title" }, { kind: "gap" }];
+  for (const group of groupByHerd(sessions)) {
+    rows.push({ kind: "herd", herd: group.name });
+    for (const session of group.members) rows.push({ kind: "session", session });
+  }
+  rows.push({ kind: "gap" }, { kind: "heading", text: "ACTIONS" });
+  for (const action of ACTIONS) rows.push({ kind: "action", action });
+  return rows.map((row, i) => ({ ...row, line: i + 1 }));
+}
+
+export function renderSidebar(rows, { selected, showing, width = SIDEBAR_WIDTH } = {}) {
+  const out = [];
+  for (const row of rows) {
+    if (row.kind === "title") { out.push(` ${bone("herd")}`); continue; }
+    if (row.kind === "gap") { out.push(""); continue; }
+    if (row.kind === "heading") { out.push(` ${ash(row.text)}`); continue; }
+    if (row.kind === "herd") { out.push(` ${ash(row.herd.toUpperCase())}`); continue; }
+    if (row.kind === "session") {
+      const s = row.session;
+      const here = s.name === showing ? acid("▸") : " ";
+      const label = s.name.slice(0, width - 7);
+      const text = s.name === selected ? bone(label) : ash(label);
+      out.push(`${here} ${paintState(s.state, MARK[s.state] || "?")} ${text}`);
+      continue;
+    }
+    const isSel = row.action.key === selected;
+    out.push(`  ${isSel ? bone(row.action.label) : ash(row.action.label)}`);
+  }
+  return out.join("\r\n");
+}
+
+/* -------------------------------------------------------- the sidebar itself */
+
+/**
+ * Runs inside the left pane. Draws the list, and turns a click into a swap.
+ *
+ * It does not take the alternate screen: it *is* a pane, and the pane is the
+ * screen. Mouse reporting is enabled for this program specifically, which tmux
+ * forwards rather than consuming once an application asks for it.
+ */
+export async function herdSidebar({
+  stdin = process.stdin, stdout = process.stdout, read = roster, refreshMs = 2000, runner = spawnSync,
+} = {}) {
+  const me = process.env.TMUX_PANE;
+  let sessions = read();
+  let rows = sidebarRows(sessions);
+  let selected = sessions[0]?.name || ACTIONS[0].key;
+  let showing = null;
+
+  const draw = () => {
+    stdout.write("\x1b[2J\x1b[H" + renderSidebar(rows, { selected, showing }));
+  };
+  const refresh = () => {
+    sessions = read();
+    rows = sidebarRows(sessions);
+    const current = contentPane({ runner, me });
+    showing = current?.title || null;
+    draw();
+  };
+
+  // Open on something rather than an empty right-hand side.
+  const first = sessions.find((s) => s.alive);
+  if (first) { showMember(first.name, { runner, me }); showing = first.name; }
+
+  stdout.write("\x1b[?1000h\x1b[?1006h\x1b[?25l");
+  try { stdin.setRawMode?.(true); } catch { /* not a tty */ }
+  stdin.resume();
+  const restore = () => stdout.write("\x1b[?1006l\x1b[?1000l\x1b[?25h");
+  process.on("exit", restore);
+
+  draw();
+  const timer = setInterval(refresh, refreshMs);
+
+  const act = async (what) => {
+    if (what === "detach") { tmux(["detach-client"], { runner }); return; }
+    if (what === "tile") {
+      const { herdTile } = await import("./herd-tile.mjs");
+      await herdTile([], { write: () => {}, spawner: () => ({ on: (e, cb) => e === "exit" && cb(0) }) });
+      refresh();
+      return;
+    }
+    if (what === "stop") {
+      const target = sessions.find((s) => s.name === selected);
+      if (!target) return;
+      const { killSession } = await import("./herd.mjs");
+      killSession(target.name);
+      refresh();
+      const next = read().find((s) => s.alive);
+      if (next) { showMember(next.name, { runner, me }); }
+      refresh();
+      return;
+    }
+    // shell / agent: start it detached, then bring it into the content pane so
+    // the thing you just asked for is the thing you are looking at.
+    const { herdShell, herdStart } = await import("./herd-cli.mjs");
+    let created = null;
+    const capture = (line) => { const m = /^\S*\s*(\S+)\s+—/.exec(String(line).replace(/\x1b\[[0-9;]*m/g, "")); if (m) created = m[1]; };
+    if (what === "shell") herdShell([], { write: capture });
+    else herdStart(["claude", "--agent"], { write: capture });
+    refresh();
+    if (created) { showMember(created, { runner, me }); refresh(); }
+  };
+
+  await new Promise((resolve) => {
+    stdin.on("data", async (buf) => {
+      for (const event of parseInput(buf)) {
+        if (event.kind === "click") {
+          const hit = rows.find((r) => r.line === event.row && (r.kind === "session" || r.kind === "action"));
+          if (!hit) continue;
+          if (hit.kind === "session") {
+            selected = hit.session.name;
+            if (hit.session.alive) { showMember(hit.session.name, { runner, me }); showing = hit.session.name; }
+            draw();
+          } else {
+            selected = hit.action.key;
+            draw();
+            await act(hit.action.run);
+          }
+          continue;
+        }
+        if (event.kind !== "key") continue;
+        const action = ACTIONS.find((a) => a.key === event.key);
+        if (action) { await act(action.run); if (action.run === "detach") { resolve(); return; } continue; }
+        if (event.key === "\x03") { resolve(); return; }
+        const names = sessions.filter((s) => s.alive).map((s) => s.name);
+        const at = names.indexOf(selected);
+        if (event.key === "\x1b[A" || event.key === "k") selected = names[Math.max(0, at - 1)] || selected;
+        if (event.key === "\x1b[B" || event.key === "j") selected = names[Math.min(names.length - 1, at + 1)] || selected;
+        if (event.key === "\r" || event.key === "\n") { showMember(selected, { runner, me }); showing = selected; }
+        draw();
+      }
+    });
+  });
+
+  clearInterval(timer);
+  restore();
+  return 0;
+}

package/src/herd.mjs

@@ -261,6 +261,11 @@ export function tmuxStartPlan({ name, cwd, command }) {
     // clickable once you are inside. This server is moshcode's and starts from
     // no config, so it is not overriding a preference anyone expressed.
     ";", "set-option", "-t", name, "mouse", "on",
+    // The pane's title is the member's durable handle — it survives being
+    // moved into a tiled window and back, which the session name does not.
+    // Set in the same invocation as the rest so a fast-exiting command cannot
+    // finish before it lands.
+    ";", "select-pane", "-t", name, "-T", name,
   ];
 }
 
@@ -420,9 +425,11 @@ function ptyWrite(name, data) {
 /** Names the substrate says are live right now. */
 export function liveNames({ substrate = detectSubstrate(), runner = spawnSync } = {}) {
   if (substrate === "tmux") {
-    const r = tmux(["list-sessions", "-F", "#{session_name}"], { runner });
-    if (!r.ok) return []; // no server yet is not an error, it is an empty herd
-    return r.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+    // Panes, not sessions: a tiled member's session is gone but the member is
+    // very much alive. Only names the manifest knows about count, so a stray
+    // pane title on the server cannot invent a roster entry.
+    const known = new Set(Object.keys(readManifest().sessions));
+    return [...paneIndex({ runner }).keys()].filter((name) => known.has(name));
   }
   if (substrate === "pty") {
     // A finished session is still one the runtime has: it stays on the roster
@@ -463,6 +470,42 @@ export function sessionExited(name, { substrate = detectSubstrate(), runner = sp
  * meant a fork per field per row, so a herd of six cost thirteen processes to
  * draw one screen. tmux will format the whole server in one pass.
  */
+/**
+ * Where every member's pane actually is, keyed by member name.
+ *
+ * A member is a *pane*, not a session. It starts life as the only pane in a
+ * session of the same name, but `herd tile` moves panes into one window to lay
+ * them out side by side — and a session whose last pane leaves is gone. Keying
+ * off session names would make every tiled member vanish from the roster, from
+ * `read`, from `prompt` and from `wait`, which is a steep price for a layout.
+ *
+ * The pane's *title* is the durable handle: it is set at creation, it travels
+ * with the pane through join-pane and break-pane, and tmux will report it from
+ * anywhere on the server.
+ */
+export function paneIndex({ runner = spawnSync } = {}) {
+  const r = tmux(["list-panes", "-a", "-F", "#{pane_title}\t#{pane_id}\t#{session_name}\t#{window_id}\t#{pane_dead}"], { runner });
+  const index = new Map();
+  if (!r.ok) return index;
+  for (const line of r.stdout.split("\n")) {
+    if (!line.trim()) continue;
+    const [title, paneId, session, windowId, dead] = line.split("\t");
+    if (!title) continue;
+    index.set(title, { paneId, session, windowId, dead: dead.trim() === "1" });
+  }
+  return index;
+}
+
+/**
+ * The tmux target for a member: its pane id when we can find one, else its
+ * session name. The fallback matters for a session created before pane titles
+ * were set, which would otherwise become unreachable after an upgrade.
+ */
+export function target(name, { runner = spawnSync, index } = {}) {
+  const found = (index || paneIndex({ runner })).get(name);
+  return found ? found.paneId : name;
+}
+
 function tmuxSnapshot({ runner = spawnSync } = {}) {
   const sessions = tmux(["list-sessions", "-F", "#{session_name}\t#{session_attached}"], { runner });
   const attached = new Map();
@@ -540,7 +583,7 @@ export function startSession({
 /** The last `lines` rows of a session's screen — what the classifier reads. */
 export function capture(name, { lines = 60, substrate = detectSubstrate(), runner = spawnSync } = {}) {
   if (substrate === "tmux") {
-    const r = tmux(["capture-pane", "-p", "-t", name, "-S", `-${Math.max(0, lines)}`], { runner });
+    const r = tmux(["capture-pane", "-p", "-t", target(name, { runner }), "-S", `-${Math.max(0, lines)}`], { runner });
     return r.ok ? r.stdout.replace(/\n+$/, "") : "";
   }
   if (substrate === "pty") return ptyCapture(name, lines);
@@ -550,7 +593,7 @@ export function capture(name, { lines = 60, substrate = detectSubstrate(), runne
 /** Raw key relay. `keys` is passed through to tmux's own key vocabulary. */
 export function sendKeys(name, keys, { substrate = detectSubstrate(), runner = spawnSync } = {}) {
   if (substrate === "tmux") {
-    const r = tmux(["send-keys", "-t", name, ...(Array.isArray(keys) ? keys : [keys])], { runner });
+    const r = tmux(["send-keys", "-t", target(name, { runner }), ...(Array.isArray(keys) ? keys : [keys])], { runner });
     return r.ok ? { ok: true } : { ok: false, error: new Error(r.stderr.trim() || "send-keys failed") };
   }
   if (substrate === "pty") {
@@ -571,9 +614,10 @@ export function sendKeys(name, keys, { substrate = detectSubstrate(), runner = s
  */
 export function sendPrompt(name, text, { substrate = detectSubstrate(), runner = spawnSync } = {}) {
   if (substrate === "tmux") {
-    const typed = tmux(["send-keys", "-t", name, "-l", String(text)], { runner });
+    const pane = target(name, { runner });
+    const typed = tmux(["send-keys", "-t", pane, "-l", String(text)], { runner });
     if (!typed.ok) return { ok: false, error: new Error(typed.stderr.trim() || "send-keys failed") };
-    const entered = tmux(["send-keys", "-t", name, "Enter"], { runner });
+    const entered = tmux(["send-keys", "-t", pane, "Enter"], { runner });
     return entered.ok ? { ok: true } : { ok: false, error: new Error(entered.stderr.trim() || "send-keys failed") };
   }
   if (substrate === "pty") return ptyWrite(name, `${String(text)}\r`);
@@ -583,7 +627,9 @@ export function sendPrompt(name, text, { substrate = detectSubstrate(), runner =
 /** End a session and forget it. */
 export function killSession(name, { substrate = detectSubstrate(), runner = spawnSync } = {}) {
   if (substrate === "tmux") {
-    const r = tmux(["kill-session", "-t", name], { runner });
+    // kill-pane, not kill-session: a tiled member shares its session with
+    // every other tiled member, and killing that would take the lot.
+    const r = tmux(["kill-pane", "-t", target(name, { runner })], { runner });
     forgetSession(name);
     return r.ok ? { ok: true } : { ok: false, error: new Error(r.stderr.trim() || "no such session") };
   }
@@ -630,9 +676,19 @@ export async function attachSession(name, {
   stdout = process.stdout,
 } = {}) {
   if (substrate === "tmux") {
+    // A member that has been tiled shares a window with its neighbours, so
+    // attaching has to select its pane and zoom it — otherwise you land on
+    // whichever pane happened to have focus, at a quarter of the screen.
+    const found = paneIndex().get(name);
+    const argv = found
+      ? ["attach-session", "-t", found.session,
+         ";", "select-window", "-t", found.windowId,
+         ";", "select-pane", "-t", found.paneId,
+         ";", "resize-pane", "-Z", "-t", found.paneId]
+      : ["attach-session", "-t", name];
     return new Promise((resolve) => {
       let child;
-      try { child = spawner("tmux", tmuxArgs(["attach-session", "-t", name]), { stdio: "inherit", env }); }
+      try { child = spawner("tmux", tmuxArgs(argv), { stdio: "inherit", env }); }
       catch (error) { resolve({ ok: false, error }); return; }
       child.on("error", (error) => resolve({ ok: false, error }));
       child.on("exit", (code, signal) => resolve({ ok: code === 0, code, signal }));
@@ -726,14 +782,17 @@ export function ptyAttachSession(name, { stdin = process.stdin, stdout = process
  */
 export function listSessions({ substrate = detectSubstrate(), runner = spawnSync, now = Date.now() } = {}) {
   const manifest = readManifest();
+  const panes = substrate === "tmux" ? paneIndex({ runner }) : null;
   const snapshot = substrate === "tmux" ? tmuxSnapshot({ runner }) : null;
-  const live = new Set(snapshot ? snapshot.attached.keys() : liveNames({ substrate, runner }));
+  const live = new Set(panes
+    ? [...panes.keys()].filter((name) => name in manifest.sessions)
+    : liveNames({ substrate, runner }));
   const names = [...new Set([...live, ...Object.keys(manifest.sessions)])].sort();
   return names.map((name) => {
     const meta = manifest.sessions[name] || {};
     const alive = live.has(name);
     const exited = !alive ? null
-      : snapshot ? !snapshot.anyLive.get(name)
+      : panes ? Boolean(panes.get(name)?.dead)
       : sessionExited(name, { substrate, runner });
     return {
       name,
@@ -746,7 +805,11 @@ export function listSessions({ substrate = detectSubstrate(), runner = spawnSync
       age: meta.created ? now - meta.created : null,
       alive,
       exited,
-      attached: alive && snapshot ? snapshot.attached.get(name) || 0 : 0,
+      // Where it currently sits — null when it is in its own session, the
+      // window it was tiled into otherwise. The UI needs this to know whether
+      // a member is already on a layout somewhere.
+      window: alive && panes ? panes.get(name)?.windowId || null : null,
+      attached: alive && snapshot ? snapshot.attached.get(panes?.get(name)?.session) || 0 : 0,
       substrate: meta.substrate || substrate,
     };
   });