herm-tui 1.0.0-dev.1

package/src/utils/sessions-db.ts

@@ -0,0 +1,396 @@
+/**
+ * sessions-db.ts — herm's window onto the Hermes session store.
+ *
+ * Architectural line: the Sessions tab is a **local state.db reader**.
+ * Stock tui_gateway covers ≈30% of what the tab needs — session.list
+ * returns {id, title, preview, started_at, message_count, source} and
+ * nothing else. There is no session.search, no lineage/children RPC,
+ * no arbitrary-id session.history, and session.title only retitles the
+ * *current* gateway session. Per herm policy we don't patch upstream,
+ * so everything richer than "which ids can the gateway resume" reads
+ * state.db directly. The gateway RPCs herm *does* use:
+ *
+ *   session.list   — source of truth for "resumable" (row.id is known
+ *                    to the connected gateway process)
+ *   session.delete — preferred over direct DELETE because it refuses
+ *                    to remove the active session and cleans transcript
+ *                    files; local remove() is the fallback
+ *
+ * All query functions here share ONE readonly connection and ONE
+ * parent→child classification rule. Upstream owns that semantic
+ * (hermes_state.py:893-970); if it changes, `kind()` is the only line
+ * that moves.
+ */
+
+import { Database, type Statement } from "bun:sqlite"
+import { homedir } from "os"
+import * as perf from "./perf"
+
+const HERMES = process.env.HERMES_HOME || `${process.env.HOME || homedir()}/.hermes`
+const PATH = `${HERMES}/state.db`
+// Source provenance mirrors hermes-home.ts makeSource("state.db") —
+// inlined to keep this module leaf (hermes-home re-exports from here).
+export type Source = { file: string; relative: string; label: string }
+const SRC: Source = { file: PATH, relative: "state.db", label: "state.db" }
+
+// ─── Connection ──────────────────────────────────────────────────────
+// One readonly handle, opened on first use. SQLite readonly connections
+// see writes from other processes (WAL or rollback), so the gateway
+// appending messages while herm holds this open is fine. Writes
+// (rename/remove) open a short-lived RW handle — rare enough that
+// pooling isn't worth it.
+
+let ro: Database | null = null
+
+/** Shared readonly handle. Null when state.db doesn't exist yet. */
+const stateDb = (): Database | null => {
+  if (ro) return ro
+  try { return (ro = new Database(PATH, { readonly: true })) }
+  catch { return null }
+}
+
+/** Test hook — drop the cached handle so the next call reopens. */
+export const resetDb = () => { ro?.close(); ro = null; stmts.clear() }
+
+// Prepared-statement cache keyed by SQL text. db.query() already
+// memoises internally, but holding our own map lets stats()/perf
+// count distinct statements and makes the no-db path trivially cheap.
+const stmts = new Map<string, Statement>()
+const q = (sql: string): Statement | null => {
+  const db = stateDb()
+  if (!db) return null
+  let s = stmts.get(sql)
+  if (!s) stmts.set(sql, (s = db.query(sql)))
+  return s
+}
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+/** A row from the sessions table enriched for the list/detail view. */
+export interface SessionRow {
+  source: Source
+  id: string
+  sessionSource: string
+  model: string | null
+  started_at: number
+  ended_at: number | null
+  end_reason: string | null
+  message_count: number
+  tool_call_count: number
+  input_tokens: number
+  output_tokens: number
+  cache_read_tokens: number
+  cache_write_tokens: number
+  reasoning_tokens: number
+  estimated_cost_usd: number | null
+  title: string | null
+  lastMessage: string | null
+  last_active: number | null
+  parent_session_id: string | null
+  /** Count of subagent children — see kind() === 'subagent'. */
+  subagent_count: number
+  /** Original root id when this row was tip-projected from a
+   *  compression chain; null otherwise. */
+  lineage_root_id: string | null
+}
+
+export interface LineageInfo {
+  continuesFrom?: { id: string; title: string | null }
+  compressedTo?: { id: string; title: string | null }
+}
+
+export interface SessionHit {
+  session_id: string
+  snippet: string
+  role: string
+  source: string
+  model: string | null
+  started_at: number
+  title: string | null
+}
+
+/** One raw message row for transcript peek. content is SUBSTR-capped
+ *  in SQL so multi-MB tool outputs don't allocate on read. */
+export interface PeekMsg {
+  role: "user" | "assistant" | "tool" | "system"
+  content: string | null
+  tool_name: string | null
+  /** JSON string of tool_calls when role='assistant' and the model
+   *  invoked tools instead of / as well as emitting content. */
+  tool_calls: string | null
+  at: number
+}
+
+// ─── parent→child classification ─────────────────────────────────────
+//
+// parent_session_id is overloaded across three unrelated relationships
+// in hermes-agent. The ONLY discriminator is (parent.end_reason,
+// child.started_at vs parent.ended_at):
+//
+//   subagent     — child started while parent was still live
+//                  (parent.ended_at NULL OR child.started_at < it)
+//   continuation — parent.end_reason='compression' AND child started
+//                  at/after parent.ended_at
+//   branch       — parent.end_reason='branched'    AND child started
+//                  at/after parent.ended_at
+//
+// This mirrors hermes_state.py compression-tip walker (:893-926) and
+// list_sessions_rich root filter (:956-971). Every query below derives
+// its WHERE from these three predicates — change the rule here, not
+// per-call. They take the child-table alias because queries variously
+// see the child as the outer `s` or an inner `c`.
+
+export type Kind = "root" | "subagent" | "continuation" | "branch"
+
+const SUB  = (c: string) => `(p.ended_at IS NULL OR ${c}.started_at < p.ended_at)`
+const CONT = (c: string) => `(p.end_reason = 'compression' AND ${c}.started_at >= p.ended_at)`
+const BR   = (c: string) => `(p.end_reason = 'branched'    AND ${c}.started_at >= p.ended_at)`
+
+/** Classify a child session given its parent. Pure — for tests and
+ *  any caller that already has both rows in hand. */
+export const kind = (
+  parent: { ended_at: number | null; end_reason: string | null } | null,
+  child: { started_at: number },
+): Kind => {
+  if (!parent) return "root"
+  if (parent.ended_at == null || child.started_at < parent.ended_at) return "subagent"
+  if (parent.end_reason === "compression") return "continuation"
+  if (parent.end_reason === "branched") return "branch"
+  return "subagent"
+}
+
+// ─── Shared SQL ──────────────────────────────────────────────────────
+
+// Column projection shared by roots()/children()/one(). Aliased `s`.
+// First-user-msg, last-user-msg, last-active, and subagent_count are
+// correlated subqueries — cheap at herm's DB sizes (thousands of rows)
+// and keeps the outer query a plain single-table scan.
+const COLS = `
+  s.id, s.source, s.model, s.started_at, s.ended_at, s.end_reason,
+  s.message_count, s.tool_call_count,
+  s.input_tokens, s.output_tokens,
+  s.cache_read_tokens, s.cache_write_tokens, s.reasoning_tokens,
+  s.estimated_cost_usd, s.parent_session_id,
+  COALESCE(s.title,
+    (SELECT SUBSTR(content,1,120) FROM messages
+     WHERE session_id = s.id AND role = 'user' ORDER BY id LIMIT 1)) AS title,
+  (SELECT SUBSTR(content,1,120) FROM messages
+   WHERE session_id = s.id AND role = 'user' ORDER BY id DESC LIMIT 1) AS lastMessage,
+  (SELECT MAX(timestamp) FROM messages WHERE session_id = s.id) AS last_active,
+  (SELECT COUNT(*) FROM sessions c
+   WHERE c.parent_session_id = s.id
+     AND (s.ended_at IS NULL OR c.started_at < s.ended_at)) AS subagent_count`
+
+type Raw = {
+  id: string; source: string; model: string | null
+  started_at: number; ended_at: number | null; end_reason: string | null
+  message_count: number; tool_call_count: number
+  input_tokens: number; output_tokens: number
+  cache_read_tokens: number; cache_write_tokens: number; reasoning_tokens: number
+  estimated_cost_usd: number | null; parent_session_id: string | null
+  title: string | null; lastMessage: string | null
+  last_active: number | null; subagent_count: number
+}
+
+const toRow = (r: Raw, lineage: string | null = null): SessionRow => ({
+  source: SRC,
+  id: r.id,
+  sessionSource: r.source,
+  model: r.model,
+  started_at: r.started_at,
+  ended_at: r.ended_at,
+  end_reason: r.end_reason,
+  message_count: r.message_count,
+  tool_call_count: r.tool_call_count,
+  input_tokens: r.input_tokens,
+  output_tokens: r.output_tokens,
+  cache_read_tokens: r.cache_read_tokens,
+  cache_write_tokens: r.cache_write_tokens,
+  reasoning_tokens: r.reasoning_tokens,
+  estimated_cost_usd: r.estimated_cost_usd,
+  title: r.title,
+  lastMessage: r.lastMessage,
+  last_active: r.last_active,
+  parent_session_id: r.parent_session_id,
+  subagent_count: r.subagent_count,
+  lineage_root_id: lineage,
+})
+
+/** Fetch one session by id with the full column projection. */
+const one = (id: string): Raw | null =>
+  (q(`SELECT ${COLS} FROM sessions s WHERE s.id = ?`)?.get(id) as Raw | undefined) ?? null
+
+/** Single session by id, or null if missing / db unavailable. */
+export const byId = (id: string): SessionRow | null => {
+  const r = one(id)
+  return r ? toRow(r) : null
+}
+
+/** Newest root TUI session that actually has messages. Target of `-c`
+ *  and source of the splash continue-prompt title. */
+export const lastReal = (): SessionRow | undefined =>
+  roots().find(r => r.message_count > 0 && r.sessionSource === "tui")
+
+// ─── Readers ─────────────────────────────────────────────────────────
+
+/** Root-level sessions, newest first, compression chains projected to
+ *  their tip (the resumable end), with lineage_root_id recording the
+ *  original root when projection happened. Mirrors list_sessions_rich. */
+export function roots(limit = 30): SessionRow[] {
+  const end = perf.mark("io:sessions.roots")
+  try {
+    // Root filter: no parent, OR parent link is a branch. Subagents
+    // and continuations are hidden — they surface via children()/
+    // lineage() instead. `p`/`c` aliases satisfy SUB/CONT/BR above.
+    const raw = (q(
+      `SELECT ${COLS} FROM sessions s
+       WHERE s.parent_session_id IS NULL
+          OR EXISTS (SELECT 1 FROM sessions p
+                     WHERE p.id = s.parent_session_id
+                       AND ${BR("s")})
+       ORDER BY s.started_at DESC
+       LIMIT ?`,
+    )?.all(limit) ?? []) as Raw[]
+
+    return raw.map((r) => {
+      if (r.end_reason !== "compression") return toRow(r)
+      const tid = tip(r.id)
+      if (tid === r.id) return toRow(r)
+      const t = one(tid)
+      // Tip stats replace the root's, but started_at stays the root's
+      // so chronological list order is preserved.
+      return t ? { ...toRow(t, r.id), started_at: r.started_at } : toRow(r)
+    })
+  } finally { end() }
+}
+
+/** Subagent children of a session, spawn-order. Each child carries its
+ *  own subagent_count so the tree view can recurse to N levels. */
+export function children(pid: string): SessionRow[] {
+  const end = perf.mark("io:sessions.children")
+  try {
+    return ((q(
+      `SELECT ${COLS} FROM sessions s
+       JOIN sessions p ON p.id = s.parent_session_id
+       WHERE s.parent_session_id = ? AND ${SUB("s")}
+       ORDER BY s.started_at ASC`,
+    )?.all(pid) ?? []) as Raw[]).map(r => toRow(r))
+  } finally { end() }
+}
+
+/** Compression-chain neighbours of a session. */
+export function lineage(sid: string): LineageInfo {
+  const end = perf.mark("io:sessions.lineage")
+  try {
+    const pred = q(
+      `SELECT p.id, p.title FROM sessions c
+       JOIN sessions p ON p.id = c.parent_session_id
+       WHERE c.id = ? AND ${CONT("c")}`,
+    )?.get(sid) as { id: string; title: string | null } | undefined
+    const succ = q(
+      `SELECT c.id, c.title FROM sessions c
+       JOIN sessions p ON p.id = c.parent_session_id
+       WHERE p.id = ? AND ${CONT("c")}
+       ORDER BY c.started_at DESC LIMIT 1`,
+    )?.get(sid) as { id: string; title: string | null } | undefined
+    return {
+      ...(pred && { continuesFrom: pred }),
+      ...(succ && { compressedTo: succ }),
+    }
+  } finally { end() }
+}
+
+/** Walk the compression chain forward to its live tip. Bounded at 100
+ *  links (upstream's defensive cap). */
+function tip(sid: string): string {
+  const step = q(
+    `SELECT c.id FROM sessions c
+     JOIN sessions p ON p.id = c.parent_session_id
+     WHERE p.id = ? AND ${CONT("c")}
+     ORDER BY c.started_at DESC LIMIT 1`,
+  )
+  let cur = sid
+  for (let i = 0; i < 100; i++) {
+    const next = step?.get(cur) as { id: string } | undefined
+    if (!next) return cur
+    cur = next.id
+  }
+  return cur
+}
+
+/** Last `n` raw message rows for a session, chronological. Content
+ *  is SUBSTR(…,400)'d in SQL — the peek view renders one line per
+ *  row, so anything past the first ~200 chars is wasted. Uses the
+ *  (session_id, timestamp) index; sub-ms for any realistic n. */
+export function peek(sid: string, n = 60): PeekMsg[] {
+  const end = perf.mark("io:sessions.peek")
+  try {
+    return ((q(
+      `SELECT role, SUBSTR(content,1,400) AS content, tool_name,
+              SUBSTR(tool_calls,1,400) AS tool_calls, timestamp AS at
+       FROM (SELECT * FROM messages WHERE session_id = ?
+             ORDER BY id DESC LIMIT ?)
+       ORDER BY id ASC`,
+    )?.all(sid, n) ?? []) as PeekMsg[])
+  } finally { end() }
+}
+
+// ─── Search ──────────────────────────────────────────────────────────
+// FTS5 over messages_fts — same table/triggers SessionDB builds, so
+// results match `hermes sessions search` and the session_search tool.
+
+// FTS5 treats - . ( ) " as syntax. Quote non-alnum tokens as phrases;
+// bare words get a * suffix so incremental typing narrows live.
+const fts = (s: string): string =>
+  s.trim().split(/\s+/).filter(Boolean)
+    .map(w => /^\w+$/.test(w) ? `${w}*` : `"${w.replace(/"/g, '""')}"`)
+    .join(" ")
+
+export function search(query: string, limit = 30): SessionHit[] {
+  const m = fts(query)
+  if (!m) return []
+  const end = perf.mark("io:sessions.search")
+  try {
+    const raw = (q(
+      `SELECT m.session_id, m.role,
+              snippet(messages_fts, 0, '>>>', '<<<', '...', 40) AS snippet,
+              s.source, s.model, s.started_at,
+              COALESCE(s.title, SUBSTR(m.content, 1, 120)) AS title
+       FROM messages_fts
+       JOIN messages m ON m.id = messages_fts.rowid
+       JOIN sessions s ON s.id = m.session_id
+       WHERE messages_fts MATCH ?
+       ORDER BY rank LIMIT ?`,
+    )?.all(m, limit * 4) ?? []) as Array<SessionHit & { session_id: string }>
+    const seen = new Set<string>()
+    return raw.filter(r =>
+      !seen.has(r.session_id) && (seen.add(r.session_id), true),
+    ).slice(0, limit)
+  } finally { end() }
+}
+
+// ─── Writes ──────────────────────────────────────────────────────────
+// Fresh RW handle per call — writes are rare (user-initiated) and a
+// long-lived writer would hold locks the gateway's own connection
+// wants. Callers should prefer the session.delete RPC and fall back
+// here only when the gateway is down.
+
+export function rename(sid: string, title: string): boolean {
+  const db = new Database(PATH)
+  try {
+    db.run("UPDATE sessions SET title = ? WHERE id = ?", [title, sid])
+    return (db.query("SELECT changes() AS c").get() as { c: number }).c > 0
+  } finally { db.close() }
+}
+
+/** Delete a session. Orphans children (matches upstream delete_session). */
+export function remove(sid: string): boolean {
+  const db = new Database(PATH)
+  try {
+    if (!db.query("SELECT 1 FROM sessions WHERE id = ?").get(sid)) return false
+    db.run("UPDATE sessions SET parent_session_id = NULL WHERE parent_session_id = ?", [sid])
+    db.run("DELETE FROM messages WHERE session_id = ?", [sid])
+    db.run("DELETE FROM sessions WHERE id = ?", [sid])
+    return true
+  } finally { db.close() }
+}

package/src/utils/subagent-tree.ts

@@ -0,0 +1,146 @@
+// Subagent tree aggregation for the Agents tab header + detail rollups.
+// Ink reference: ui-tui/src/lib/subagentTree.ts. Herm's wire data is
+// thinner (DelegationRecord has no tokens/cost; those arrive via
+// subagent.complete into `live`), so aggregate() takes both.
+
+import type { DelegationRecord } from "./gateway-types"
+
+// Per-node enrichment accumulated from subagent.* push events between
+// registry polls. Mirrors the `Live` shape in Agents.tsx.
+export type Live = {
+  tool_count?: number
+  input_tokens?: number
+  output_tokens?: number
+  cost_usd?: number
+  status?: string
+}
+
+export type Agg = {
+  agents: number
+  tools: number
+  dur: number
+  tok: number
+  cost: number
+  active: number
+  depth: number
+  hot: number
+}
+
+type Node = { rec: DelegationRecord; agg: Agg; kids: Node[] }
+
+const running = (s: string | undefined) => !s || s === "running" || s === "queued"
+
+export function tree(
+  recs: readonly DelegationRecord[],
+  live: ReadonlyMap<string, Live>,
+  now: number,
+): Node[] {
+  const ids = new Set(recs.map(r => r.subagent_id))
+  const by = new Map<string, DelegationRecord[]>()
+  for (const r of recs) {
+    const k = r.parent_id && ids.has(r.parent_id) ? r.parent_id : ""
+    ;(by.get(k) ?? by.set(k, []).get(k)!).push(r)
+  }
+  const build = (r: DelegationRecord): Node => {
+    const kids = (by.get(r.subagent_id) ?? []).map(build)
+    const lv = live.get(r.subagent_id) ?? {}
+    const dur = r.started_at != null ? Math.max(0, now - r.started_at) : 0
+    let a: Agg = {
+      agents: 1,
+      tools: lv.tool_count ?? r.tool_count ?? 0,
+      dur,
+      tok: (lv.input_tokens ?? 0) + (lv.output_tokens ?? 0),
+      cost: lv.cost_usd ?? 0,
+      active: running(lv.status ?? r.status) ? 1 : 0,
+      depth: 0,
+      hot: 0,
+    }
+    for (const k of kids) {
+      a = {
+        agents: a.agents + k.agg.agents,
+        tools: a.tools + k.agg.tools,
+        dur: a.dur + k.agg.dur,
+        tok: a.tok + k.agg.tok,
+        cost: a.cost + k.agg.cost,
+        active: a.active + k.agg.active,
+        depth: Math.max(a.depth, k.agg.depth + 1),
+        hot: 0,
+      }
+    }
+    a.hot = a.dur > 0 ? a.tools / a.dur : 0
+    return { rec: r, agg: a, kids }
+  }
+  return (by.get("") ?? []).map(build)
+}
+
+export function totals(nodes: readonly Node[]): Agg {
+  const z: Agg = { agents: 0, tools: 0, dur: 0, tok: 0, cost: 0, active: 0, depth: 0, hot: 0 }
+  for (const n of nodes) {
+    z.agents += n.agg.agents
+    z.tools += n.agg.tools
+    z.dur += n.agg.dur
+    z.tok += n.agg.tok
+    z.cost += n.agg.cost
+    z.active += n.agg.active
+    z.depth = Math.max(z.depth, n.agg.depth + 1)
+  }
+  z.hot = z.dur > 0 ? z.tools / z.dur : 0
+  return z
+}
+
+const SPARK = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"] as const
+
+export function spark(nodes: readonly Node[]): string {
+  const w: number[] = []
+  const walk = (ns: readonly Node[], d: number) => {
+    if (ns.length === 0) return
+    w[d] = (w[d] ?? 0) + ns.length
+    for (const n of ns) walk(n.kids, d + 1)
+  }
+  walk(nodes, 0)
+  if (w.length === 0) return ""
+  const max = Math.max(...w)
+  return w.map(v => v <= 0 ? " "
+    : SPARK[Math.min(7, Math.ceil((v / max) * 7))]).join("")
+}
+
+const tk = (n: number) =>
+  n < 1000 ? String(Math.round(n))
+  : n < 10_000 ? `${(n / 1000).toFixed(1)}k`
+  : `${Math.round(n / 1000)}k`
+
+const $$ = (n: number) =>
+  n <= 0 ? "" : n < 0.01 ? "<$0.01" : n < 10 ? `$${n.toFixed(2)}` : `$${n.toFixed(1)}`
+
+const sec = (s: number) => {
+  if (s < 60) return `${Math.round(s)}s`
+  const m = Math.floor(s / 60)
+  const r = Math.round(s - m * 60)
+  return r === 0 ? `${m}m` : `${m}m${r}s`
+}
+
+/** `d2 · 7 agents · 124 tools · 2m14s · 10k tok · $0.42 · ⚡3` */
+export function summary(a: Agg): string {
+  const p = [`d${a.depth}`, `${a.agents} agent${a.agents === 1 ? "" : "s"}`]
+  if (a.tools > 0) p.push(`${a.tools} tools`)
+  if (a.dur > 0) p.push(sec(a.dur))
+  if (a.tok > 0) p.push(`${tk(a.tok)} tok`)
+  if (a.cost > 0) p.push($$(a.cost))
+  if (a.active > 0) p.push(`⚡${a.active}`)
+  return p.join(" · ")
+}
+
+/** 0..(buckets-1) normalized against peak across all nodes. */
+export function heat(hot: number, peak: number, buckets: number): number {
+  if (hot <= 0 || peak <= 0 || buckets <= 1) return 0
+  return Math.min(buckets - 1, Math.round((Math.min(1, hot / peak)) * (buckets - 1)))
+}
+
+export function peak(nodes: readonly Node[]): number {
+  let p = 0
+  const walk = (ns: readonly Node[]) => {
+    for (const n of ns) { p = Math.max(p, n.agg.hot); walk(n.kids) }
+  }
+  walk(nodes)
+  return p
+}

package/src/utils/terminal-reset.ts

@@ -0,0 +1,129 @@
+// Reset sticky terminal modes. Ported from hermes-agent
+// ui-tui/src/lib/terminalModes.ts (v0.12.0, commits d05497f81 +
+// cad7944b9).
+//
+// Why this exists: @opentui/core only resets ?1049 (alt-screen) on
+// shutdown. If a prior TUI crashed with any of the modes below still
+// enabled — mouse reporting, focus events, bracketed paste, kitty
+// keyboard protocol — the terminal tab poisons the next process.
+// Symptoms: raw `[<35;12;8M` cursor-motion escapes dumped into the
+// composer, phantom focus events, paste wrapped in [200~...[201~,
+// kitty CSI-u sequences interpreted as literal input.
+//
+// We emit this on startup (self-heal a poisoned tab from a prior
+// crashed process) and on every exit path (so our own crash doesn't
+// poison the next shell prompt).
+
+import { writeSync } from "node:fs"
+
+export const TERMINAL_MODE_RESET =
+  "\x1b[0'z" +     // DEC locator reporting
+  "\x1b[0'{" +     // selectable locator events
+  "\x1b[?2029l" +  // passive mouse
+  "\x1b[?1016l" +  // SGR-pixels mouse
+  "\x1b[?1015l" +  // urxvt decimal mouse
+  "\x1b[?1006l" +  // SGR mouse
+  "\x1b[?1005l" +  // UTF-8 extended mouse
+  "\x1b[?1003l" +  // any-motion mouse
+  "\x1b[?1002l" +  // button-motion mouse
+  "\x1b[?1001l" +  // highlight mouse
+  "\x1b[?1000l" +  // click mouse
+  "\x1b[?9l" +     // X10 mouse
+  "\x1b[?1004l" +  // focus events
+  "\x1b[?2004l" +  // bracketed paste
+  "\x1b[?1049l" +  // alternate screen
+  "\x1b[<u" +      // kitty keyboard (pop stack)
+  "\x1b[>4;0m" +   // modifyOtherKeys → level 0
+  "\x1b[0m" +      // SGR attributes
+  "\x1b[?25h"      // cursor visible
+
+type ResettableStream = Pick<NodeJS.WriteStream, "isTTY" | "write"> & {
+  fd?: number
+}
+
+/**
+ * Synchronously emit the reset blob to `stream`.
+ *
+ * Returns true if the write succeeded. Skips non-TTY streams (piped
+ * stdout, test mocks) — ANSI reset on a plain pipe would corrupt
+ * downstream consumers.
+ *
+ * Prefers `fs.writeSync(fd, …)` over `stream.write(…)` because async
+ * writes don't flush when `process.exit()` terminates the loop.
+ * `stream.write` is the fallback for mocked streams where `fd` isn't
+ * a real kernel descriptor.
+ */
+export function resetTerminalModes(stream: ResettableStream = process.stdout): boolean {
+  if (!stream.isTTY) return false
+
+  const fd = typeof stream.fd === "number"
+    ? stream.fd
+    : stream === process.stdout ? 1 : undefined
+
+  if (fd !== undefined) {
+    try {
+      writeSync(fd, TERMINAL_MODE_RESET)
+      return true
+    } catch {
+      // Fall through to stream.write for mocked or unusual TTY streams.
+    }
+  }
+
+  try {
+    stream.write(TERMINAL_MODE_RESET)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Wire exit-path hooks so the reset blob fires on every shutdown
+ * route: clean exit, signals (SIGINT/SIGTERM/SIGHUP), and uncaught
+ * throws. Idempotent — calling more than once is a no-op.
+ *
+ * On signals we let the process continue to exit naturally after the
+ * reset; we don't `process.exit(code)` ourselves because that would
+ * race with OpenTUI's own signal handler (which has its own
+ * alt-screen cleanup). The reset is synchronous stdout writeSync, so
+ * it always lands before the process reaps.
+ */
+let wired = false
+export function installExitResetHooks(): void {
+  if (wired) return
+  wired = true
+
+  // Normal exit — fires on process.exit() and on main() falling off.
+  // `exit` handler must be synchronous (node discards async work).
+  process.on("exit", () => { resetTerminalModes() })
+
+  // Signals. Attaching a listener suppresses node's default terminate,
+  // so we must exit ourselves. OpenTUI's exitHandler was registered
+  // after ours (createCliRenderer runs later) and also listens here —
+  // but all it does is destroy(), whose terminal writes our reset blob
+  // already covers. writeSync flushes before exit() tears the fd.
+  const codes = { SIGHUP: 129, SIGINT: 130, SIGTERM: 143 } as const
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+    process.on(sig, () => {
+      resetTerminalModes()
+      process.exit(codes[sig])
+    })
+  }
+
+  // Uncaught throws. Emit reset before node prints the stack, so the
+  // traceback renders on a clean primary screen.
+  process.on("uncaughtException", err => {
+    resetTerminalModes()
+    // Re-throw via default behavior by writing + exiting after a tick.
+    // We print here instead of letting it reach the default handler
+    // because OpenTUI may have the alt-screen active and the default
+    // traceback would land there and disappear on exit.
+    console.error(err)
+    process.exit(1)
+  })
+  process.on("unhandledRejection", reason => {
+    resetTerminalModes()
+    console.error(reason)
+    process.exit(1)
+  })
+}