@sandropadin/tend 0.1.0

package/src/pick.ts

@@ -0,0 +1,224 @@
+// Interactive live dashboard: a grouped list of agents across all tmux sessions
+// that re-scans on an interval AND lets you act on it. Arrow keys (or j/k) move
+// the cursor; Enter jumps to that pane; o cycles where the jump opens; r
+// refreshes; q / Esc / Ctrl-C quits.
+//
+// Jump target: by default Enter opens the agent in *this* window (the one the
+// dashboard runs in), keeping the dashboard alive in its own pane. Press `o` to
+// cycle the target to another attached client (another terminal window), so you
+// can watch here and open blocked agents over there — the dashboard never moves.
+// (When targeting this window from a plain terminal — not inside tmux — jumping
+// means `tmux attach`, which takes over the terminal, so there we exit.)
+
+import { scan, type ScanOptions } from "./scan.ts";
+import { insideTmux, jumpToPane, listClients, selfClientTty, type TmuxClient } from "./nav.ts";
+import { agentRow, bold, dim, groupBySession, summaryLine } from "./render.ts";
+import type { PaneMemory } from "./detect.ts";
+import type { AgentStatus } from "./types.ts";
+
+const ALT_ON = "\x1b[?1049h";
+const ALT_OFF = "\x1b[?1049l";
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+const CURSOR_HOME = "\x1b[H"; // move to top-left without clearing (no flicker)
+const CLEAR_EOL = "\x1b[K"; // erase from cursor to end of *line*
+const CLEAR_BELOW = "\x1b[J"; // erase from cursor to end of screen
+const ANIM_MS = 90; // spinner tick — faster than the scan interval
+
+const shortTty = (tty: string) => tty.replace(/^\/dev\//, "");
+
+export async function runPicker(
+  opts: ScanOptions,
+  intervalMs: number,
+  initialTarget?: string,
+): Promise<void> {
+  let statuses: AgentStatus[] = [];
+  let memory = new Map<string, PaneMemory>();
+  let cursorPaneId: string | null = null; // track selection by id across rescans
+  let clients: TmuxClient[] = [];
+  let targetTty: string | null = initialTarget ?? null; // null = this window
+  let selfTty: string | null = null;
+  let done = false;
+  let statusMsg = ""; // transient line (e.g. "sent … to …")
+  let frame = 0; // spinner animation frame
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let animTimer: ReturnType<typeof setInterval> | undefined;
+
+  const out = process.stdout;
+  const input = process.stdin;
+
+  // Flattened, display-ordered list of selectable agent rows (grouped order).
+  const selectable = (): AgentStatus[] => groupBySession(statuses).flatMap((g) => g.agents);
+  const otherClients = (): TmuxClient[] => clients.filter((c) => c.tty !== selfTty);
+
+  const currentIndex = (): number => {
+    const list = selectable();
+    if (list.length === 0) return -1;
+    const i = list.findIndex((s) => s.pane.id === cursorPaneId);
+    return i >= 0 ? i : 0;
+  };
+
+  const moveCursor = (delta: number) => {
+    const list = selectable();
+    if (list.length === 0) return;
+    const next = Math.min(list.length - 1, Math.max(0, currentIndex() + delta));
+    cursorPaneId = list[next]!.pane.id;
+    statusMsg = ""; // clear the note once you start moving again
+  };
+
+  // Cycle the jump target: this window → each other client → back.
+  const cycleTarget = () => {
+    const others = otherClients();
+    if (others.length === 0) {
+      // Nothing to target — tell the user how to get a second window instead of
+      // silently doing nothing.
+      statusMsg =
+        clients.length <= 1
+          ? "no other tmux client — run `tmux attach` in another terminal window"
+          : "no other client detected (couldn't tell this window apart)";
+      render();
+      return;
+    }
+    const cycle: Array<string | null> = [null, ...others.map((c) => c.tty)];
+    let idx = cycle.indexOf(targetTty);
+    if (idx < 0) idx = 0;
+    targetTty = cycle[(idx + 1) % cycle.length] ?? null;
+    statusMsg = "";
+    render();
+  };
+
+  const targetLabel = (): string => {
+    if (!targetTty) return "this window";
+    const c = clients.find((x) => x.tty === targetTty);
+    return shortTty(targetTty) + (c ? ` · ${c.session}` : "");
+  };
+
+  const render = () => {
+    const groups = groupBySession(statuses);
+    const selectedId = selectable()[currentIndex()]?.pane.id ?? null;
+    const others = otherClients().length;
+    const lines: string[] = [];
+    lines.push(
+      bold("tend") + dim("  ↑/↓ move · enter jump · o target · r refresh · q quit"),
+    );
+    // Show where Enter opens, plus how many other windows are available to target.
+    const windowsNote = others > 0 ? `  (${others} other window${others > 1 ? "s" : ""})` : "";
+    lines.push(dim(`opens in: ${targetLabel()}${windowsNote}`) + (statusMsg ? dim(`   ${statusMsg}`) : ""));
+    if (groups.length === 0) {
+      lines.push(dim("No AI agents detected in any tmux session."));
+    } else {
+      for (const { session, agents } of groups) {
+        const blocked = agents.filter((a) => a.state === "blocked").length;
+        const suffix = blocked ? `  \x1b[31m· ${blocked} blocked\x1b[0m` : "";
+        lines.push(bold(`▸ ${session}`) + dim(`  (${agents.length})`) + suffix);
+        for (const a of agents) {
+          lines.push(agentRow(a, a.pane.id === selectedId, frame));
+        }
+        lines.push("");
+      }
+    }
+    lines.push(summaryLine(statuses));
+    // Home + overwrite, erasing each line's tail (CLEAR_EOL) so a line that got
+    // shorter doesn't leave ghost text (e.g. a stale "· 1 blocked" suffix), plus
+    // CLEAR_BELOW for when this frame has fewer lines. No full-screen wipe, so
+    // the ~90ms spinner repaints stay flicker-free.
+    out.write(CURSOR_HOME + lines.map((l) => l + CLEAR_EOL).join("\n") + "\n" + CLEAR_BELOW);
+  };
+
+  const refresh = async () => {
+    const result = await scan(opts, memory);
+    memory = result.memory;
+    statuses = result.statuses;
+    clients = await listClients();
+    // If our chosen target client went away, fall back to this window.
+    if (targetTty && !clients.some((c) => c.tty === targetTty)) targetTty = null;
+    if (cursorPaneId === null) cursorPaneId = selectable()[0]?.pane.id ?? null;
+    if (!done) render();
+  };
+
+  const cleanup = () => {
+    if (timer) clearInterval(timer);
+    if (animTimer) clearInterval(animTimer);
+    input.setRawMode?.(false);
+    input.pause();
+    input.removeListener("data", onKey);
+    out.write(SHOW_CURSOR + ALT_OFF);
+  };
+
+  const jump = async () => {
+    const target = selectable()[currentIndex()];
+    if (!target) return;
+
+    // Targeting another client: move that window, keep the dashboard put.
+    if (targetTty) {
+      try {
+        await jumpToPane(target.pane, { client: targetTty });
+        statusMsg = `→ sent ${target.agent} (${target.pane.id}) to ${shortTty(targetTty)}`;
+      } catch {
+        statusMsg = `⚠ ${shortTty(targetTty)} unavailable`;
+      }
+      render();
+      return;
+    }
+
+    // Targeting this window, inside tmux: switch our client but keep running.
+    if (insideTmux()) {
+      await jumpToPane(target.pane);
+      statusMsg = `→ jumped to ${target.agent} in ${target.pane.sessionName} (${target.pane.id})`;
+      render();
+      return;
+    }
+
+    // This window, outside tmux: attach takes over the terminal → tear down.
+    done = true;
+    cleanup();
+    await jumpToPane(target.pane);
+    process.exit(0);
+  };
+
+  function onKey(buf: Buffer) {
+    const key = buf.toString("utf8");
+    if (key === "\x03" || key === "q" || key === "\x1b") {
+      done = true;
+      cleanup();
+      process.exit(0);
+    } else if (key === "\r" || key === "\n") {
+      void jump();
+    } else if (key === "\x1b[A" || key === "k") {
+      moveCursor(-1);
+      render();
+    } else if (key === "\x1b[B" || key === "j") {
+      moveCursor(1);
+      render();
+    } else if (key === "o" || key === "\t") {
+      cycleTarget();
+    } else if (key === "r") {
+      void refresh();
+    }
+  }
+
+  // Setup terminal. We only have a "self" client to exclude when we're actually
+  // running inside a tmux client; from a plain terminal every attached client is
+  // a legitimate target (and tmux would otherwise report one of them as "self").
+  selfTty = insideTmux() ? await selfClientTty() : null;
+  out.write(ALT_ON + HIDE_CURSOR);
+  input.setRawMode?.(true);
+  input.resume();
+  input.setEncoding?.("utf8");
+  input.on("data", onKey);
+  process.on("SIGINT", () => {
+    done = true;
+    cleanup();
+    process.exit(0);
+  });
+
+  await refresh();
+  timer = setInterval(() => void refresh(), intervalMs);
+  // Advance the spinner only while something is working, so an all-idle board
+  // stays quiet (no needless repaints).
+  animTimer = setInterval(() => {
+    if (done || !statuses.some((s) => s.state === "working")) return;
+    frame++;
+    render();
+  }, ANIM_MS);
+}

package/src/regions.ts

@@ -0,0 +1,65 @@
+// Region extractors: pure string functions that slice the captured pane text
+// down to the part a rule cares about. Keeping these tiny and pure is what makes
+// the rule engine testable.
+
+import type { Region } from "./types.ts";
+
+// A "horizontal rule" line is one made mostly of box-drawing horizontals — the
+// borders Claude/Codex draw around their input box and section separators.
+const RULE_CHARS = /[─━╌╍]/g;
+
+function isRuleLine(line: string): boolean {
+  const matches = line.match(RULE_CHARS);
+  return matches !== null && matches.length >= 3;
+}
+
+function indicesOfRuleLines(lines: string[]): number[] {
+  const idx: number[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (isRuleLine(lines[i]!)) idx.push(i);
+  }
+  return idx;
+}
+
+// Everything below the last horizontal rule — isolates the live prompt area
+// from scrollback above it.
+export function afterLastHorizontalRule(lines: string[]): string[] {
+  const rules = indicesOfRuleLines(lines);
+  if (rules.length === 0) return lines;
+  const last = rules[rules.length - 1]!;
+  return lines.slice(last + 1);
+}
+
+// The interior of the input box: the lines between the last two horizontal
+// rules (the box's top and bottom borders). Falls back to the tail if there
+// aren't two borders to bracket.
+export function promptBoxBody(lines: string[]): string[] {
+  const rules = indicesOfRuleLines(lines);
+  if (rules.length < 2) return bottomNonEmptyLines(lines, 3);
+  const bottom = rules[rules.length - 1]!;
+  const top = rules[rules.length - 2]!;
+  return lines.slice(top + 1, bottom);
+}
+
+// The last N lines that aren't blank.
+export function bottomNonEmptyLines(lines: string[], n: number): string[] {
+  const out: string[] = [];
+  for (let i = lines.length - 1; i >= 0 && out.length < n; i--) {
+    if (lines[i]!.trim().length > 0) out.push(lines[i]!);
+  }
+  return out.reverse();
+}
+
+export function extractRegion(lines: string[], region: Region): string {
+  if (typeof region === "object") {
+    return bottomNonEmptyLines(lines, region.bottom_non_empty_lines).join("\n");
+  }
+  switch (region) {
+    case "full":
+      return lines.join("\n");
+    case "after_last_horizontal_rule":
+      return afterLastHorizontalRule(lines).join("\n");
+    case "prompt_box_body":
+      return promptBoxBody(lines).join("\n");
+  }
+}

package/src/render.ts

@@ -0,0 +1,139 @@
+// Terminal rendering: agents grouped by tmux session, with colored state dots
+// and a git column. No dependencies — raw ANSI. Falls back to plain text when
+// stdout isn't a TTY (piped) or NO_COLOR is set.
+
+import type { AgentState, AgentStatus, GitStatus } from "./types.ts";
+
+const useColor = process.stdout.isTTY === true && !process.env.NO_COLOR;
+
+export const color = (code: string, s: string) =>
+  useColor ? `\x1b[${code}m${s}\x1b[0m` : s;
+export const dim = (s: string) => color("2", s);
+export const bold = (s: string) => color("1", s);
+
+// Braille spinner frames for the "working" state (classic dots animation).
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+// The state indicator: a distinct *shape* per state (so it reads even without
+// color) plus color. "working" animates through the spinner; `frame` advances it.
+export function stateGlyph(state: AgentState, frame = 0): string {
+  switch (state) {
+    case "blocked":
+      return color("31", "●"); // red filled — needs you
+    case "working":
+      return color("33", SPINNER[frame % SPINNER.length]!); // yellow spinner
+    case "idle":
+      return color("32", "○"); // green hollow — waiting for input
+    case "unknown":
+      return color("90", "◌"); // grey dotted — unknown
+  }
+}
+
+export function gitCell(git: GitStatus | null): string {
+  if (!git || !git.branch) return dim("—");
+  let s = git.branch;
+  const marks: string[] = [];
+  if (git.ahead) marks.push(`↑${git.ahead}`);
+  if (git.behind) marks.push(`↓${git.behind}`);
+  if (git.dirty) marks.push(color("33", "✱"));
+  if (marks.length) s += " " + marks.join(" ");
+  return s;
+}
+
+// Pad by *visible* width, ignoring ANSI escapes.
+export function pad(s: string, width: number): string {
+  const visible = s.replace(/\x1b\[[0-9;]*m/g, "").length;
+  return s + " ".repeat(Math.max(0, width - visible));
+}
+
+const STATE_ORDER: Record<AgentState, number> = {
+  blocked: 0,
+  working: 1,
+  idle: 2,
+  unknown: 3,
+};
+
+export interface SessionGroup {
+  session: string;
+  agents: AgentStatus[];
+}
+
+// Group agents by tmux session (insertion order = tmux's session order), with
+// each session's agents sorted blocked→working→idle so the ones needing you
+// float to the top.
+export function groupBySession(statuses: AgentStatus[]): SessionGroup[] {
+  const groups = new Map<string, AgentStatus[]>();
+  for (const s of statuses) {
+    const key = s.pane.sessionName;
+    let list = groups.get(key);
+    if (!list) {
+      list = [];
+      groups.set(key, list);
+    }
+    list.push(s);
+  }
+  return [...groups.entries()].map(([session, agents]) => ({
+    session,
+    agents: agents.sort((a, b) => STATE_ORDER[a.state] - STATE_ORDER[b.state]),
+  }));
+}
+
+// One agent row: state glyph + pane id + agent + git. The glyph's shape+color
+// carries the state (● red blocked, spinner yellow working, ○ green idle); the
+// pane id is the jump reference. `cursor` renders a caret; `frame` animates the
+// working spinner.
+export function agentRow(s: AgentStatus, cursor = false, frame = 0): string {
+  const caret = cursor ? bold("❯ ") : "  ";
+  return (
+    caret +
+    `${stateGlyph(s.state, frame)} ` +
+    pad(s.pane.id, 6) +
+    pad(bold(s.agent), 10) +
+    gitCell(s.git)
+  );
+}
+
+export function renderGrouped(statuses: AgentStatus[], frame = 0): string {
+  if (statuses.length === 0) {
+    return dim("No AI agents detected in any tmux session.");
+  }
+  const lines: string[] = [];
+  for (const { session, agents } of groupBySession(statuses)) {
+    const blocked = agents.filter((a) => a.state === "blocked").length;
+    const suffix = blocked ? color("31", ` · ${blocked} blocked`) : "";
+    lines.push(bold(`▸ ${session}`) + dim(`  (${agents.length})`) + suffix);
+    for (const a of agents) lines.push(agentRow(a, false, frame));
+    lines.push("");
+  }
+  if (lines[lines.length - 1] === "") lines.pop();
+  return lines.join("\n");
+}
+
+export function renderJson(statuses: AgentStatus[]): string {
+  return JSON.stringify(
+    statuses.map((s) => ({
+      pane: s.pane.id,
+      agent: s.agent,
+      state: s.state,
+      matchedRule: s.matchedRule,
+      session: s.pane.sessionName,
+      window: s.pane.windowName,
+      path: s.pane.path,
+      git: s.git,
+    })),
+    null,
+    2,
+  );
+}
+
+export const CLEAR_SCREEN = "\x1b[2J\x1b[H";
+
+export function summaryLine(statuses: AgentStatus[]): string {
+  const counts = { blocked: 0, working: 0, idle: 0, unknown: 0 };
+  for (const s of statuses) counts[s.state]++;
+  const sessions = new Set(statuses.map((s) => s.pane.sessionName)).size;
+  return dim(
+    `${statuses.length} agent(s) across ${sessions} session(s) — ` +
+      `${counts.blocked} blocked, ${counts.working} working, ${counts.idle} idle`,
+  );
+}

package/src/scan.ts

@@ -0,0 +1,58 @@
+// One detection pass over every pane. Shared by the list, watch, and picker
+// modes. Threads per-pane memory across calls so "working" (content changed
+// since last look) and idle-debounce work in the live modes.
+
+import { capturePane, listPanes } from "./tmux.ts";
+import { createGitCache } from "./git.ts";
+import { resolveState, type PaneMemory } from "./detect.ts";
+import type { AgentStatus } from "./types.ts";
+
+export interface ScanOptions {
+  all: boolean;
+}
+
+export async function scan(
+  opts: ScanOptions,
+  memory: Map<string, PaneMemory>,
+): Promise<{ statuses: AgentStatus[]; memory: Map<string, PaneMemory> }> {
+  const panes = await listPanes({ all: opts.all });
+  const gitCache = createGitCache();
+  const nextMemory = new Map<string, PaneMemory>();
+
+  // Resolve concurrently but keep results in tmux pane order (session → window →
+  // pane) so the grouped view is stable across refreshes rather than ordered by
+  // whichever capture-pane happened to finish first.
+  const resolved = await Promise.all(
+    panes.map(async (pane): Promise<AgentStatus | null> => {
+      const lines = await capturePane(pane.id);
+      const resolution = resolveState(pane, lines, memory.get(pane.id));
+      if (!resolution) return null; // not an agent pane
+      nextMemory.set(pane.id, resolution.memory);
+      const git = await gitCache(pane.path);
+      return {
+        pane,
+        agent: resolution.agent,
+        state: resolution.state,
+        matchedRule: resolution.matchedRule,
+        git,
+      };
+    }),
+  );
+  const statuses = resolved.filter((s): s is AgentStatus => s !== null);
+  return { statuses, memory: nextMemory };
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+// Fire-once: sample twice with a short delay so "working" can be detected via
+// content change even without a persistent watcher.
+export async function scanOnce(
+  opts: ScanOptions,
+  delayMs: number,
+): Promise<AgentStatus[]> {
+  let memory = new Map<string, PaneMemory>();
+  ({ memory } = await scan(opts, memory));
+  await sleep(delayMs);
+  const { statuses } = await scan(opts, memory);
+  return statuses;
+}

package/src/tmux.ts

@@ -0,0 +1,173 @@
+// tmux glue. tmux has already done the hard part for us: #{pane_current_command}
+// is the foreground process's comm, and capture-pane hands us the rendered
+// screen for free. We just ask nicely.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { PaneInfo } from "./types.ts";
+
+const exec = promisify(execFile);
+
+async function tmux(args: string[]): Promise<string> {
+  const { stdout } = await exec("tmux", args, { maxBuffer: 16 * 1024 * 1024 });
+  return stdout;
+}
+
+// tmux sanitizes ANY control character in -F output (including our separator and
+// even newlines) to "_", so we can't pack multiple free-text fields into one
+// formatted line. Instead we query one field per call, each paired with the
+// pane id. pane_id is always "%<digits>" — it can't contain the "|" delimiter or
+// a newline — so we split once on the first "|" and the value may then contain
+// anything (spaces, "|", unicode) without ambiguity. Keying the merge by id
+// makes it robust to the pane set changing between calls.
+async function column(
+  scope: string[],
+  field: string,
+): Promise<Array<[string, string]>> {
+  const stdout = await tmux(["list-panes", ...scope, "-F", `#{pane_id}|${field}`]);
+  const rows: Array<[string, string]> = [];
+  for (const line of stdout.split("\n")) {
+    if (!line) continue;
+    const i = line.indexOf("|");
+    if (i < 0) continue;
+    rows.push([line.slice(0, i), line.slice(i + 1)]);
+  }
+  return rows;
+}
+
+export async function isServerRunning(): Promise<boolean> {
+  try {
+    await tmux(["list-panes", "-a"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Enumerate panes. Scope defaults to the current session when run inside tmux,
+// or all sessions with `all: true` (or when run outside tmux).
+export async function listPanes(opts: { all: boolean }): Promise<PaneInfo[]> {
+  const insideTmux = Boolean(process.env.TMUX);
+  const scope = opts.all || !insideTmux ? ["-a"] : ["-s"];
+
+  const [commands, pids, paths, titles, sessions, windows, windowIdx, actives] =
+    await Promise.all([
+      column(scope, "#{pane_current_command}"),
+      column(scope, "#{pane_pid}"),
+      column(scope, "#{pane_current_path}"),
+      column(scope, "#{pane_title}"),
+      column(scope, "#{session_name}"),
+      column(scope, "#{window_name}"),
+      column(scope, "#{window_index}"),
+      column(scope, "#{pane_active}"),
+    ]);
+
+  // Seed one PaneInfo per id from the first column, then fill from the rest.
+  // Keyed by id, so a pane appearing/vanishing mid-scan can't misalign fields.
+  const byId = new Map<string, PaneInfo>();
+  for (const [id] of commands) {
+    if (!byId.has(id)) {
+      byId.set(id, {
+        id,
+        command: "",
+        pid: 0,
+        path: "",
+        title: "",
+        sessionName: "",
+        windowName: "",
+        windowIndex: "",
+        active: false,
+      });
+    }
+  }
+  const fill = (rows: Array<[string, string]>, set: (p: PaneInfo, v: string) => void) => {
+    for (const [id, value] of rows) {
+      const p = byId.get(id);
+      if (p) set(p, value);
+    }
+  };
+  fill(commands, (p, v) => (p.command = v));
+  fill(pids, (p, v) => (p.pid = Number(v) || 0));
+  fill(paths, (p, v) => (p.path = v));
+  fill(titles, (p, v) => (p.title = v));
+  fill(sessions, (p, v) => (p.sessionName = v));
+  fill(windows, (p, v) => (p.windowName = v));
+  fill(windowIdx, (p, v) => (p.windowIndex = v));
+  fill(actives, (p, v) => (p.active = v === "1"));
+
+  return [...byId.values()];
+}
+
+// Capture the visible screen of a pane as plain text lines (no escape codes).
+// -p prints to stdout; trailing blank lines trimmed.
+export async function capturePane(paneId: string): Promise<string[]> {
+  const stdout = await tmux(["capture-pane", "-p", "-t", paneId]);
+  return stdout.replace(/\n+$/, "").split("\n");
+}
+
+// Move the *currently attached* tmux client to a pane: switch its session, then
+// select the window and pane. A pane id (%N) resolves up to its window/session,
+// so we only need the session name for switch-client. Use when already inside
+// tmux (process.env.TMUX set).
+export async function switchToPane(sessionName: string, paneId: string): Promise<void> {
+  await tmux(["switch-client", "-t", sessionName]);
+  await tmux(["select-window", "-t", paneId]);
+  await tmux(["select-pane", "-t", paneId]);
+}
+
+// Like switchToPane, but moves a *specific* client (by its tty) rather than the
+// current one. This is how the dashboard in one window drives another window:
+// select-window/select-pane set the agent session's active window+pane server-
+// side, and switch-client -c points that other client at it.
+export async function switchClientToPane(
+  clientTty: string,
+  sessionName: string,
+  paneId: string,
+): Promise<void> {
+  await tmux(["switch-client", "-c", clientTty, "-t", sessionName]);
+  await tmux(["select-window", "-t", paneId]);
+  await tmux(["select-pane", "-t", paneId]);
+}
+
+export interface TmuxClient {
+  tty: string; // client_tty, e.g. "/dev/ttys004" — the client's identity
+  session: string; // session it's currently attached to
+}
+
+// All attached clients. Uses the same "id | value" split trick as listPanes to
+// dodge tmux's control-character sanitization; client_tty never contains "|".
+export async function listClients(): Promise<TmuxClient[]> {
+  let stdout = "";
+  try {
+    stdout = await tmux(["list-clients", "-F", "#{client_tty}|#{client_session}"]);
+  } catch {
+    return [];
+  }
+  const clients: TmuxClient[] = [];
+  for (const line of stdout.split("\n")) {
+    if (!line) continue;
+    const i = line.indexOf("|");
+    if (i < 0) continue;
+    clients.push({ tty: line.slice(0, i), session: line.slice(i + 1) });
+  }
+  return clients;
+}
+
+// The tty of the client this process is running under (best effort). Used to
+// tell "this window" apart from the others when choosing a jump target.
+export async function selfClientTty(): Promise<string | null> {
+  try {
+    const tty = (await tmux(["display-message", "-p", "#{client_tty}"])).trim();
+    return tty || null;
+  } catch {
+    return null;
+  }
+}
+
+// Pre-select the target window/pane on the server (no client needed), so a
+// subsequent `tmux attach` lands with that pane active. Use when NOT inside
+// tmux — the caller then execs `tmux attach-session -t <sessionName>`.
+export async function preselectPane(paneId: string): Promise<void> {
+  await tmux(["select-window", "-t", paneId]);
+  await tmux(["select-pane", "-t", paneId]);
+}