@a-t-h-i/bot-lobby 0.4.0 → 0.5.0

package/src/lobby/feed.ts

@@ -0,0 +1,253 @@
+/**
+ * What the lobby narrates: an activity log of plain-words tool steps from the
+ * Master and every subagent, a single place for thoughts, and the conversation
+ * with the Master stripped of tool rows and thinking. Bounded ring buffers in
+ * one module-level store (like the zen widget state), so every event source can
+ * write without a reference to the lobby, and the lobby repaints on `version`.
+ */
+import type { AgentRun } from "../schemas/findings.ts";
+import { agentName } from "../pi/run-summary.ts";
+
+export type ActivityKind = "info" | "success" | "warning" | "error";
+
+export interface ActivityEntry {
+  id: number;
+  at: number;
+  /** Who acted: MASTER, DEV, DESIGN, QA, RESEARCH, QUICK FIX, PLANNER, LOBBY. */
+  source: string;
+  text: string;
+  kind: ActivityKind;
+  /** Still in flight; rendered with an ellipsis until it settles. */
+  pending: boolean;
+  /** Correlates a start with its end (a tool call id or a run id). */
+  key?: string;
+}
+
+export interface ThoughtEntry {
+  id: number;
+  at: number;
+  source: string;
+  text: string;
+  /** The Master's thought still streaming. */
+  live: boolean;
+}
+
+export type ChatRole = "you" | "oracle" | "note";
+
+export interface ChatEntry {
+  id: number;
+  at: number;
+  role: ChatRole;
+  text: string;
+}
+
+export const MAX_ACTIVITY = 400;
+export const MAX_THOUGHTS = 40;
+export const MAX_CHAT = 200;
+/** Longest thought kept; a streaming thought keeps its newest text. */
+export const MAX_THOUGHT_TEXT = 4000;
+
+function bounded<T>(list: T[], max: number): T[] {
+  return list.length > max ? list.slice(-max) : list;
+}
+
+export class LobbyFeed {
+  activity: ActivityEntry[] = [];
+  thoughts: ThoughtEntry[] = [];
+  chat: ChatEntry[] = [];
+  /** The oracle's reply while it streams; cleared when the message ends. */
+  reply = "";
+  version = 0;
+  private nextId = 1;
+  private readonly listeners = new Set<() => void>();
+  /** Last step reported per run, so repeated run updates log each step once. */
+  private readonly runSteps = new Map<string, string>();
+  private readonly runThoughts = new Map<string, string>();
+  private readonly runStatus = new Map<string, AgentRun["status"]>();
+
+  onChange(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private touch(): void {
+    this.version += 1;
+    for (const listener of this.listeners) listener();
+  }
+
+  /** Settle every pending entry of `source` (optionally only the one keyed `key`). */
+  private settle(source: string | undefined, key: string | undefined, kind?: ActivityKind): boolean {
+    let changed = false;
+    for (const entry of this.activity) {
+      if (!entry.pending) continue;
+      if (key !== undefined ? entry.key !== key : entry.source !== source) continue;
+      entry.pending = false;
+      if (kind) entry.kind = kind;
+      changed = true;
+    }
+    return changed;
+  }
+
+  /** A one-off entry that is already done (a receipt, a transition, a note). */
+  log(source: string, text: string, kind: ActivityKind = "info", at = Date.now()): void {
+    this.activity = bounded([...this.activity, { id: this.nextId++, at, source, text, kind, pending: false }], MAX_ACTIVITY);
+    this.touch();
+  }
+
+  /** Open an in-flight step; `key` lets `end` settle exactly this one. */
+  begin(source: string, text: string, key?: string, at = Date.now()): void {
+    this.activity = bounded([...this.activity, { id: this.nextId++, at, source, text, kind: "info", pending: true, ...(key ? { key } : {}) }], MAX_ACTIVITY);
+    this.touch();
+  }
+
+  /** Settle the step opened with `key`; an error marks it. */
+  end(key: string, isError = false): void {
+    if (this.settle(undefined, key, isError ? "error" : undefined)) this.touch();
+  }
+
+  /** The next step of an agent that reports one step at a time: the previous one settles. */
+  step(source: string, text: string, key: string, at = Date.now()): void {
+    this.settle(undefined, key);
+    this.begin(source, text, key, at);
+  }
+
+  /** Stream the Master's (or any source's) live thought. */
+  thinkDelta(source: string, delta: string, at = Date.now()): void {
+    const last = this.thoughts.at(-1);
+    if (last && last.live && last.source === source) {
+      const text = last.text + delta;
+      last.text = text.length > MAX_THOUGHT_TEXT ? text.slice(-MAX_THOUGHT_TEXT) : text;
+    } else {
+      this.thoughts = bounded([...this.thoughts, { id: this.nextId++, at, source, text: delta.slice(-MAX_THOUGHT_TEXT), live: true }], MAX_THOUGHTS);
+    }
+    this.touch();
+  }
+
+  /** Close the live thought of `source`, replacing it with the final text when given. */
+  thinkEnd(source: string, text?: string): void {
+    const last = [...this.thoughts].reverse().find((entry) => entry.source === source && entry.live);
+    if (!last) {
+      if (text?.trim()) this.thought(source, text);
+      return;
+    }
+    last.live = false;
+    if (text?.trim()) last.text = text.trim().slice(-MAX_THOUGHT_TEXT);
+    if (!last.text.trim()) this.thoughts = this.thoughts.filter((entry) => entry !== last);
+    this.touch();
+  }
+
+  /** A finished thought from an agent that reports whole thoughts (subagents). */
+  thought(source: string, text: string, at = Date.now()): void {
+    const body = text.trim();
+    if (!body) return;
+    this.thoughts = bounded([...this.thoughts, { id: this.nextId++, at, source, text: body.slice(-MAX_THOUGHT_TEXT), live: false }], MAX_THOUGHTS);
+    this.touch();
+  }
+
+  /** Stream the oracle's reply text as it arrives. */
+  replyDelta(delta: string): void {
+    this.reply = (this.reply + delta).slice(-MAX_THOUGHT_TEXT);
+    this.touch();
+  }
+
+  /** The streamed reply is over; `say` records the final message. */
+  replyEnd(): void {
+    if (!this.reply) return;
+    this.reply = "";
+    this.touch();
+  }
+
+  say(role: ChatRole, text: string, at = Date.now()): void {
+    const body = text.trim();
+    if (!body) return;
+    this.chat = bounded([...this.chat, { id: this.nextId++, at, role, text: body }], MAX_CHAT);
+    this.touch();
+  }
+
+  /** Replace the conversation (seeding from the session when the lobby first opens). */
+  seedChat(entries: ReadonlyArray<{ role: ChatRole; text: string; at?: number }>): void {
+    this.chat = bounded(entries.filter((entry) => entry.text.trim()).map((entry) => ({ id: this.nextId++, at: entry.at ?? 0, role: entry.role, text: entry.text.trim() })), MAX_CHAT);
+    this.touch();
+  }
+
+  /**
+   * Fold streamed subagent run updates into the log: each new plain-words step
+   * opens an entry (settling the previous one), each new thought lands in the
+   * thinking pane, and a finished run settles with its outcome.
+   */
+  runs(runs: readonly AgentRun[], at = Date.now()): void {
+    for (const run of runs) {
+      const source = agentName(run);
+      const key = run.runId;
+      const before = this.runStatus.get(key);
+      this.runStatus.set(key, run.status);
+      if (before === undefined) this.log(source, `started as ${run.role}`, "info", at);
+      if (run.step && this.runSteps.get(key) !== run.step) {
+        this.runSteps.set(key, run.step);
+        this.step(source, run.step, key, at);
+      }
+      if (run.thought && this.runThoughts.get(key) !== run.thought) {
+        this.runThoughts.set(key, run.thought);
+        this.thought(source, run.thought, at);
+      }
+      if (run.status !== "running" && before !== run.status) {
+        this.settle(undefined, key);
+        const kind: ActivityKind = run.status === "success" ? (run.wrappedUp ? "warning" : "success") : run.status === "cancelled" ? "warning" : "error";
+        this.log(source, `${run.role} ${run.status === "success" ? "finished" : run.status}${run.error ? ` — ${run.error.split("\n")[0]}` : ""}`, kind, at);
+      }
+    }
+  }
+
+  clear(): void {
+    this.activity = [];
+    this.thoughts = [];
+    this.chat = [];
+    this.reply = "";
+    this.runSteps.clear();
+    this.runThoughts.clear();
+    this.runStatus.clear();
+    this.touch();
+  }
+}
+
+/** The process-wide lobby feed; the Master session is the only writer that matters. */
+export const lobbyFeed = new LobbyFeed();
+
+/** The text parts of a message's content, joined; thinking and tool calls are dropped. */
+export function textOf(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((part): part is { type: string; text: string } => typeof part === "object" && part !== null && (part as { type?: string }).type === "text" && typeof (part as { text?: unknown }).text === "string")
+    .map((part) => part.text)
+    .join("")
+    .trim();
+}
+
+/** The long kickoff message bot-lobby sends reads as a short note in the conversation. */
+export function chatText(role: "user" | "assistant", text: string): { role: ChatRole; text: string } | undefined {
+  const body = text.trim();
+  if (!body) return undefined;
+  if (role === "assistant") return { role: "oracle", text: body };
+  const kickoff = /^A bot-lobby task is active: (\S+)\nTitle: (.*)/.exec(body);
+  if (kickoff) return { role: "note", text: `task ${kickoff[1]} started — ${kickoff[2]}` };
+  const comment = /^The user left (?:a comment|\d+ comments) on (the approved plan|the proposal) of (\S+) from the lobby:/.exec(body);
+  if (comment) return { role: "note", text: `plan comment sent to the oracle for ${comment[2]}` };
+  return { role: "you", text: body };
+}
+
+/** Session entries (`{ type: "message", message }`) as conversation entries, oldest first. */
+export function chatFromEntries(entries: readonly unknown[], max = MAX_CHAT): Array<{ role: ChatRole; text: string; at?: number }> {
+  const chat: Array<{ role: ChatRole; text: string; at?: number }> = [];
+  for (const entry of entries) {
+    const record = entry as { type?: string; timestamp?: string; message?: { role?: string; content?: unknown } };
+    if (record?.type !== "message") continue;
+    const role = record.message?.role;
+    if (role !== "user" && role !== "assistant") continue;
+    const line = chatText(role, textOf(record.message?.content));
+    if (!line) continue;
+    const at = record.timestamp ? Date.parse(record.timestamp) : undefined;
+    chat.push({ ...line, ...(at !== undefined && Number.isFinite(at) ? { at } : {}) });
+  }
+  return chat.slice(-max);
+}

package/src/lobby/issues.ts

@@ -0,0 +1,227 @@
+/**
+ * GitHub issues through the `gh` CLI: list the repository's open issues, read
+ * one with its comments, and file a new one. `gh` owns authentication and repo
+ * detection, so bot-lobby holds no token; every failure becomes one readable
+ * line (not installed, not signed in, not a GitHub repository).
+ */
+import { execFile } from "node:child_process";
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+}
+
+/** Runs a command without a shell; `execCommand` in the extension, a fake in tests. */
+export type Exec = (command: string, args: string[], options?: { cwd?: string; timeout?: number }) => Promise<ExecResult>;
+
+/**
+ * `execFile` as an `Exec`: a non-zero exit resolves with its code and output,
+ * while a missing binary rejects with the spawn error (`ENOENT`), so the tab
+ * can say "gh is not installed" rather than "exited with code 1".
+ */
+export const execCommand: Exec = (command, args, options) =>
+  new Promise((resolve, reject) => {
+    execFile(command, args, { cwd: options?.cwd, timeout: options?.timeout, maxBuffer: 10 * 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => {
+      if (error && typeof (error as NodeJS.ErrnoException).code === "string") return reject(error);
+      const code = error ? (typeof (error as { code?: unknown }).code === "number" ? (error as { code: number }).code : 1) : 0;
+      resolve({ stdout: String(stdout), stderr: String(stderr), code });
+    });
+  });
+
+export interface IssueSummary {
+  number: number;
+  title: string;
+  labels: string[];
+  author?: string;
+  updatedAt?: string;
+  url?: string;
+}
+
+export interface IssueComment {
+  author?: string;
+  body: string;
+  createdAt?: string;
+}
+
+export interface IssueDetail extends IssueSummary {
+  body: string;
+  state?: string;
+  comments: IssueComment[];
+}
+
+const TIMEOUT_MS = 20_000;
+export const LIST_LIMIT = 50;
+
+/** One readable line for a failed `gh` call. */
+export function ghError(result: Partial<ExecResult> & { error?: string }): string {
+  const text = `${result.error ?? ""}\n${result.stderr ?? ""}`.trim();
+  if (result.code === 127 || /ENOENT|not found|command not found/i.test(text)) return "GitHub CLI (gh) is not installed — install it from https://cli.github.com and run `gh auth login`.";
+  if (/auth login|not logged|authentication|GH_TOKEN/i.test(text)) return "gh is not signed in — run `gh auth login` in a terminal.";
+  if (/not a git repository|no git remotes|could not determine|none of the git remotes/i.test(text)) return "This project has no GitHub remote gh can use.";
+  const first = text.split("\n").find((line) => line.trim()) ?? `gh exited with code ${result.code ?? "?"}`;
+  return first.length > 160 ? `${first.slice(0, 159)}…` : first;
+}
+
+async function gh(exec: Exec, cwd: string, args: string[]): Promise<string> {
+  let result: ExecResult;
+  try {
+    result = await exec("gh", args, { cwd, timeout: TIMEOUT_MS });
+  } catch (error) {
+    throw new Error(ghError({ error: (error as Error).message }));
+  }
+  if (result.code !== 0) throw new Error(ghError(result));
+  return result.stdout;
+}
+
+interface RawIssue {
+  number?: unknown;
+  title?: unknown;
+  body?: unknown;
+  state?: unknown;
+  url?: unknown;
+  updatedAt?: unknown;
+  author?: { login?: unknown } | null;
+  labels?: Array<{ name?: unknown }> | null;
+  comments?: Array<{ author?: { login?: unknown } | null; body?: unknown; createdAt?: unknown }> | null;
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function summary(raw: RawIssue): IssueSummary | undefined {
+  if (typeof raw.number !== "number" || typeof raw.title !== "string") return undefined;
+  const author = str(raw.author?.login);
+  const updatedAt = str(raw.updatedAt);
+  const url = str(raw.url);
+  return {
+    number: raw.number,
+    title: raw.title,
+    labels: (raw.labels ?? []).map((label) => str(label?.name)).filter((name): name is string => Boolean(name)),
+    ...(author ? { author } : {}),
+    ...(updatedAt ? { updatedAt } : {}),
+    ...(url ? { url } : {}),
+  };
+}
+
+function parseJson<T>(stdout: string): T {
+  try {
+    return JSON.parse(stdout) as T;
+  } catch {
+    throw new Error("gh returned output bot-lobby could not read");
+  }
+}
+
+export async function listIssues(exec: Exec, cwd: string, limit = LIST_LIMIT): Promise<IssueSummary[]> {
+  const stdout = await gh(exec, cwd, ["issue", "list", "--state", "open", "--limit", String(limit), "--json", "number,title,labels,author,updatedAt,url"]);
+  const raw = parseJson<RawIssue[]>(stdout);
+  return (Array.isArray(raw) ? raw : []).map(summary).filter((issue): issue is IssueSummary => Boolean(issue));
+}
+
+export async function viewIssue(exec: Exec, cwd: string, number: number): Promise<IssueDetail> {
+  const stdout = await gh(exec, cwd, ["issue", "view", String(number), "--json", "number,title,body,state,labels,author,url,updatedAt,comments"]);
+  const raw = parseJson<RawIssue>(stdout);
+  const base = summary(raw);
+  if (!base) throw new Error(`gh returned no issue #${number}`);
+  const state = str(raw.state);
+  return {
+    ...base,
+    body: typeof raw.body === "string" ? raw.body : "",
+    ...(state ? { state } : {}),
+    comments: (raw.comments ?? []).map((comment) => {
+      const author = str(comment?.author?.login);
+      const createdAt = str(comment?.createdAt);
+      return { body: typeof comment?.body === "string" ? comment.body : "", ...(author ? { author } : {}), ...(createdAt ? { createdAt } : {}) };
+    }),
+  };
+}
+
+/** First non-empty line is the title, the rest is the body. */
+export function splitIssueText(text: string): { title: string; body: string } {
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  const first = lines.findIndex((line) => line.trim());
+  if (first < 0) return { title: "", body: "" };
+  return { title: lines[first]!.trim().replace(/^#+\s*/, ""), body: lines.slice(first + 1).join("\n").trim() };
+}
+
+/** File an issue; returns its number and URL as `gh` prints it. */
+export async function createIssue(exec: Exec, cwd: string, title: string, body: string): Promise<{ number?: number; url: string }> {
+  if (!title.trim()) throw new Error("an issue needs a title (the first line)");
+  const stdout = await gh(exec, cwd, ["issue", "create", "--title", title.trim(), "--body", body.trim() || " "]);
+  const url = stdout.trim().split("\n").reverse().find((line) => /^https?:\/\//.test(line.trim()))?.trim() ?? stdout.trim();
+  const number = Number(/\/issues\/(\d+)/.exec(url)?.[1]);
+  return { url, ...(Number.isFinite(number) ? { number } : {}) };
+}
+
+/** The issue as text for the planner: body plus comments. */
+export function issueText(issue: IssueDetail): string {
+  const comments = issue.comments
+    .filter((comment) => comment.body.trim())
+    .map((comment) => `**${comment.author ?? "someone"}** commented:\n${comment.body.trim()}`);
+  return [issue.body.trim() || "(no description)", ...comments].join("\n\n");
+}
+
+/** Lobby state for the Issues tab: the list, the open issue, and what is loading. */
+export class IssuesState {
+  issues: IssueSummary[] = [];
+  details = new Map<number, IssueDetail>();
+  loading = false;
+  loaded = false;
+  error?: string;
+  notice?: string;
+  private readonly exec: Exec;
+  private readonly cwd: string;
+  private readonly onChange: () => void;
+
+  constructor(exec: Exec, cwd: string, onChange: () => void = () => {}) {
+    this.exec = exec;
+    this.cwd = cwd;
+    this.onChange = onChange;
+  }
+
+  async refresh(): Promise<void> {
+    if (this.loading) return;
+    this.loading = true;
+    this.error = undefined;
+    this.onChange();
+    try {
+      this.issues = await listIssues(this.exec, this.cwd);
+      this.loaded = true;
+    } catch (error) {
+      this.error = (error as Error).message;
+    } finally {
+      this.loading = false;
+      this.onChange();
+    }
+  }
+
+  async detail(number: number): Promise<IssueDetail | undefined> {
+    const cached = this.details.get(number);
+    if (cached) return cached;
+    try {
+      const detail = await viewIssue(this.exec, this.cwd, number);
+      this.details.set(number, detail);
+      this.onChange();
+      return detail;
+    } catch (error) {
+      this.error = (error as Error).message;
+      this.onChange();
+      return undefined;
+    }
+  }
+
+  async create(text: string): Promise<void> {
+    const { title, body } = splitIssueText(text);
+    try {
+      const created = await createIssue(this.exec, this.cwd, title, body);
+      this.notice = `created ${created.number ? `#${created.number}` : "issue"} — ${created.url}`;
+      this.error = undefined;
+      this.onChange();
+      await this.refresh();
+    } catch (error) {
+      this.error = (error as Error).message;
+      this.onChange();
+    }
+  }
+}

package/src/lobby/layout.ts

@@ -0,0 +1,174 @@
+/**
+ * Pure layout helpers for the lobby: exact-width cells, wrapped paragraphs,
+ * section rules, side-by-side columns and scroll windows. Every function takes
+ * its widths and heights explicitly and never reads a clock or the terminal,
+ * so each tab renders deterministically in tests.
+ */
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+/** Colours the lobby uses; a subset of pi's theme so tests can pass a plain stub. */
+export type LobbyColor =
+  | "accent"
+  | "text"
+  | "muted"
+  | "dim"
+  | "success"
+  | "warning"
+  | "error"
+  | "border"
+  | "borderAccent"
+  | "borderMuted"
+  | "toolTitle"
+  | "mdHeading"
+  | "mdCode";
+
+export interface LobbyTheme {
+  fg(color: LobbyColor, text: string): string;
+  bold(text: string): string;
+  italic?(text: string): string;
+  bg?(color: "selectedBg", text: string): string;
+}
+
+/** Paint only when a theme is present; tests without one get plain text. */
+export function paint(theme: LobbyTheme | undefined, color: LobbyColor, text: string): string {
+  return theme && text ? theme.fg(color, text) : text;
+}
+
+export function bold(theme: LobbyTheme | undefined, text: string): string {
+  return theme && text ? theme.bold(text) : text;
+}
+
+export function italic(theme: LobbyTheme | undefined, text: string): string {
+  return theme?.italic && text ? theme.italic(text) : text;
+}
+
+/** Exactly `width` columns: truncated with an ellipsis, or padded with spaces. */
+export function fit(text: string, width: number): string {
+  if (width <= 0) return "";
+  const cut = visibleWidth(text) > width ? truncateToWidth(text, width) : text;
+  const pad = width - visibleWidth(cut);
+  return pad > 0 ? `${cut}${" ".repeat(pad)}` : cut;
+}
+
+/** Word-wrap text (ANSI-safe) to `width`, keeping blank lines; tabs become spaces. */
+export function wrap(text: string, width: number): string[] {
+  if (width <= 0) return [];
+  const lines: string[] = [];
+  for (const raw of text.replace(/\t/g, "  ").split("\n")) {
+    if (!raw.trim()) {
+      lines.push("");
+      continue;
+    }
+    lines.push(...wrapTextWithAnsi(raw, width));
+  }
+  return lines;
+}
+
+/** Wrap with a hanging indent: the first line carries `lead`, the rest align under it. */
+export function wrapHanging(lead: string, text: string, width: number): string[] {
+  const indent = visibleWidth(lead);
+  const body = wrap(text, Math.max(1, width - indent));
+  if (body.length === 0) return [lead];
+  return body.map((line, index) => `${index === 0 ? lead : " ".repeat(indent)}${line}`);
+}
+
+/** `── Title ───────` spanning `width`; `right` sits at the far end when it fits. */
+export function rule(width: number, title = "", theme?: LobbyTheme, right = "", color: LobbyColor = "borderMuted"): string {
+  if (width <= 0) return "";
+  const head = title ? `── ${title} ` : "";
+  const tail = right ? ` ${right} ──` : "";
+  const fill = width - visibleWidth(head) - visibleWidth(tail);
+  if (fill < 1) return fit(paint(theme, color, head.trimEnd() || "─".repeat(width)), width);
+  const titled = title ? `${paint(theme, color, "── ")}${bold(theme, paint(theme, "accent", title))}${paint(theme, color, " ")}` : "";
+  const ending = right ? `${paint(theme, color, " ")}${paint(theme, "muted", right)}${paint(theme, color, " ──")}` : "";
+  return `${titled}${paint(theme, color, "─".repeat(fill))}${ending}`;
+}
+
+/** Exactly `height` lines: extra lines dropped from the end, missing ones blank. */
+export function fill(lines: readonly string[], height: number, width?: number): string[] {
+  const out = lines.slice(0, Math.max(0, height));
+  while (out.length < height) out.push("");
+  return width === undefined ? out : out.map((line) => fit(line, width));
+}
+
+/** The last `height` lines, shifted up by `offset` lines of scrollback. */
+export function tail(lines: readonly string[], height: number, offset = 0): string[] {
+  if (height <= 0) return [];
+  const end = Math.max(Math.min(lines.length, height), lines.length - Math.max(0, offset));
+  return lines.slice(Math.max(0, end - height), end);
+}
+
+/** The largest useful scroll-back offset for `lines` in a window of `height`. */
+export function maxOffset(lineCount: number, height: number): number {
+  return Math.max(0, lineCount - height);
+}
+
+/** First index to show so `selected` stays visible in a window of `height` rows. */
+export function windowStart(selected: number, count: number, height: number): number {
+  if (height <= 0 || count <= height) return 0;
+  const half = Math.floor(height / 2);
+  return Math.max(0, Math.min(count - height, selected - half));
+}
+
+/** Two columns side by side, each cell fitted to its width, `gap` columns apart. */
+export function columns(left: readonly string[], right: readonly string[], leftWidth: number, rightWidth: number, gap = " │ ", theme?: LobbyTheme): string[] {
+  const rows = Math.max(left.length, right.length);
+  const separator = paint(theme, "borderMuted", gap);
+  const out: string[] = [];
+  for (let i = 0; i < rows; i++) out.push(`${fit(left[i] ?? "", leftWidth)}${separator}${fit(right[i] ?? "", rightWidth)}`);
+  return out;
+}
+
+/** Split `width` into two columns plus a gap; the left gets `share` of the space. */
+export function split(width: number, share: number, gap = 3, minRight = 24): [number, number] {
+  const usable = Math.max(0, width - gap);
+  const left = Math.max(10, Math.min(usable - minRight, Math.round(usable * share)));
+  return [left, Math.max(0, usable - left)];
+}
+
+/** `12:04` in local time. */
+export function clock(at: number): string {
+  const date = new Date(at);
+  if (!Number.isFinite(date.getTime())) return "--:--";
+  return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+}
+
+/** Compact age: `now`, `45s`, `12m`, `3h`, `2d`. */
+export function ago(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 5_000) return "now";
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 48) return `${hours}h`;
+  return `${Math.floor(hours / 24)}d`;
+}
+
+/** `just now` or `12m ago`. */
+export function since(ms: number): string {
+  const age = ago(ms);
+  return age === "now" ? "just now" : `${age} ago`;
+}
+
+/** Highlight a selected row: the theme's selection background, or a leading marker without one. */
+export function selectRow(theme: LobbyTheme | undefined, text: string, width: number, selected: boolean, focused = true): string {
+  const cell = fit(text, width);
+  if (!selected) return cell;
+  if (theme?.bg && focused) return theme.bg("selectedBg", cell);
+  return cell;
+}
+
+export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+
+export function spinner(tick: number): string {
+  return SPINNER[((tick % SPINNER.length) + SPINNER.length) % SPINNER.length]!;
+}
+
+/** Light Markdown for plans and reports: headings bold without their `#`, everything else wrapped as written. */
+export function markdownLines(text: string, width: number, theme?: LobbyTheme): string[] {
+  return text.split("\n").flatMap((line) => {
+    const heading = /^#{1,6}\s+(.*)$/.exec(line);
+    return wrap(heading ? bold(theme, paint(theme, "mdHeading", heading[1]!)) : line, width);
+  });
+}