@taicho-ai/cli 0.1.0

package/src/ui/browser-model.ts

@@ -0,0 +1,170 @@
+/** Plan 21 — the artifact browser's PURE model: scope resolution, filters, badges, run-grouping,
+ *  sorts, and the "N of M" honesty line. No Ink, no state — everything here is unit-testable with a
+ *  seeded workspace. The Shelf/Reader (ArtifactBrowser.tsx) render what this module returns.
+ *
+ *  Scopes (spec §2):
+ *   - "run"          — the delegation subtree of one foreground turn (gatherConversationArtifacts).
+ *   - "conversation" — the union over EVERY agent's conversation ledger (ledgers are per-agent; a
+ *                      foreground @agent turn audits to the TARGET agent's ledger, so reading root's
+ *                      alone would miss exactly the turns that docked the browser).
+ *   - "all"          — the whole store (latest version per id, by the manifest's construction),
+ *                      grouped by producing run so the widest scope reads as execution history. */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { type Artifact, artifactHandle } from "@taicho-ai/contracts/artifact";
+import { listArtifacts } from "@taicho-ai/framework/store/artifacts";
+import { listAnnotations } from "@taicho-ai/framework/store/annotations";
+import { loadLedger } from "@taicho-ai/framework/store/conversation";
+import { gatherConversationArtifacts } from "@taicho-ai/framework/core/conversation-artifacts";
+
+export type BrowserScope = "run" | "conversation" | "all";
+export type BrowserSort = "run" | "time" | "producer";
+
+export interface BrowserFilters {
+  producer?: string;
+  type?: string;
+  feedback?: "open" | "any";
+  verdict?: "pass" | "fail" | "any";
+  since?: "24h" | "7d" | "30d" | "all";
+  q?: string;
+}
+
+export interface RowBadges { openFeedback: number; approved: boolean; verdict?: "pass" | "fail"; }
+export type ShelfRow =
+  | { kind: "header"; label: string }
+  | { kind: "artifact"; artifact: Artifact; badges: RowBadges };
+
+const SINCE_MS: Record<Exclude<NonNullable<BrowserFilters["since"]>, "all">, number> = {
+  "24h": 24 * 3600_000,
+  "7d": 7 * 24 * 3600_000,
+  "30d": 30 * 24 * 3600_000,
+};
+
+function conversationAgents(ws: string): string[] {
+  const dir = join(ws, "conversations");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+}
+
+/** Merge, keeping the LATEST version per logical id, ordered created desc — the same discipline
+ *  gatherConversationArtifacts applies inside one run tree, applied across trees. */
+function mergeLatest(lists: Artifact[][]): Artifact[] {
+  const byId = new Map<string, Artifact>();
+  for (const list of lists) for (const a of list) {
+    const cur = byId.get(a.id);
+    if (!cur || a.version > cur.version) byId.set(a.id, a);
+  }
+  return [...byId.values()].sort((x, y) => y.created.localeCompare(x.created));
+}
+
+export function resolveScope(ws: string, scope: BrowserScope, opts: { rootRunId?: string } = {}): Artifact[] {
+  if (scope === "run") return opts.rootRunId ? gatherConversationArtifacts(ws, opts.rootRunId) : [];
+  if (scope === "conversation") {
+    const runIds = new Set<string>();
+    for (const agent of conversationAgents(ws))
+      for (const turn of loadLedger(ws, agent)) if (turn.runId) runIds.add(turn.runId);
+    return mergeLatest([...runIds].map((id) => gatherConversationArtifacts(ws, id)));
+  }
+  return listArtifacts(ws);
+}
+
+/** Cold-start "latest run": the newest ledger turn across every agent's conversation — a foreground
+ *  turn by definition (only user turns are audited). Undefined on a fresh workspace. */
+export function latestRunFallback(ws: string): string | undefined {
+  let best: { ts: string; runId: string } | undefined;
+  for (const agent of conversationAgents(ws))
+    for (const turn of loadLedger(ws, agent)) {
+      if (!turn.runId || !turn.timestamp) continue;
+      if (!best || turn.timestamp > best.ts) best = { ts: turn.timestamp, runId: turn.runId };
+    }
+  return best?.runId;
+}
+
+export function badgesFor(ws: string, a: Artifact): RowBadges {
+  const anns = listAnnotations(ws, artifactHandle(a));
+  let verdict: "pass" | "fail" | undefined;
+  for (const an of anns) if (an.verdict) verdict = an.verdict.pass ? "pass" : "fail"; // last verdict wins
+  return {
+    // "Open feedback" means ACTIONABLE: open feedback text or a FAILING verdict. A passing checker
+    // verdict is an open annotation too, but flagging it would tell the captain to act on a pass —
+    // and an approval (open by ledger mechanics) is state, not feedback.
+    openFeedback: anns.filter((an) => an.status === "open" && an.kind !== "approval" && (!an.verdict || !an.verdict.pass)).length,
+    approved: anns.some((an) => an.kind === "approval"),
+    verdict,
+  };
+}
+
+export function applyFilters(ws: string, arts: Artifact[], f: BrowserFilters, nowMs = Date.now()): Artifact[] {
+  const ql = f.q?.trim().toLowerCase();
+  return arts.filter((a) => {
+    if (f.producer && a.producer !== f.producer) return false;
+    if (f.type && a.type !== f.type) return false;
+    if (ql && !`${a.id} ${a.title} ${a.summary ?? ""}`.toLowerCase().includes(ql)) return false;
+    if (f.since && f.since !== "all") {
+      const age = nowMs - Date.parse(a.created);
+      if (!(age <= SINCE_MS[f.since])) return false;
+    }
+    if (f.feedback === "open" || (f.verdict && f.verdict !== "any")) {
+      const b = badgesFor(ws, a);
+      if (f.feedback === "open" && b.openFeedback === 0) return false;
+      if (f.verdict && f.verdict !== "any" && b.verdict !== f.verdict) return false;
+    }
+    return true;
+  });
+}
+
+function shortRun(runId: string): string {
+  const slash = runId.indexOf("/");
+  return slash === -1 ? runId : runId.slice(slash + 1);
+}
+
+export function ageLabel(created: string, nowMs = Date.now()): string {
+  const ms = nowMs - Date.parse(created);
+  if (isNaN(ms)) return "";
+  const secs = Math.floor(ms / 1000);
+  if (secs < 60) return `${Math.max(secs, 0)}s`;
+  const mins = Math.floor(secs / 60);
+  if (mins < 60) return `${mins}m`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h`;
+  return `${Math.floor(hours / 24)}d`;
+}
+
+/** Rows the Shelf renders. Only the all-runs scope with the default "run" sort gets group headers
+ *  (execution history); every flat sort/scope is artifact rows only, and `sel` indexes ONLY the
+ *  artifact rows — headers are never selectable. */
+export function shelfRows(ws: string, arts: Artifact[], scope: BrowserScope, sort: BrowserSort, nowMs = Date.now()): ShelfRow[] {
+  const row = (a: Artifact): ShelfRow => ({ kind: "artifact", artifact: a, badges: badgesFor(ws, a) });
+  if (scope !== "all" || sort === "time")
+    return [...arts].sort((x, y) => y.created.localeCompare(x.created)).map(row);
+  if (sort === "producer")
+    return [...arts].sort((x, y) => x.producer.localeCompare(y.producer) || y.created.localeCompare(x.created)).map(row);
+  // sort === "run": group by producing run, groups ordered by their newest member.
+  const groups = new Map<string, Artifact[]>();
+  for (const a of arts) {
+    const g = groups.get(a.runId) ?? [];
+    g.push(a);
+    groups.set(a.runId, g);
+  }
+  const ordered = [...groups.entries()].map(([runId, list]) => {
+    list.sort((x, y) => y.created.localeCompare(x.created));
+    return { runId, list, newest: list[0]!.created };
+  }).sort((x, y) => y.newest.localeCompare(x.newest));
+  const out: ShelfRow[] = [];
+  for (const g of ordered) {
+    out.push({ kind: "header", label: `── ${shortRun(g.runId)} · ${g.list.length} artifact${g.list.length === 1 ? "" : "s"} · ${ageLabel(g.newest, nowMs)}` });
+    for (const a of g.list) out.push(row(a));
+  }
+  return out;
+}
+
+/** The honesty line (spec §3): a filtered shelf announces itself, never impersonates the store. */
+export function countLine(matched: number, total: number): string {
+  if (matched === total) return `${total} artifact${total === 1 ? "" : "s"}`;
+  return `${matched} of ${total} match`;
+}
+
+/** The artifact rows in shelf order (what `sel` indexes). */
+export function artifactRows(rows: ShelfRow[]): Extract<ShelfRow, { kind: "artifact" }>[] {
+  return rows.filter((r): r is Extract<ShelfRow, { kind: "artifact" }> => r.kind === "artifact");
+}

package/src/ui/editor-handoff.ts

@@ -0,0 +1,51 @@
+/** Plan 23: hand the terminal to the captain's OWN editor to edit a file, then return control to Ink.
+ *
+ *  The old approach (spawn detached, stdio:"ignore") could never work for a TERMINAL editor — Ink owns
+ *  the tty (raw mode + full-screen render loop), so nano/vim never got it, and with no $EDITOR set it
+ *  just dead-ended on "no $EDITOR". Ink 7.1.0's `suspendTerminal()` fixes this properly: it releases the
+ *  terminal to a child process, then restores Ink's state and repaints. We wait for the editor to EXIT
+ *  before resuming, so the browser (which re-reads files on render) shows the saved changes on return.
+ *
+ *  Editor precedence: $EDITOR → $VISUAL → nano → vi. In a non-interactive context (tests, pipes) there
+ *  is no tty to hand off, so we skip the spawn and report the path — a test never launches a real editor. */
+import { spawn } from "node:child_process";
+
+/** The callback form of Ink 7.1.0's `useApp().suspendTerminal` — restores the terminal even on throw. */
+export type SuspendTerminal = (callback: () => void | Promise<void>) => Promise<void>;
+
+/** Runs the chosen editor over the file and resolves when it EXITS (rejects on spawn error, e.g. ENOENT).
+ *  Injectable so tests never launch a real process — the real one inherits the tty (stdio:"inherit"). */
+export type RunEditor = (cmd: string, args: string[]) => Promise<void>;
+
+const spawnEditor: RunEditor = (cmd, args) =>
+  new Promise<void>((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: "inherit" });
+    child.on("error", reject);
+    child.on("exit", () => resolve());
+  });
+
+export interface EditResult { ok: boolean; note: string }
+
+/** The editor to hand off to: $EDITOR → $VISUAL → nano (the near-universal terminal default). May carry
+ *  flags (e.g. "code --wait"); the caller splits it. */
+export function pickEditor(): string {
+  return process.env.EDITOR || process.env.VISUAL || "nano";
+}
+
+export async function editFileInTerminal(suspendTerminal: SuspendTerminal, path: string, run: RunEditor = spawnEditor): Promise<EditResult> {
+  const editor = pickEditor();
+  const name = path.split("/").pop() ?? path;
+  // No interactive terminal to hand off (tests, headless, a pipe) → don't launch anything.
+  if (!process.stdin.isTTY) return { ok: false, note: `not an interactive terminal — open it yourself: ${path}` };
+  try {
+    await suspendTerminal(() => {
+      // $EDITOR may carry flags ("code --wait", "code -w"); split so the command + its args are honored.
+      const [cmd, ...args] = editor.split(/\s+/).filter(Boolean);
+      return run(cmd!, [...args, path]);
+    });
+    return { ok: true, note: `✓ ${name} saved — reloaded` };
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException)?.code;
+    return { ok: false, note: `⚠ couldn't open "${editor}"${code ? ` (${code})` : ""} — set $EDITOR, or open: ${path}` };
+  }
+}

package/src/ui/input-history.ts

@@ -0,0 +1,55 @@
+/** Plan 24: session message history + a ↑/↓ navigator. `idx` is an offset from the NEWEST entry: -1 means
+ *  "on the live draft" (not in history yet), 0 = newest, list.length-1 = oldest. Stepping up the first
+ *  time stashes the current draft so stepping all the way back down restores it (shell-style). Pure +
+ *  deterministic. loadHistory/appendHistory persist across sessions in a per-workspace dot-file. */
+import { existsSync, readFileSync, appendFileSync } from "node:fs";
+import { paths } from "@taicho-ai/framework/store/files";
+
+export const HISTORY_CAP = 500;
+
+export function pushHistory(list: string[], entry: string, cap = HISTORY_CAP): string[] {
+  const e = entry.trim();
+  if (!e) return list;
+  if (list.length && list[list.length - 1] === e) return list; // ignore consecutive dupes
+  const next = [...list, e];
+  return next.length > cap ? next.slice(next.length - cap) : next;
+}
+
+export interface HistNav { idx: number; draft: string }
+export const histStart = (): HistNav => ({ idx: -1, draft: "" });
+
+/** Step to an OLDER entry. `current` is the buffer's current text (stashed as the draft on the first step). */
+export function histPrev(nav: HistNav, list: string[], current: string): { nav: HistNav; value: string } | null {
+  if (!list.length) return null;
+  const draft = nav.idx === -1 ? current : nav.draft;
+  const idx = Math.min(nav.idx + 1, list.length - 1);
+  if (idx === nav.idx) return null; // already at the oldest
+  return { nav: { idx, draft }, value: list[list.length - 1 - idx]! };
+}
+
+/** Step to a NEWER entry, or back to the stashed draft when leaving history. */
+export function histNext(nav: HistNav, list: string[]): { nav: HistNav; value: string } | null {
+  if (nav.idx === -1) return null; // already on the draft
+  const idx = nav.idx - 1;
+  if (idx === -1) return { nav: { idx: -1, draft: "" }, value: nav.draft };
+  return { nav: { idx, draft: nav.draft }, value: list[list.length - 1 - idx]! };
+}
+
+// ── persistence (per-workspace dot-file; gitignored) ─────────────────────────────────────────────
+
+export function loadHistory(ws: string): string[] {
+  const f = paths.inputHistoryFile(ws);
+  if (!existsSync(f)) return [];
+  const lines = readFileSync(f, "utf8").split("\n").map((l) => l.trim()).filter(Boolean);
+  const out: string[] = [];
+  for (const l of lines) if (out[out.length - 1] !== l) out.push(l); // collapse consecutive dupes
+  return out.length > HISTORY_CAP ? out.slice(out.length - HISTORY_CAP) : out;
+}
+
+export function appendHistory(ws: string, entry: string): void {
+  const e = entry.trim();
+  if (!e) return;
+  const cur = loadHistory(ws);
+  if (cur[cur.length - 1] === e) return;
+  appendFileSync(paths.inputHistoryFile(ws), e + "\n");
+}

package/src/ui/input-keys.ts

@@ -0,0 +1,51 @@
+/** Plan 24: map one Ink keypress to a semantic editing action. This is the ONE place the cross-platform
+ *  key detection lives. Ink 7.1.0 normalizes Option/Alt into `key.meta` (via ESC-prefix like `\x1b\x7f`,
+ *  and via the kitty keyboard protocol). We also bind Ctrl+W → delete-word-back, the readline-universal
+ *  fallback that works even on macOS Terminal.app/iTerm2 when "Use Option as Meta" is OFF. Word MOVE is
+ *  bound to meta+arrow and meta+b / meta+f; word DELETE to meta+backspace / meta+delete, Alt+d, Ctrl+W. */
+import type { Key } from "ink";
+
+export type InputAction =
+  | { kind: "insert"; text: string } | { kind: "newline" }
+  | { kind: "backspace" } | { kind: "del" }
+  | { kind: "left" } | { kind: "right" } | { kind: "home" } | { kind: "end" }
+  | { kind: "wordLeft" } | { kind: "wordRight" } | { kind: "deleteWordBack" } | { kind: "deleteWordForward" }
+  | { kind: "submit" } | { kind: "historyPrev" } | { kind: "historyNext" } | { kind: "noop" };
+
+export function classifyKey(input: string, key: Key): InputAction {
+  // Newline (multi-line): Shift+Enter (kitty-protocol terminals), Alt/Option+Enter, or Ctrl+J. Ctrl+J is
+  // the terminal-agnostic fallback: legacy terminals send a raw linefeed `\n`; under the kitty protocol it
+  // arrives as `input:"j", key.ctrl` (a CSI-u sequence), so accept both so it behaves identically either way.
+  if (input === "\n" || (key.ctrl && input === "j") || (key.return && (key.shift || key.meta)))
+    return { kind: "newline" };
+  if (key.return) return { kind: "submit" };
+  if (key.tab || key.escape) return { kind: "noop" }; // owned by the suggester / higher dispatch
+
+  // Word DELETE (check before plain backspace/delete).
+  if (key.ctrl && (input === "w" || input === "\x17")) return { kind: "deleteWordBack" }; // Ctrl+W
+  if (key.meta && key.backspace) return { kind: "deleteWordBack" };
+  if (key.meta && key.delete) return { kind: "deleteWordForward" };
+  if (key.meta && input === "d") return { kind: "deleteWordForward" };
+
+  // Word MOVE (check before plain arrows).
+  if (key.meta && key.leftArrow) return { kind: "wordLeft" };
+  if (key.meta && key.rightArrow) return { kind: "wordRight" };
+  if (key.meta && input === "b") return { kind: "wordLeft" };
+  if (key.meta && input === "f") return { kind: "wordRight" };
+
+  // Plain motions + deletes.
+  if (key.backspace) return { kind: "backspace" };
+  if (key.delete) return { kind: "del" };
+  if (key.leftArrow) return { kind: "left" };
+  if (key.rightArrow) return { kind: "right" };
+  if (key.home || (key.ctrl && input === "a")) return { kind: "home" };
+  if (key.end || (key.ctrl && input === "e")) return { kind: "end" };
+  if (key.upArrow) return { kind: "historyPrev" };
+  if (key.downArrow) return { kind: "historyNext" };
+
+  // Any remaining ctrl/meta combo is a shortcut we don't own — never insert control chars.
+  if (key.ctrl || key.meta) return { kind: "noop" };
+  // Printable text (Ink hands a paste as one multi-char `input`).
+  if (input && input !== "\r" && input !== "\n") return { kind: "insert", text: input };
+  return { kind: "noop" };
+}

package/src/ui/input.ts

@@ -0,0 +1,18 @@
+/** Pure REPL line classifier: slash command, @address, or bare chat (-> root). */
+export type ParsedInput =
+  | { kind: "slash"; cmd: string; arg: string }
+  | { kind: "address"; to: string; text: string }
+  | { kind: "chat"; text: string };
+
+export function parseInput(value: string): ParsedInput {
+  const t = value.trim();
+  if (t.startsWith("/")) {
+    const [cmd, ...rest] = t.slice(1).split(/\s+/);
+    return { kind: "slash", cmd, arg: rest.join(" ") };
+  }
+  if (t.startsWith("@")) {
+    const m = /^@([a-z][a-z0-9-]*)\s*([\s\S]*)$/.exec(t);
+    if (m) return { kind: "address", to: m[1], text: m[2] };
+  }
+  return { kind: "chat", text: t };
+}

package/src/ui/markdown-stream.ts

@@ -0,0 +1,31 @@
+/** Incremental markdown streaming: given the accumulated buffer, report which top-level markdown
+ *  blocks are COMPLETE (safe to render) vs the still-growing tail. Uses marked's lexer — every
+ *  content token except the last is stable; the last may still grow (an open code fence / list is a
+ *  single token that stays in `tail` until it closes). Pure + deterministic. */
+import { Marked } from "marked";
+
+const lexerMd = new Marked();
+
+// Block types that can still GROW by absorbing a following block across a blank line (a loose list
+// gains items; a blockquote gains lazy lines; html gains lines). Committing one on a trailing blank
+// line would let a later delta shift its boundary — so these stay in the tail until a different
+// block begins after them. Every other type (heading, paragraph, closed code fence, hr, table) is
+// final the moment a blank line follows it.
+const MERGEABLE = new Set(["list", "blockquote", "html"]);
+
+export interface BlockSplit { blocks: string[]; tail: string }
+
+export function splitCompletedBlocks(buffer: string): BlockSplit {
+  if (!buffer.trim()) return { blocks: [], tail: buffer };
+  const tokens = lexerMd.lexer(buffer).filter((t) => t.type !== "space"); // drop blank-line tokens
+  if (tokens.length === 0) return { blocks: [], tail: buffer };
+  const last = tokens[tokens.length - 1]!;
+  // A block is complete when a later block already follows it — OR when it is the last block but a
+  // trailing blank line proves it closed AND its type can't later absorb the next block. This lets a
+  // finished heading/paragraph/fence reveal as soon as its blank line lands, instead of waiting for
+  // the next block's first token (so the stream breaks on blocks, never showing a raw partial line).
+  if (/\n[ \t]*\n[ \t]*$/.test(buffer) && !MERGEABLE.has(last.type))
+    return { blocks: tokens.map((t) => t.raw), tail: "" };
+  if (tokens.length === 1) return { blocks: [], tail: buffer };
+  return { blocks: tokens.slice(0, -1).map((t) => t.raw), tail: last.raw };
+}

package/src/ui/markdown.ts

@@ -0,0 +1,45 @@
+/** Markdown → ANSI for the terminal REPL. A thin, owned wrapper over marked + marked-terminal
+ *  (we don't use the dormant ink-markdown package). Pure + synchronous + memoized, so it's cheap to
+ *  call from render. One Marked instance per width (marked-terminal wraps to a fixed width). */
+import { Marked } from "marked";
+import chalk from "chalk";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+// @ts-ignore marked-terminal has no types, but the API is stable
+import { markedTerminal } from "marked-terminal";
+
+const byWidth = new Map<number, Marked>();
+function mdFor(width: number): Marked {
+  let m = byWidth.get(width);
+  if (!m) {
+    // reflowText makes paragraphs wrap to `width`; unescape keeps entities readable.
+    // showSectionPrefix: false removes the markdown markers from output (e.g., # from headings).
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    m = new Marked(markedTerminal({ width, reflowText: true, unescape: true, showSectionPrefix: false }) as any);
+    byWidth.set(width, m);
+  }
+  return m;
+}
+
+const cache = new Map<string, string>();
+
+export function renderMarkdown(text: string, width = 80): string {
+  const key = `${width}:${text}`;
+  const hit = cache.get(key);
+  if (hit !== undefined) return hit;
+  // marked-terminal both styles text AND strips markdown markers (**bold**, `-` lists, `#`) via chalk.
+  // When chalk auto-detects NO color (level 0 — common in a compiled binary / non-TTY / the Ink
+  // runtime) it returns the markdown almost RAW, markers intact — so agent replies show as literal
+  // `**text**`. taicho is a color TUI, so force a color level for the SYNCHRONOUS render and restore
+  // it immediately (a scoped, self-undoing bump — not a permanent global mutation). Respect NO_COLOR.
+  const prevLevel = chalk.level;
+  if (prevLevel === 0 && !process.env.NO_COLOR) chalk.level = 3;
+  let out: string;
+  try {
+    out = (mdFor(width).parse(text) as string).replace(/\n+$/, "");
+  } finally {
+    chalk.level = prevLevel;
+  }
+  if (cache.size > 500) cache.clear(); // bound the memo; a REPL session shouldn't hoard forever
+  cache.set(key, out);
+  return out;
+}

package/src/ui/org-browser-model.ts

@@ -0,0 +1,43 @@
+/** Plan 22 — the Org browser's PURE model: the rows each scope renders, and the small guards the UI
+ *  needs. No Ink, no state — everything here reads the store (like browser-model.ts) and is unit-testable
+ *  with a seeded workspace. OrgBrowser.tsx renders what this returns. */
+import type { Database } from "bun:sqlite";
+import { listTeams, membersOf } from "@taicho-ai/framework/store/teams";
+import { loadIndex } from "@taicho-ai/framework/store/roster";
+import { DEFAULT_TEAM_ID } from "@taicho-ai/contracts/team";
+
+export type OrgScope = "teams" | "agents";
+
+export interface TeamRow { id: string; charter: string; lead?: string; members: string[]; }
+export interface AgentRow { id: string; role: string; isRoot: boolean; teams: string[]; }
+
+/** Every team, with its members resolved from the join. The default team is included — it IS the squad,
+ *  and the Org browser is where the captain sees the whole org (unlike the terse /agents list). */
+export function teamRows(ws: string, db: Database): TeamRow[] {
+  return listTeams(ws).map((t) => ({ id: t.id, charter: t.charter, lead: t.lead, members: membersOf(db, t.id).map((m) => m.id) }));
+}
+
+/** Every agent, with its EXPLICIT teams (default dropped — every agent is on it, so it carries no signal
+ *  in a per-row list). Sorted by id, root first is NOT forced — id order keeps navigation deterministic. */
+export function agentRows(db: Database): AgentRow[] {
+  return loadIndex(db)
+    .map((r) => ({ id: r.id, role: r.role, isRoot: !!r.is_root, teams: (r.teams ?? []).filter((t) => t !== DEFAULT_TEAM_ID) }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/** Root and the librarian are the squad's fixtures — they cannot be retired (deleteAgent enforces it too;
+ *  this is the UI-side guard that greys the verb). */
+export function isProtectedAgent(id: string): boolean {
+  return id === "root" || id === "librarian";
+}
+
+/** The default team cannot be deleted or have its membership set — everyone belongs to it. */
+export function isProtectedTeam(id: string): boolean {
+  return id === DEFAULT_TEAM_ID;
+}
+
+/** Wrap a selection index into [0, len) — shared by every list/cursor in the browser. */
+export function clampSel(sel: number, len: number): number {
+  if (len <= 0) return 0;
+  return Math.max(0, Math.min(sel, len - 1));
+}