moshcode 0.33.1 → 0.35.0

package/README.md

@@ -125,6 +125,78 @@ moshcode attach api                      # step in; Ctrl-b d steps back out
 moshcode kill api                        # end it
 ```
 
+### The clickable list
+
+```sh
+moshcode herd ui
+```
+
+```
+  moshcode herd   3 members   1 waiting on you
+
+  MAIN (2)
+   ▸ ! api          claude     blocked  ~/src/coinpay
+     · work         shell      idle     ~/src/coinpay
+
+  SCRATCH (1)
+     · logs         shell      idle     ~/src/ugig.net
+
+  click or ↑↓ to choose · enter to go in · r refresh · q quit
+```
+
+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`.
+
+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.
+
+### A workspace: a few shells and an agent
+
+This is what most people actually want — a couple of shells to work in and an
+agent or two running beside them, none of which die when the terminal does:
+
+```sh
+cd ~/src/coinpay
+moshcode herd shell --name work          # a plain $SHELL
+moshcode herd shell --name logs          # another
+moshcode agents claude -d --name api     # and an agent
+```
+
+```sh
+$ moshcode ps
+  api    claude  blocked   ~/src/coinpay   3m
+  logs   shell   idle      ~/src/coinpay   3m
+  work   shell   idle      ~/src/coinpay   3m
+
+⚠ 1 waiting on you — moshcode attach api
+```
+
+`moshcode attach work` puts you in one; `Ctrl-b s` hops between all three;
+`Ctrl-b d` leaves the lot running. Close the laptop and they are still there.
+
+### Agents moshcode does not ship
+
+`start` only knows the engines moshcode installs. `run` takes anything —
+an agent with no install spec here, a build, a script:
+
+```sh
+moshcode herd run --name cur -- cursor-agent
+moshcode herd run --name build -- npm run watch
+```
+
+Everything after `--` is the command, flags and all. These get a roster entry
+and the same state detection as a known engine: the shared rules match what a
+terminal *draws* — a y/n prompt, a numbered menu, "esc to interrupt" — not
+anything engine-specific, so an agent moshcode has never heard of still shows up
+`blocked` when it stops to ask you something.
+
 Close the terminal, drop the SSH link, come back tomorrow — `moshcode ps` still
 answers, and `moshcode attach` puts you back inside. In the pit the same verbs
 are `/ps`, `/attach`, `/kill`, and the roster prints on the way in.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moshcode",
-  "version": "0.33.1",
+  "version": "0.35.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

@@ -79,12 +79,27 @@ export const CORE_CLI_COMMANDS = [
     verbs: "HERD_VERBS",
     flags: [["--json", "machine-readable, on every verb", ""]],
     examples: [
-      ["moshcode herd start claude --name api", "start one and get your prompt back"],
-      ["moshcode herd prompt api \"run the tests\" --wait", "hand it work and block until it lands"],
-      ["moshcode herd read api --lines 40", "read its screen without attaching"],
+      ["moshcode herd ui", "the clickable list — start here"],
+      ["", ""],
+      ["# a workspace: two shells and an agent, none of which die with this terminal", ""],
+      ["moshcode herd shell --name work", "a plain $SHELL you can come back to"],
+      ["moshcode herd shell --name logs", "another one"],
+      ["moshcode agents claude -d --name api", "an agent, detached"],
+      ["moshcode ps", "all three, and which one is blocked"],
+      ["moshcode attach api", "step in · Ctrl-b s switches · Ctrl-b d leaves it running"],
+      ["", ""],
+      ["# an agent moshcode has no install spec for", ""],
+      ["moshcode herd run --name cur -- cursor-agent", "anything at all runs in the herd"],
+      ["", ""],
+      ["# driving one without attaching", ""],
+      ["moshcode herd prompt api \"run the tests\" --wait", "hand it work, block until it lands"],
+      ["moshcode herd read api --lines 40", "read its screen"],
     ],
     seeAlso: ["ps", "attach", "wait", "restore", "start"],
-    note: "sessions live in a tmux server moshcode owns, or under script(1) when there is no tmux. with neither, launches stay in the foreground and say so.",
+    note: "`start` is for the engines moshcode installs; `run` and `shell` take anything else, "
+      + "so an agent it has never heard of still gets a roster entry and blocked/idle detection. "
+      + "sessions live in a tmux server moshcode owns, or under script(1) when there is no tmux. "
+      + "with neither, launches stay in the foreground and say so.",
   },
   {
     name: "ps",
@@ -723,6 +738,19 @@ 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: "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: [
+      ["--name <slug>", "session name", "<command>-<dir>"],
+      ["--cwd <dir>", "where to run it", "this directory"],
+      ["--json", "machine-readable", ""],
+    ] },
+  { name: "shell", description: "a plain $SHELL in the herd",
+    synopsis: [["moshcode herd shell [--name <slug>]", ""]],
+    flags: [["--name <slug>", "session name", "shell-<dir>"], ["--cwd <dir>", "where to run it", "this directory"]] },
   { name: "attach", description: "put this terminal inside a session",
     synopsis: [["moshcode herd attach <name>", ""]] },
   { name: "kill", description: "end a session",

package/src/help.mjs

@@ -167,7 +167,11 @@ export function wrap(text, indent = 0, width = WIDTH) {
 
 /** `  name        description`, wrapped, for a two-column list. */
 function row(left, right, pad = 22) {
-  const head = `  ${left.padEnd(pad)}`;
+  // padEnd does nothing when the left column is already wider than the pad, so
+  // a long example used to butt straight against its comment:
+  // `… "run the tests" --wait# hand it work`. One guaranteed space keeps the
+  // two readable however long the command gets.
+  const head = left.length >= pad ? `  ${left} ` : `  ${left.padEnd(pad)}`;
   if (!right) return head.trimEnd();
   const wrapped = wrap(right, head.length, WIDTH);
   return `${head}${wrapped}`;

package/src/herd-cli.mjs

@@ -11,7 +11,7 @@ import path from "node:path";
 import {
   attachSession, capture, defaultName, detectSubstrate, forgetSession, HERD_SOCKET,
   herdDir, killSession, listSessions, readManifest, rememberSession, sendKeys, sendPrompt,
-  startSession, stopRuntime, substrateNote, validName, NAME_RE,
+  slugifyName, startSession, stopRuntime, substrateNote, validName, NAME_RE,
 } from "./herd.mjs";
 import { clearReport, reportState, STATES, withState } from "./herd-state.mjs";
 import { ENGINES, resolveEngine, resolveExecutable, agentLaunchArgs } from "./engines.mjs";
@@ -130,13 +130,15 @@ export function herdStart(argv, { write = console.log } = {}) {
   const substrate = requireSubstrate(write);
   if (!substrate) return EXIT.usage;
 
-  const flags = { name: null, cwd: process.cwd(), agent: false, json: false };
+  const flags = { name: null, cwd: process.cwd(), agent: false, json: false, herd: "main" };
   const rest = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--name") flags.name = argv[++i];
     else if (a.startsWith("--name=")) flags.name = a.slice(7);
     else if (a === "--cwd") flags.cwd = path.resolve(argv[++i] || ".");
+    else if (a === "--herd") flags.herd = slugifyName(argv[++i]);
+    else if (a.startsWith("--herd=")) flags.herd = slugifyName(a.slice(7));
     else if (a === "--agent") flags.agent = true;
     else if (a === "--json") flags.json = true;
     else rest.push(a);
@@ -168,10 +170,10 @@ export function herdStart(argv, { write = console.log } = {}) {
     write(err(String(started.error?.message || started.error)));
     return EXIT.usage;
   }
-  rememberSession(name, { agent: flags.agent });
+  rememberSession(name, { agent: flags.agent, herd: flags.herd });
 
   if (flags.json) {
-    write(JSON.stringify({ name, engine: key, cwd: flags.cwd, substrate, agent: flags.agent }, null, 2));
+    write(JSON.stringify({ name, engine: key, herd: flags.herd, cwd: flags.cwd, substrate, agent: flags.agent }, null, 2));
     return EXIT.matched;
   }
   write(ok(`${bone(name)} — ${key} running in the herd. the prompt is yours.`));
@@ -182,6 +184,82 @@ export function herdStart(argv, { write = console.log } = {}) {
   return EXIT.matched;
 }
 
+/**
+ * Run anything at all in the herd — a shell, or an agent moshcode does not ship
+ * an install spec for.
+ *
+ * `herd start` is deliberately limited to the engines in ENGINES, because it
+ * does engine-specific things: agent-mode flags, env stripping, resume args.
+ * That made the herd useless for the two most common things people actually
+ * want in it — a couple of shells, and whichever agent they use that moshcode
+ * has never heard of (cursor-agent, copilot, amp, a local script).
+ *
+ * So this is the escape hatch, and it is the same model herdr uses: a session
+ * holds a process, and an agent is just a process we happen to recognise.
+ * Detection still works, because the shared rules in herd-state.mjs match what
+ * a terminal draws — a y/n prompt, a numbered menu, "esc to interrupt" — rather
+ * than anything engine-specific. An unknown agent that stops to ask a question
+ * shows up `blocked` without moshcode knowing what it is.
+ */
+export function herdRun(argv, { write = console.log, shell = false } = {}) {
+  const substrate = requireSubstrate(write);
+  if (!substrate) return EXIT.usage;
+
+  const flags = { name: null, cwd: process.cwd(), json: false, herd: "main" };
+  const command = [];
+  let afterSeparator = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (afterSeparator) { command.push(a); continue; }
+    // Everything after `--` belongs to the command, flags included — otherwise
+    // `herd run -- claude --json` would have its --json eaten by us.
+    if (a === "--") { afterSeparator = true; }
+    else if (a === "--name") flags.name = argv[++i];
+    else if (a.startsWith("--name=")) flags.name = a.slice(7);
+    else if (a === "--cwd") flags.cwd = path.resolve(argv[++i] || ".");
+    else if (a === "--herd") flags.herd = slugifyName(argv[++i]);
+    else if (a.startsWith("--herd=")) flags.herd = slugifyName(a.slice(7));
+    else if (a === "--json") flags.json = true;
+    else command.push(a);
+  }
+
+  if (shell && !command.length) {
+    command.push(process.env.SHELL || (process.platform === "win32" ? "cmd.exe" : "/bin/sh"));
+  }
+  if (!command.length) {
+    write(err('usage: moshcode herd run [--name <slug>] -- <command…>'));
+    write(info(`e.g. ${acid('moshcode herd run --name build -- npm run watch')}`));
+    return EXIT.usage;
+  }
+
+  const [bin, ...args] = command;
+  const label = shell ? "shell" : path.basename(bin);
+  const taken = listSessions().map((s) => s.name);
+  const name = flags.name || defaultName(slugifyName(label), flags.cwd, taken);
+  if (!validName(name)) {
+    write(err(`invalid name ${JSON.stringify(name)} — must match ${NAME_RE}`));
+    return EXIT.usage;
+  }
+
+  const started = startSession({ name, engine: label, bin, args, cwd: flags.cwd, substrate });
+  if (!started.ok) {
+    write(err(String(started.error?.message || started.error)));
+    return EXIT.usage;
+  }
+  rememberSession(name, { herd: flags.herd });
+
+  if (flags.json) {
+    write(JSON.stringify({ name, engine: label, herd: flags.herd, cwd: flags.cwd, substrate }, null, 2));
+    return EXIT.matched;
+  }
+  write(ok(`${bone(name)} — ${label} running in the herd. the prompt is yours.`));
+  write(info(`attach: ${acid(`moshcode attach ${name}`)} · roster: ${acid("moshcode ps")}`));
+  return EXIT.matched;
+}
+
+/** A plain $SHELL in the herd — the common case of herdRun. */
+export const herdShell = (argv, options = {}) => herdRun(argv, { ...options, shell: true });
+
 /**
  * Pull the herd flags out of an engine launch (PRD 0009 R3).
  *
@@ -208,8 +286,8 @@ export function splitDetachArgs(args = []) {
 export function herdPs(argv, { write = console.log } = {}) {
   const rows = roster();
   if (argv.includes("--json")) {
-    write(JSON.stringify(rows.map(({ name, engine, state, authority, cwd, age, alive, attached, substrate }) => ({
-      name, engine, state, authority, cwd, ageMs: age, alive, attached, substrate,
+    write(JSON.stringify(rows.map(({ name, engine, herd, state, authority, cwd, age, alive, attached, substrate }) => ({
+      name, engine, herd, state, authority, cwd, ageMs: age, alive, attached, substrate,
     })), null, 2));
     return EXIT.matched;
   }
@@ -645,8 +723,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),
   ps: herdPs, list: herdPs, status: herdStatus,
-  start: herdStart, attach: herdAttach, kill: herdKill, prune: herdPrune,
+  start: herdStart, run: herdRun, shell: herdShell,
+  attach: herdAttach, kill: herdKill, prune: herdPrune,
   read: herdRead, prompt: herdPrompt, "send-keys": herdSendKeys,
   wait: herdWait, restore: herdRestore, report: herdReport,
   notify: herdNotify, watch: herdWatch, stop: herdStop,

package/src/herd-state.mjs

@@ -80,7 +80,25 @@ export const COMMON_RULES = {
     /\bctrl\+c to (?:stop|cancel|interrupt)\b/i,
     /\bpress esc to cancel\b/i,
   ],
-  idle: [],
+  // A prompt sitting at the very end of the screen, waiting for a keystroke —
+  // a shell's `$`, a root `#`, zsh/starship's `❯`/`➜`, an agent's `>` composer.
+  // Anchored to the end of the *capture* rather than to any line, because a `$`
+  // in the middle of output is a dollar sign and not an invitation.
+  //
+  // Checked after blocked and working, so the cost of a false positive is only
+  // `idle` where `unknown` was already the honest answer. This is what stops a
+  // couple of shells in the herd reading `unknown` forever.
+  idle: [
+    // The glyph last: `… $`, `… #`, `… ❯`.
+    /[$%#>❯➜»]\s*$/,
+    // The glyph first, with the path after it: `➜  ~/src/api `, which is what
+    // zsh and starship actually draw. Restricted to ❯ and ➜ because those are
+    // prompt characters and almost nothing else; `>` and `#` in that position
+    // are markdown quotes and headings, which agents print all the time.
+    // Claude Code's `❯ 2. Dark mode` selector reaches the blocked rule first,
+    // so a menu still reads blocked rather than idle.
+    /(?:^|\n)[^\n]*[❯➜][^\n]*$/,
+  ],
 };
 
 /**

package/src/herd-ui.mjs

@@ -0,0 +1,296 @@
+// `moshcode herd ui` — the clickable list of herds and their members.
+//
+// The roster answers "what is running" in a line each, which is right for a
+// pipe and wrong for a person with five sessions who wants to get into one of
+// them. This is the same information as a place you can point at: herds as
+// headings, members under them, click one to go in, detach to come back.
+//
+// WHY THIS AND NOT A SIDEBAR. tmux's model is session > window > pane, and a
+// pane belongs to exactly one window — so nothing can stay on screen across a
+// switch. A list pinned beside a live session is therefore impossible with tmux
+// underneath, and doing it anyway would mean rendering every session ourselves
+// from `capture-pane` polls: no real cursor, no real mouse inside the agent,
+// full-screen UIs flickering at the refresh rate. That is rebuilding herdr, and
+// worse. So this list hands the whole terminal to a *real* attach and takes it
+// back on detach — you lose side-by-side, you keep a real terminal.
+//
+// No dependencies, for the same reason as everything else here: moshcode
+// installs by untarring a release and running node. Alternate screen, SGR mouse
+// reporting and raw-mode keys are a few escape sequences, and every one of them
+// is undone in a single restore path so a crash cannot leave a terminal with no
+// cursor and the mouse captured.
+import { attachSession, detectSubstrate, substrateNote } from "./herd.mjs";
+import { roster } from "./herd-cli.mjs";
+import { acid, amber, ash, bone, danger, dim } from "./ui.mjs";
+
+/** The herd a session has no opinion about. */
+export const DEFAULT_HERD = "main";
+
+const ESC = {
+  altOn: "\x1b[?1049h", altOff: "\x1b[?1049l",
+  hideCursor: "\x1b[?25l", showCursor: "\x1b[?25h",
+  // 1000 = report button press/release, 1006 = SGR encoding, which is the only
+  // one that survives past column 95 — the older scheme packs coordinates into
+  // single bytes and simply cannot express a click on a wide terminal.
+  mouseOn: "\x1b[?1000h\x1b[?1006h", mouseOff: "\x1b[?1006l\x1b[?1000l",
+  clear: "\x1b[2J\x1b[H",
+};
+
+/**
+ * Group the roster into herds.
+ *
+ * Sessions carry their herd in the manifest; anything written before herds
+ * existed has none, and lands in `main` rather than in a group called
+ * "undefined".
+ */
+export function groupByHerd(sessions) {
+  const herds = new Map();
+  for (const session of sessions) {
+    const key = session.herd || DEFAULT_HERD;
+    if (!herds.has(key)) herds.set(key, []);
+    herds.get(key).push(session);
+  }
+  return [...herds.entries()]
+    .sort(([a], [b]) => (a === DEFAULT_HERD ? -1 : b === DEFAULT_HERD ? 1 : a.localeCompare(b)))
+    .map(([name, members]) => ({ name, members: members.sort((a, b) => a.name.localeCompare(b.name)) }));
+}
+
+/**
+ * Flatten the groups into the rows the screen actually shows, so a click at
+ * line N and the highlighted row are the same lookup rather than two pieces of
+ * arithmetic that can disagree.
+ */
+/**
+ * How many lines render() prints before the first group heading — the title and
+ * the blank under it.
+ *
+ * Shared by render() and layout() rather than written twice, because the two
+ * disagreeing is not a cosmetic bug: layout() is the click map, so a
+ * one-line drift silently sends every click to the row below the one under the
+ * pointer. A test pins them together.
+ */
+export const HEADER_LINES = 2;
+
+export function layout(groups, { top = HEADER_LINES + 1 } = {}) {
+  const rows = [];
+  for (const group of groups) {
+    rows.push({ kind: "herd", herd: group.name, count: group.members.length });
+    for (const session of group.members) rows.push({ kind: "session", session, herd: group.name });
+    rows.push({ kind: "gap" });
+  }
+  if (rows.length) rows.pop(); // no trailing gap
+  return rows.map((row, i) => ({ ...row, line: top + i }));
+}
+
+const MARK = { blocked: "!", working: "~", done: "✓", idle: "·", gone: "×", unknown: "?" };
+
+const paint = (state, text) =>
+  state === "blocked" ? amber(text)
+  : state === "working" ? acid(text)
+  : state === "done" ? bone(text)
+  : state === "gone" ? danger(text)
+  : ash(text);
+
+/** One frame. Pure, so the whole screen can be asserted in a test. */
+export function render(rows, { selected = 0, width = 80, substrate = "tmux" } = {}) {
+  const out = [];
+  const total = rows.filter((r) => r.kind === "session").length;
+  const blocked = rows.filter((r) => r.kind === "session" && r.session.state === "blocked").length;
+  out.push(`  ${bone("moshcode herd")}${ash(`   ${total} member${total === 1 ? "" : "s"}`)}${blocked ? amber(`   ${blocked} waiting on you`) : ""}`);
+  out.push("");
+
+  for (const row of rows) {
+    if (row.kind === "gap") { out.push(""); continue; }
+    if (row.kind === "herd") {
+      out.push(`  ${ash(row.herd.toUpperCase())} ${dim(`(${row.count})`)}`);
+      continue;
+    }
+    const s = row.session;
+    const isSelected = rows[selected] === row;
+    const cursor = isSelected ? acid("▸") : " ";
+    const mark = paint(s.state, MARK[s.state] || "?");
+    const name = isSelected ? bone(s.name.padEnd(12)) : ash(s.name.padEnd(12));
+    const engine = ash(String(s.engine).padEnd(10));
+    const state = paint(s.state, s.state.padEnd(8));
+    const cwd = dim(tilde(s.cwd || "").slice(0, Math.max(10, width - 48)));
+    out.push(`   ${cursor} ${mark} ${name} ${engine} ${state} ${cwd}`);
+  }
+
+  if (!total) {
+    out.push(`  ${ash("the herd is empty.")}`);
+    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")}`);
+  if (substrate !== "tmux") out.push(`  ${dim(substrateNote(substrate) || "")}`);
+  return out.join("\r\n");
+}
+
+const tilde = (p) => {
+  const home = process.env.HOME || "";
+  return home && p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+};
+
+/**
+ * Decode one SGR mouse report: ESC [ < button ; col ; row (M press | m release).
+ *
+ * Only presses matter here, and only button 0 (left) and the wheel. Returning
+ * null for everything else keeps the caller from acting on a release, which
+ * would otherwise fire every click twice.
+ */
+export function parseMouse(sequence) {
+  const m = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/.exec(sequence);
+  if (!m) return null;
+  const [, button, col, row, kind] = m;
+  if (kind === "m") return null; // release
+  const b = Number(button);
+  if (b === 64) return { kind: "wheel", direction: -1 };
+  if (b === 65) return { kind: "wheel", direction: 1 };
+  if (b !== 0) return null;
+  return { kind: "click", col: Number(col), row: Number(row) };
+}
+
+/** Every mouse report in a chunk, so a fast click-drag cannot desync the parser. */
+export function parseInput(buffer) {
+  const events = [];
+  const text = String(buffer);
+  const mouse = /\x1b\[<\d+;\d+;\d+[Mm]/g;
+  let match;
+  while ((match = mouse.exec(text))) {
+    const parsed = parseMouse(match[0]);
+    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"]) {
+    if (text.includes(key)) events.push({ kind: "key", key });
+  }
+  return events;
+}
+
+/** Move the selection to the next/previous *session* row, skipping headings. */
+export function moveSelection(rows, from, delta) {
+  const selectable = rows.map((r, i) => (r.kind === "session" ? i : -1)).filter((i) => i >= 0);
+  if (!selectable.length) return from;
+  const at = selectable.indexOf(from);
+  if (at < 0) return selectable[0];
+  return selectable[Math.min(selectable.length - 1, Math.max(0, at + delta))];
+}
+
+/**
+ * The interactive list.
+ *
+ * Everything the terminal had is restored through one `restore()`, wired to
+ * normal exit and to the signals that otherwise kill a raw-mode process — a
+ * crash here must not leave someone with no cursor, no echo, and the mouse
+ * still captured by a program that is gone.
+ */
+export async function herdUi({
+  stdin = process.stdin,
+  stdout = process.stdout,
+  attach = attachSession,
+  read = roster,
+  refreshMs = 2000,
+} = {}) {
+  const substrate = detectSubstrate();
+  if (!stdin.isTTY || !stdout.isTTY) {
+    stdout.write("moshcode herd ui needs an interactive terminal — try `moshcode ps`\n");
+    return 1;
+  }
+
+  let rows = layout(groupByHerd(read()));
+  let selected = rows.findIndex((r) => r.kind === "session");
+  if (selected < 0) selected = 0;
+  let done = false;
+  let restored = false;
+
+  const wasRaw = Boolean(stdin.isRaw);
+  const restore = () => {
+    if (restored) return;
+    restored = true;
+    stdout.write(ESC.mouseOff + ESC.showCursor + ESC.altOff);
+    try { stdin.setRawMode?.(wasRaw); } catch { /* already gone */ }
+    stdin.pause();
+  };
+  const enter = () => {
+    restored = false;
+    stdout.write(ESC.altOn + ESC.hideCursor + ESC.mouseOn);
+    try { stdin.setRawMode?.(true); } catch { /* not a tty */ }
+    stdin.resume();
+  };
+  const onSignal = () => { restore(); process.exit(130); };
+  process.on("exit", restore);
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+
+  const draw = () => {
+    if (done) return;
+    stdout.write(ESC.clear + render(rows, { selected, width: stdout.columns || 80, substrate }));
+  };
+
+  const refresh = () => {
+    const previous = rows[selected];
+    rows = layout(groupByHerd(read()));
+    // Keep the highlight on the same session across a refresh, not on the same
+    // line number — a session finishing above it would otherwise slide the
+    // selection onto something else just as someone pressed enter.
+    const again = rows.findIndex((r) => r.kind === "session" && r.session?.name === previous?.session?.name);
+    selected = again >= 0 ? again : Math.max(0, rows.findIndex((r) => r.kind === "session"));
+    draw();
+  };
+
+  enter();
+  draw();
+  const timer = setInterval(refresh, refreshMs);
+  const onResize = () => draw();
+  stdout.on("resize", onResize);
+
+  const openSelected = async () => {
+    const row = rows[selected];
+    if (row?.kind !== "session" || !row.session.alive) return;
+    // Give the terminal back before handing it to tmux, and take it again after
+    // — attaching inside our alternate screen with the mouse captured would put
+    // the agent's own mouse handling in a fight with ours.
+    restore();
+    await attach(row.session.name, { substrate });
+    if (done) return;
+    enter();
+    refresh();
+  };
+
+  await new Promise((resolve) => {
+    const onData = async (buf) => {
+      for (const event of parseInput(buf)) {
+        if (event.kind === "key" && (event.key === "q" || event.key === "\x03")) {
+          done = true;
+          resolve();
+          return;
+        }
+        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 === "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);
+          draw();
+          await openSelected();
+          continue;
+        }
+        else if (event.kind === "key") { await openSelected(); continue; }
+        draw();
+      }
+    };
+    stdin.on("data", onData);
+  });
+
+  clearInterval(timer);
+  stdout.off("resize", onResize);
+  stdin.off("data", () => {});
+  restore();
+  process.off("exit", restore);
+  process.off("SIGINT", onSignal);
+  process.off("SIGTERM", onSignal);
+  stdout.write("\n");
+  return 0;
+}

package/src/herd.mjs

@@ -257,6 +257,10 @@ export function tmuxStartPlan({ name, cwd, command }) {
     "-f", "/dev/null",
     "new-session", "-d", "-s", name, "-c", cwd, command,
     ";", "set-option", "-t", name, "remain-on-exit", "on",
+    // Mouse on, so a click selects a pane and the status line's window list is
+    // 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",
   ];
 }
 
@@ -734,6 +738,9 @@ export function listSessions({ substrate = detectSubstrate(), runner = spawnSync
     return {
       name,
       engine: meta.engine || "?",
+      // Sessions started before herds existed have none. They belong to `main`
+      // rather than to a group rendered as "undefined".
+      herd: meta.herd || "main",
       cwd: meta.cwd || "",
       created: meta.created || null,
       age: meta.created ? now - meta.created : null,