@hellix-ai/cubes 0.1.5 → 0.2.1

package/dist/termstatus.js

@@ -7,7 +7,7 @@
 // working / ready / waiting-with-a-reason), in the three dialects terminals understand:
 //
 //   • OSC 0 TITLE - every terminal. `<glyph> <session title>`, the convention Claude Code itself uses:
-//     a spinner while working, ✳ when idle, ✋ when it is waiting for you.
+//     ● while working, ✳ when idle, ✋ when it is waiting for you. Static: an animated glyph churns the tab.
 //   • BEL + OSC 9 - the generic "this tab wants you": a bell marks the tab / bounces the dock almost
 //     everywhere, and OSC 9 raises a desktop notification in iTerm2, Ghostty, WezTerm, kitty, Warp.
 //   • OSC 777 `warp://cli-agent` - Warp's structured agent protocol, the same events and payload as
@@ -19,7 +19,7 @@
 // would corrupt both. `StreamFilter` tracks where the stream is, and the caller only writes ours when
 // the stream is between sequences.
 export const WARP_PLUGIN_COMPAT = "2.3.0"; // the claude-code-warp release whose event set this mirrors
-const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const WORKING = "●";
 const IDLE = "✳";
 const WAITING = "✋";
 /** Title push / pop (xterm window ops): our title is set on top of yours and yours comes back after. */
@@ -30,6 +30,22 @@ export function clean(s, max = 120) {
     const t = s.replace(/[\x00-\x1f\x7f-\x9f]/g, " ").replace(/\s+/g, " ").trim();
     return t.length > max ? t.slice(0, max - 1) + "…" : t;
 }
+/** Largest OSC 52 we will hold (base64): a copy, not a file transfer. Past it the copy is dropped. */
+const CLIP_MAX = 4 * 1024 * 1024;
+/** The text an OSC 52 body (`c;<base64>`) carries, or null for a READ request (`?`), which we never
+ *  answer - a session asking for the person's clipboard gets nothing. */
+export function decodeOsc52(body) {
+    const semi = body.indexOf(";");
+    const data = semi >= 0 ? body.slice(semi + 1) : body;
+    if (!data || data === "?")
+        return null;
+    try {
+        return Buffer.from(data, "base64").toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Passes the session's output through, minus the two things that would fight us for the title -
  * OSC 0/1/2 (set title) and CSI 22/23 t (title push/pop, which the session's tmux sends on attach and
@@ -37,10 +53,20 @@ export function clean(s, max = 120) {
  * safe to write a sequence of our own.
  */
 export class StreamFilter {
+    onClipboard;
     st = "ground";
     seq = []; // the CSI or OSC-prefix being decided
     utf8Left = 0;
     oscEsc = false; // saw ESC inside a string, waiting for '\'
+    clip = [];
+    /**
+     * `onClipboard`: when given, an OSC 52 (set clipboard) is taken OUT of the stream and its text
+     * handed over instead - the CLI puts it on the person's clipboard itself, which works whether or not
+     * their terminal honours OSC 52. Without it, OSC 52 passes through like any other OSC.
+     */
+    constructor(onClipboard) {
+        this.onClipboard = onClipboard;
+    }
     get safe() {
         return this.st === "ground" && this.utf8Left === 0;
     }
@@ -112,10 +138,12 @@ export class StreamFilter {
                     const ends = b === 0x07 || b === 0x1b;
                     if (b === 0x3b || ends || this.seq.length > 8) {
                         const num = String.fromCharCode(...this.seq.slice(2));
-                        const title = /^[012]$/.test(num);
+                        const clip = num === "52" && !!this.onClipboard;
+                        const title = /^[012]$/.test(num) || clip; // both are ours, neither reaches the terminal
                         if (!title)
                             out.push(...this.seq);
                         this.seq = [];
+                        this.clip = [];
                         if (ends) {
                             if (b === 0x07) {
                                 if (!title)
@@ -125,14 +153,14 @@ export class StreamFilter {
                             else {
                                 if (!title)
                                     out.push(b);
-                                this.st = title ? "oscDrop" : "str";
+                                this.st = clip ? "oscClip" : title ? "oscDrop" : "str";
                                 this.oscEsc = true;
                             }
                         }
                         else {
                             if (!title)
                                 out.push(b);
-                            this.st = title ? "oscDrop" : "str";
+                            this.st = clip ? "oscClip" : title ? "oscDrop" : "str";
                             this.oscEsc = false;
                         }
                     }
@@ -141,6 +169,20 @@ export class StreamFilter {
                     }
                     break;
                 }
+                case "oscClip": {
+                    if (this.oscEsc && b === 0x5c) {
+                        this.endClip();
+                        break;
+                    } // ST = ESC \
+                    if (b === 0x07) {
+                        this.endClip();
+                        break;
+                    }
+                    this.oscEsc = b === 0x1b;
+                    if (!this.oscEsc && this.clip.length < CLIP_MAX)
+                        this.clip.push(b);
+                    break;
+                }
                 case "oscDrop":
                 case "str": {
                     const keep = this.st === "str";
@@ -160,6 +202,16 @@ export class StreamFilter {
         }
         return Uint8Array.from(out);
     }
+    endClip() {
+        this.st = "ground";
+        this.oscEsc = false;
+        // Buffer, not String.fromCharCode(...bytes): a spread of a large copy overflows the argument limit.
+        const body = this.clip.length < CLIP_MAX ? Buffer.from(this.clip).toString("latin1") : "";
+        this.clip = [];
+        const text = body ? decodeOsc52(body) : null;
+        if (text)
+            this.onClipboard?.(text);
+    }
 }
 function stateOf(r) {
     if (r.status !== "running")
@@ -192,20 +244,30 @@ export function warpProtocol(env) {
 export class TermStatus {
     emit;
     state = null;
-    frame = 0;
     shown = "";
     row;
     warp;
+    inTmux;
     constructor(row, emit, env = process.env) {
         this.emit = emit;
         this.row = row;
         this.warp = warpProtocol(env);
+        this.inTmux = !!env.TMUX;
     }
     title() {
-        const glyph = this.state === "working" ? SPINNER[this.frame % SPINNER.length]
-            : this.state === "waiting" ? WAITING : IDLE;
+        const glyph = this.state === "working" ? WORKING : this.state === "waiting" ? WAITING : IDLE;
         return `${glyph} ${clean(this.row.title || "Cubes session", 80)}`;
     }
+    flashTimer = null;
+    /** A moment's word in the tab title ("✓ Copied 42 characters"), then the title it had. */
+    flash(text, ms = 1500) {
+        if (this.flashTimer)
+            clearTimeout(this.flashTimer);
+        this.emit(`\x1b]0;${clean(text, 80)}\x07`);
+        this.shown = "";
+        this.flashTimer = setTimeout(() => { this.flashTimer = null; this.setTitle(); }, ms);
+        this.flashTimer.unref?.();
+    }
     /** Only when it changed: the activity is re-read every few seconds, and most reads change nothing. */
     setTitle() {
         const t = this.title();
@@ -214,6 +276,15 @@ export class TermStatus {
         this.shown = t;
         this.emit(`\x1b]0;${t}\x07`);
     }
+    /**
+     * Notifications (OSC 9, OSC 777) are for the terminal the PERSON sees. Inside tmux - the split view
+     * runs everything in one - tmux would swallow them, so they travel as tmux's DCS passthrough (every
+     * ESC doubled), which reaches the outer terminal when `allow-passthrough` is on (the split view turns
+     * it on). The bell needs none of this: tmux forwards a bell by itself.
+     */
+    outward(seq) {
+        return this.inTmux ? `\x1bPtmux;${seq.replace(/\x1b/g, "\x1b\x1b")}\x1b\\` : seq;
+    }
     warpEvent(event, extra = {}) {
         if (this.warp === null)
             return;
@@ -221,7 +292,7 @@ export class TermStatus {
             v: this.warp, agent: "claude", event, session_id: this.row.id, cwd: "",
             project: clean(this.row.title || "cubes", 60), ...extra,
         });
-        this.emit(`\x1b]777;notify;warp://cli-agent;${body}\x07`);
+        this.emit(this.outward(`\x1b]777;notify;warp://cli-agent;${body}\x07`));
     }
     /** Feed the latest row. The first call only establishes the state - nobody needs to be told that a
      *  session they are attaching to right now is waiting for them. */
@@ -260,16 +331,8 @@ export class TermStatus {
             else if (!row.muted_at) {
                 // Bell first (marks the tab nearly everywhere), then the desktop notification where supported.
                 // "Cubes" leads the text so it can never be read as ConEmu's numeric OSC 9 sub-commands.
-                this.emit(`\x07\x1b]9;Cubes · ${clean(row.title || "session", 60)}: ${summary}\x07`);
+                this.emit(`\x07${this.outward(`\x1b]9;Cubes · ${clean(row.title || "session", 60)}: ${summary}\x07`)}`);
             }
         }
     }
-    /** Advance the working spinner. Returns false when there is nothing to animate. */
-    tick() {
-        if (this.state !== "working")
-            return false;
-        this.frame++;
-        this.setTitle();
-        return true;
-    }
 }

package/dist/tui/launch.js

@@ -0,0 +1,98 @@
+// `cubes` with no arguments: the split view. A local tmux on its own socket holds two panes - the
+// session list on the left, the session on the right - so layout, resizing, mouse focus and the
+// terminal emulation of the right pane are tmux's, which is the battle-tested part. Our two processes
+// (`cubes _list`, `cubes _pane`) only draw and talk to the API.
+//
+// Run it again and you are back where you were: the tmux outlives the terminal that opened it.
+import { spawnSync } from "node:child_process";
+import { CliError, currentSession } from "../auth.js";
+import { selfCommand, SESSION, SOCKET, tmux, tmuxVersion } from "./tmux.js";
+const MIN_TMUX = 3.2;
+/** Every option is set on OUR socket only, so none of this reaches a tmux the person already uses. */
+const OPTIONS = [
+    ["mouse", "on"],
+    ["status", "off"],
+    // ⚠ NO PREFIX. tmux's Ctrl-B is Claude Code's "run in background", and the session's own tmux (the
+    // one in the pod) has none either, so nothing here may eat a keystroke. Focus moves by mouse, by
+    // Ctrl-] from the session pane, and by Enter/Tab from the list.
+    ["prefix", "None"],
+    ["prefix2", "None"],
+    // Escape must reach Claude Code at once: tmux's default 500 ms makes every Esc feel broken.
+    ["escape-time", "10"],
+    ["focus-events", "on"],
+    ["pane-border-status", "top"],
+    ["pane-border-format", " #{?#{@cubes_header},#{@cubes_header},#{pane_title}} "],
+    ["pane-border-style", "fg=colour238"],
+    ["pane-active-border-style", "fg=colour62"],
+    // The outer terminal's tab follows the session on the right, whichever pane has focus.
+    ["set-titles", "on"],
+    ["set-titles-string", "#{?#{@cubes_tab},#{@cubes_tab},Cubes}"],
+    // So a session's bell and notifications reach the terminal the person is looking at.
+    ["bell-action", "any"],
+    ["visual-bell", "off"],
+    ["allow-passthrough", "on"],
+];
+function attachClient() {
+    const env = { ...process.env };
+    delete env.TMUX; // inside the person's own tmux: nest on purpose rather than refuse
+    const r = spawnSync("tmux", ["-L", SOCKET, "attach-session", "-t", SESSION], { stdio: "inherit", env });
+    return r.status ?? 0;
+}
+function build(org) {
+    const cols = process.stdout.columns ?? 160;
+    const rows = process.stdout.rows ?? 48;
+    const env = org ? ["-e", `CUBES_ORG=${org}`] : [];
+    const created = tmux(["new-session", "-d", "-s", SESSION, "-x", String(cols), "-y", String(rows), ...env,
+        "-P", "-F", "#{pane_id}", selfCommand(["_list"])]);
+    if (created.code !== 0)
+        throw new CliError(`could not start tmux: ${created.err || created.code}`);
+    const left = created.out;
+    for (const [k, v] of OPTIONS)
+        tmux(["set-option", "-g", "-q", k, v]);
+    // ⚠ The same fix the session's own tmux carries (server Tmux.clientDefaults): without `ech`, tmux
+    // draws gaps as real spaces. Warp left stale letters in every gap drawn with ECH. A SERVER option,
+    // read when a client attaches, so it is set before ours does.
+    tmux(["set-option", "-s", "terminal-overrides[90]", "*:ech@"]);
+    tmux(["set-option", "-w", "-t", SESSION, "-q", "remain-on-exit", "on"]);
+    // The list gets about a third, within reason: enough for a title, never most of the screen.
+    const listW = Math.max(32, Math.min(56, Math.round(cols * 0.3)));
+    const right = tmux(["split-window", "-h", "-t", left, "-l", String(Math.max(20, cols - listW - 1)), ...env,
+        "-P", "-F", "#{pane_id}", selfCommand(["_pane"])]);
+    if (right.code !== 0)
+        throw new CliError(`could not split the window: ${right.err || right.code}`);
+    tmux(["set-option", "-t", SESSION, "@cubes_left", left]);
+    tmux(["set-option", "-t", SESSION, "@cubes_right", right.out]);
+    tmux(["select-pane", "-t", left]);
+}
+/**
+ * Bring a dead pane back. `remain-on-exit` keeps a crashed pane on screen (with what it printed)
+ * instead of letting the layout collapse; reopening `cubes` restarts whichever of the two died.
+ */
+function heal() {
+    const panes = tmux(["list-panes", "-t", SESSION, "-F", "#{pane_id} #{pane_dead}"]).out.split("\n");
+    const left = tmux(["show-options", "-v", "-q", "-t", SESSION, "@cubes_left"]).out;
+    for (const line of panes) {
+        const [id, dead] = line.split(" ");
+        if (dead !== "1" || !id)
+            continue;
+        tmux(["respawn-pane", "-k", "-t", id, selfCommand(id === left ? ["_list"] : ["_pane"])]);
+    }
+}
+export async function launchTui(opts) {
+    const v = tmuxVersion();
+    if (v === null) {
+        throw new CliError("the split view runs inside tmux, which is not installed - `brew install tmux` (macOS) or "
+            + "`apt install tmux`. `cubes attach` works without it.");
+    }
+    if (v < MIN_TMUX)
+        throw new CliError(`the split view needs tmux ${MIN_TMUX} or newer (this is ${v}) - upgrade it, or use \`cubes attach\``);
+    // Fail here, with a sentence, rather than in two panes at once.
+    await currentSession({ org: opts.org }).token();
+    if (tmux(["has-session", "-t", SESSION]).code === 0) {
+        heal();
+        tmux(["set-option", "-s", "terminal-overrides[90]", "*:ech@"]); // a layout built by an older cubes
+    }
+    else
+        build(opts.org);
+    return attachClient();
+}

package/dist/tui/listApp.js

@@ -0,0 +1,347 @@
+// The left pane of the split view: every session, grouped and nested, with its state, filterable,
+// and one keystroke (or click) from being open on the right.
+import { makeApi } from "../api.js";
+import { currentSession } from "../auth.js";
+import { age, listSessions, LIVE } from "../sessions.js";
+import { buildItems, statusOf, treePrefix } from "./model.js";
+import { ESC, fit, parseKeys, printable, strWidth } from "./term.js";
+import { fmtText, getSessionOption, selfCommand, setPaneOption, setSessionOption, SESSION, tmux } from "./tmux.js";
+const POLL_MS = 3000;
+const SELECTED_BG = 237;
+const ACCENT = 62;
+/** As many WHOLE key hints as fit, in order of how much they are needed - never one cut in half -
+ *  and the way out always last. */
+export function hints(width) {
+    const all = ["⏎ open", "l live", "m mine", "/ find", "^] back here", "←→ fold", "r refresh"];
+    const quit = "q quit";
+    let out = "";
+    for (const h of all) {
+        const next = out ? `${out}  ${h}` : h;
+        if (strWidth(`${next}  ${quit}`) > width)
+            break;
+        out = next;
+    }
+    return out ? `${out}  ${quit}` : quit;
+}
+export async function runList() {
+    const session = currentSession();
+    const api = makeApi(session);
+    const out = process.stdout;
+    const st = {
+        rows: [], loaded: false, error: null, filters: { live: false, mine: false, text: "" }, searching: false,
+        expanded: new Map(), selectedId: null, top: 0, current: getSessionOption("@cubes_current"), flash: null,
+    };
+    let items = [];
+    let flashTimer = null;
+    const restore = () => out.write(ESC.mouseOff + ESC.showCursor + ESC.altOff);
+    process.on("exit", restore);
+    for (const sig of ["SIGTERM", "SIGHUP"])
+        process.on(sig, () => process.exit(0));
+    if (process.stdin.isTTY)
+        process.stdin.setRawMode(true);
+    out.write(ESC.altOn + ESC.hideCursor + ESC.mouseOn);
+    const sessionItems = () => items.filter((i) => i.kind === "session");
+    const selIndex = () => items.findIndex((i) => i.kind === "session" && i.row.id === st.selectedId);
+    const rebuild = () => {
+        items = buildItems(st.rows, st.filters, st.expanded);
+        if (selIndex() < 0) {
+            const first = sessionItems()[0];
+            st.selectedId = first ? first.row.id : null;
+        }
+    };
+    const flash = (msg) => {
+        st.flash = msg;
+        if (flashTimer)
+            clearTimeout(flashTimer);
+        flashTimer = setTimeout(() => { st.flash = null; render(); }, 2500);
+        render();
+    };
+    // ── rendering ──────────────────────────────────────────────────────────────────────────────────
+    const chip = (label, on) => on ? `${ESC.bg(ACCENT)}${ESC.fg(255)} ${label} ${ESC.reset}` : `${ESC.dim} ${label} ${ESC.reset}`;
+    const sessionLine = (it, w, selected) => {
+        const r = it.row;
+        const s = statusOf(r);
+        const mark = r.id === st.current ? `${ESC.fg(ACCENT)}▌${ESC.reset}` : " ";
+        const tree = treePrefix(it);
+        const exp = it.children > 0 ? (it.expanded ? "▾" : "▸") : " ";
+        const right = w >= 34 ? (LIVE.has(r.status) ? s.label : age(r.ended_at ?? r.created_at)) : "";
+        const fixed = 1 + strWidth(tree) + 1 + 2; // mark, tree, expander, glyph + space
+        const titleW = Math.max(4, w - fixed - (right ? strWidth(right) + 1 : 0));
+        const title = fit(printable(r.title || "(untitled)"), titleW);
+        const bg = selected ? ESC.bg(SELECTED_BG) : "";
+        const body = `${bg}${ESC.dim}${tree}${ESC.reset}${bg}${exp}${ESC.fg(s.color)}${s.glyph}${ESC.reset}${bg} ` +
+            `${s.attention ? ESC.bold : ""}${title}${ESC.reset}${bg}${right ? ` ${ESC.fg(s.color)}${right}` : ""}`;
+        return `${mark}${body}${ESC.reset}`;
+    };
+    function render() {
+        const w = out.columns ?? 40;
+        const h = out.rows ?? 20;
+        const viewH = Math.max(1, h - 2);
+        const lines = [];
+        // Line 1: the filters, and the count they leave.
+        const search = st.searching || st.filters.text
+            ? ` ${ESC.fg(ACCENT)}/${ESC.reset}${printable(st.filters.text)}${st.searching ? `${ESC.inverse} ${ESC.reset}` : ""}`
+            : ` ${ESC.dim}/ find${ESC.reset}`;
+        lines.push(`${chip("live", st.filters.live)} ${chip("mine", st.filters.mine)}${search}`);
+        // The list, scrolled to keep the selection in view.
+        const sel = selIndex();
+        if (sel >= 0) {
+            if (sel < st.top)
+                st.top = sel;
+            if (sel >= st.top + viewH)
+                st.top = sel - viewH + 1;
+        }
+        st.top = Math.max(0, Math.min(st.top, Math.max(0, items.length - viewH)));
+        for (let i = 0; i < viewH; i++) {
+            const it = items[st.top + i];
+            if (!it) {
+                lines.push("");
+                continue;
+            }
+            if (it.kind === "section") {
+                const label = ` ${it.title} (${it.count}) `;
+                lines.push(`${ESC.dim}──${ESC.reset}${ESC.bold}${fit(printable(label), Math.min(w - 2, strWidth(label)))}${ESC.reset}` +
+                    `${ESC.dim}${"─".repeat(Math.max(0, w - 2 - strWidth(label)))}${ESC.reset}`);
+            }
+            else {
+                lines.push(sessionLine(it, w, it.row.id === st.selectedId));
+            }
+        }
+        if (!items.length) {
+            const msg = !st.loaded ? "loading sessions…" : st.error ? "" : "nothing matches - l / m / find narrow the list";
+            lines[2] = `  ${ESC.dim}${fit(msg, w - 2)}${ESC.reset}`;
+        }
+        // Last line: what went wrong, or what the keys do.
+        const foot = st.flash ?? (st.error ? `⚠ ${st.error}` : st.searching
+            ? "type to filter · ⏎ keep · esc clear"
+            : hints(w));
+        lines.push(`${st.error && !st.flash ? ESC.fg(203) : ESC.dim}${fit(foot, w)}${ESC.reset}`);
+        let frame = ESC.syncOn + ESC.home;
+        lines.forEach((l, i) => { frame += `${ESC.at(i + 1, 1)}\x1b[2K${l}`; });
+        out.write(frame + ESC.syncOff);
+        updateHeader();
+    }
+    let lastHeader = "";
+    function updateHeader() {
+        const live = st.rows.filter((r) => LIVE.has(r.status)).length;
+        const needs = st.rows.filter((r) => statusOf(r).attention).length;
+        const org = session.org ? ` · ${fmtText(printable(session.org))}` : "";
+        const h = `#[bold]Cubes#[nobold]${org} · ${live} live${needs ? ` · #[fg=colour214]${needs} need you#[default]` : ""}`;
+        if (h !== lastHeader) {
+            lastHeader = h;
+            setPaneOption("@cubes_header", h);
+        }
+    }
+    // ── actions ────────────────────────────────────────────────────────────────────────────────────
+    const move = (delta) => {
+        const list = sessionItems();
+        if (!list.length)
+            return;
+        const at = Math.max(0, list.findIndex((i) => i.row.id === st.selectedId));
+        const next = list[Math.max(0, Math.min(list.length - 1, at + delta))];
+        st.selectedId = next.row.id;
+    };
+    const open = (id) => {
+        const right = getSessionOption("@cubes_right");
+        if (!right) {
+            flash("the session pane is gone - run cubes again");
+            return;
+        }
+        const r = tmux(["respawn-pane", "-k", "-t", right, selfCommand(["_pane", id])]);
+        if (r.code !== 0) {
+            flash(`could not open it: ${r.err || r.code}`);
+            return;
+        }
+        tmux(["select-pane", "-t", right]);
+        st.current = id;
+        setSessionOption("@cubes_current", id);
+    };
+    const toggleFold = (id, open) => {
+        const it = sessionItems().find((i) => i.row.id === id);
+        if (!it || it.children === 0)
+            return false;
+        st.expanded.set(id, open ?? !it.expanded);
+        return true;
+    };
+    const goParent = () => {
+        const it = sessionItems().find((i) => i.row.id === st.selectedId);
+        if (it?.row.parent_session_id && items.some((i) => i.kind === "session" && i.row.id === it.row.parent_session_id)) {
+            st.selectedId = it.row.parent_session_id;
+        }
+    };
+    function onKey(k) {
+        if (st.searching) {
+            if (k.kind === "char")
+                st.filters.text += k.ch;
+            else if (k.kind === "backspace")
+                st.filters.text = [...st.filters.text].slice(0, -1).join("");
+            else if (k.kind === "enter" || k.kind === "down")
+                st.searching = false;
+            else if (k.kind === "escape" || k.kind === "ctrl-c") {
+                st.searching = false;
+                st.filters.text = "";
+            }
+            rebuild();
+            return;
+        }
+        const viewH = Math.max(1, (out.rows ?? 20) - 2);
+        switch (k.kind) {
+            case "up":
+                move(-1);
+                break;
+            case "down":
+                move(1);
+                break;
+            case "pgup":
+                move(-viewH);
+                break;
+            case "pgdn":
+                move(viewH);
+                break;
+            case "home":
+                move(-1e9);
+                break;
+            case "end":
+                move(1e9);
+                break;
+            case "enter":
+                if (st.selectedId)
+                    open(st.selectedId);
+                break;
+            case "tab":
+            case "ctrl-]": {
+                const right = getSessionOption("@cubes_right");
+                if (right)
+                    tmux(["select-pane", "-t", right]);
+                break;
+            }
+            case "right":
+                if (st.selectedId && !toggleFold(st.selectedId, true)) { /* a leaf: nothing to open */ }
+                break;
+            case "left":
+                if (!(st.selectedId && toggleFold(st.selectedId, false)))
+                    goParent();
+                break;
+            case "escape":
+                if (st.filters.text) {
+                    st.filters.text = "";
+                    rebuild();
+                }
+                break;
+            case "ctrl-l":
+                out.write(ESC.clear);
+                break;
+            case "mouse":
+                onMouse(k);
+                break;
+            case "char":
+                switch (k.ch) {
+                    case "j":
+                        move(1);
+                        break;
+                    case "k":
+                        move(-1);
+                        break;
+                    case "g":
+                        move(-1e9);
+                        break;
+                    case "G":
+                        move(1e9);
+                        break;
+                    case " ":
+                        if (st.selectedId)
+                            toggleFold(st.selectedId);
+                        break;
+                    case "l":
+                        st.filters.live = !st.filters.live;
+                        break;
+                    case "m":
+                        st.filters.mine = !st.filters.mine;
+                        break;
+                    case "/":
+                        st.searching = true;
+                        break;
+                    case "r":
+                        void refresh(true);
+                        break;
+                    case "d":
+                        tmux(["detach-client", "-s", SESSION]);
+                        break;
+                    case "q":
+                        tmux(["kill-session", "-t", SESSION]);
+                        break;
+                }
+                break;
+        }
+        rebuild();
+    }
+    function onMouse(k) {
+        if (k.release)
+            return;
+        if (k.button === 64) {
+            move(-3);
+            return;
+        } // wheel up
+        if (k.button === 65) {
+            move(3);
+            return;
+        } // wheel down
+        if (k.button !== 0)
+            return;
+        if (k.y === 1) { // the filter line
+            if (k.x <= 6)
+                st.filters.live = !st.filters.live;
+            else if (k.x <= 13)
+                st.filters.mine = !st.filters.mine;
+            else
+                st.searching = true;
+            return;
+        }
+        const it = items[st.top + k.y - 2];
+        if (!it || it.kind !== "session")
+            return;
+        // A click on the fold arrow folds; anywhere else on the row opens it.
+        const arrowCol = 1 + strWidth(treePrefix(it)) + 1;
+        if (it.children > 0 && k.x === arrowCol) {
+            st.selectedId = it.row.id;
+            toggleFold(it.row.id);
+            return;
+        }
+        st.selectedId = it.row.id;
+        open(it.row.id);
+    }
+    // ── data ───────────────────────────────────────────────────────────────────────────────────────
+    let inFlight = false;
+    async function refresh(announce = false) {
+        if (inFlight)
+            return;
+        inFlight = true;
+        try {
+            st.rows = await listSessions(api, { all: true });
+            st.loaded = true;
+            st.error = null;
+            if (announce)
+                flash(`${st.rows.length} sessions`);
+        }
+        catch (e) {
+            st.error = e.message;
+        }
+        finally {
+            inFlight = false;
+            // The pane on the right says which session it holds; it can change without us (a reconnect).
+            st.current = getSessionOption("@cubes_current");
+            rebuild();
+            render();
+        }
+    }
+    process.stdin.on("data", (b) => {
+        for (const k of parseKeys(b.toString("utf8")))
+            onKey(k);
+        render();
+    });
+    out.on("resize", render);
+    render();
+    await refresh();
+    setInterval(() => void refresh(), POLL_MS);
+    return new Promise(() => { });
+}