refactor(tui): /clean pass across ui-tui — 49 files, −217 LOC

Full codebase pass using the /clean doctrine (KISS/DRY, no one-off
helpers, no variables-used-once, pure functional where natural,
inlined obvious one-liners, killed dead exports, narrowed types,
spaced JSX). All contracts preserved — no RPC method, event name,
or exported type shape changed.

app/ — 15 files, -134 LOC
- inlined 4 one-off helpers (titleCase, isLong, statusToneFrom,
  focusOutside predicate)
- stores to arrow-const style (buildUiState, buildTurnState,
  buildOverlayState plus get/patch/reset triplets)
- functional slash/registry byName map (flatMap over for-loops)
- dropped dead param `live` in cancelOverlayFromCtrlC
- DRY'd duplicate shift() call in scrollWithSelection
- consolidated sections.push calls in /help

components/ — 12 files, -40 LOC
- extracted inline prop types to interfaces at file bottom (13×)
- inlined 6 one-off vars (pctLabel, logoW, heroW, cwd, title, hint)
- promoted HEART_COLORS + OPTS/LABELS to module scope
- JSX sibling spacing across 9 files
- un-shadowed `raw` in textInput
- components/thinking.tsx + components/markdown.tsx untouched
  (structurally load-bearing / edge-case-heavy)

config content domain protocol/ — 8 files, -77 LOC
- tightened 3 regexes (MOUSE_TRACKING, looksLikeSlashCommand,
  hasInterpolation — dropped stateful lastIndex dance)
- dead export ParsedSlashCommand removed
- MODES narrowed to `as const`, `.find(m => m === s)` replaces
  `.includes() ? (as cast) : null`
- fortunes.ts hash via reduce
- fmtDuration ternary chain
- inlined aboveViewport predicate in viewport.ts

hooks/ + lib/ — 9 files, -38 LOC
- ANSI_RE via String.fromCharCode(27) + WS_RE lifted to module
  scope (no more eslint-disable no-control-regex)
- compactPreview/edgePreview/thinkingPreview → ternary arrows
- useCompletion: hoisted pathReplace, moved stale-ref guard earlier
- useInputHistory: dropped useCallback wrapper (append is stable)
- useVirtualHistory: replaced 4× any with unknown + narrow
  MeasuredNode interface + one cast site

root TS — 3 files, -63 LOC
- banner.ts: parseRichMarkup via matchAll instead of exec/lastIndex,
  artWidth via reduce
- gatewayClient.ts: resolvePython candidate list collapse, inlined
  one-branch guards in dispatch/pushLog/drain/request
- types.ts: alpha-sorted ActiveTool / Msg / SudoReq / SecretReq
  members

eslint config
- disabled react-hooks/exhaustive-deps on packages/hermes-ink/**
  (compiled by react/compiler, deps live in $[N] memo arrays that
  eslint can't introspect) and removed the now-orphan in-file
  disable directive in ScrollBox.tsx

fixes (not from the cleaner pass)
- useComposerState: unlinkSync(file) + try/catch → rmSync(file,
  { force: true }) — kills the no-empty lint error and is more
  idiomatic
- useConfigSync: added setBellOnComplete + setVoiceEnabled to the
  two useEffect dep arrays (they're stable React setState setters;
  adding is safe and silences exhaustive-deps)

verification
- npx eslint src/ packages/ → 0 errors, 0 warnings
- npm run type-check → clean
- npm test → 50/50
- npm run build → 394.8kb ink-bundle.js, 11ms esbuild
- pytest tests/tui_gateway/ tests/test_tui_gateway_server.py
  tests/hermes_cli/test_tui_resume_flow.py
  tests/hermes_cli/test_tui_npm_install.py → 57/57

ui-tui/src/app/createGatewayEventHandler.ts

@@ -35,9 +35,6 @@ const dropBgTask = (taskId: string) =>
     return { ...state, bgTasks: next }
   })
 
-const statusToneFrom = (kind: string): 'error' | 'info' | 'warn' =>
-  kind === 'error' ? 'error' : kind === 'warn' || kind === 'approval' ? 'warn' : 'info'
-
 const pushUnique =
   (max: number) =>
   <T>(xs: T[], x: T): T[] =>
@@ -213,7 +210,10 @@ export function createGatewayEventHandler(ctx: GatewayEventHandlerContext): (ev:
 
         if (turnController.lastStatusNote !== p.text) {
           turnController.lastStatusNote = p.text
-          turnController.pushActivity(p.text, statusToneFrom(p.kind))
+          turnController.pushActivity(
+            p.text,
+            p.kind === 'error' ? 'error' : p.kind === 'warn' || p.kind === 'approval' ? 'warn' : 'info'
+          )
         }
 
         restoreStatusAfter(4000)

ui-tui/src/app/createSlashHandler.ts

@@ -7,10 +7,6 @@ import { findSlashCommand } from './slash/registry.js'
 import type { SlashRunCtx } from './slash/types.js'
 import { getUiState } from './uiStore.js'
 
-const titleCase = (name: string) => name.charAt(0).toUpperCase() + name.slice(1)
-
-const isLong = (text: string) => text.length > 180 || text.split('\n').filter(Boolean).length > 2
-
 export function createSlashHandler(ctx: SlashHandlerContext): (cmd: string) => boolean {
   const { gw } = ctx.gateway
   const { catalog } = ctx.local
@@ -79,8 +75,9 @@ export function createSlashHandler(ctx: SlashHandlerContext): (cmd: string) => b
 
         const body = r?.output || `/${parsed.name}: no output`
         const text = r?.warning ? `warning: ${r.warning}\n${body}` : body
+        const long = text.length > 180 || text.split('\n').filter(Boolean).length > 2
 
-        isLong(text) ? page(text, titleCase(parsed.name)) : sys(text)
+        long ? page(text, parsed.name[0]!.toUpperCase() + parsed.name.slice(1)) : sys(text)
       })
       .catch(() => {
         gw.request('command.dispatch', { arg: parsed.arg, name: parsed.name, session_id: sid })

ui-tui/src/app/overlayStore.ts

@@ -2,40 +2,25 @@ import { atom, computed } from 'nanostores'
 
 import type { OverlayState } from './interfaces.js'
 
-function buildOverlayState(): OverlayState {
-  return {
-    approval: null,
-    clarify: null,
-    modelPicker: false,
-    pager: null,
-    picker: false,
-    secret: null,
-    sudo: null
-  }
-}
+const buildOverlayState = (): OverlayState => ({
+  approval: null,
+  clarify: null,
+  modelPicker: false,
+  pager: null,
+  picker: false,
+  secret: null,
+  sudo: null
+})
 
 export const $overlayState = atom<OverlayState>(buildOverlayState())
 
-export const $isBlocked = computed($overlayState, state =>
-  Boolean(
-    state.approval || state.clarify || state.modelPicker || state.pager || state.picker || state.secret || state.sudo
-  )
+export const $isBlocked = computed($overlayState, ({ approval, clarify, modelPicker, pager, picker, secret, sudo }) =>
+  Boolean(approval || clarify || modelPicker || pager || picker || secret || sudo)
 )
 
-export function getOverlayState() {
-  return $overlayState.get()
-}
+export const getOverlayState = () => $overlayState.get()
 
-export function patchOverlayState(next: Partial<OverlayState> | ((state: OverlayState) => OverlayState)) {
-  if (typeof next === 'function') {
-    $overlayState.set(next($overlayState.get()))
+export const patchOverlayState = (next: Partial<OverlayState> | ((state: OverlayState) => OverlayState)) =>
+  $overlayState.set(typeof next === 'function' ? next($overlayState.get()) : { ...$overlayState.get(), ...next })
 
-    return
-  }
-
-  $overlayState.set({ ...$overlayState.get(), ...next })
-}
-
-export function resetOverlayState() {
-  $overlayState.set(buildOverlayState())
-}
+export const resetOverlayState = () => $overlayState.set(buildOverlayState())

ui-tui/src/app/slash/commands/core.ts

@@ -9,12 +9,12 @@ import { patchUiState } from '../../uiStore.js'
 import type { SlashCommand } from '../types.js'
 
 const flagFromArg = (arg: string, current: boolean): boolean | null => {
-  const mode = arg.trim().toLowerCase()
-
   if (!arg) {
     return !current
   }
 
+  const mode = arg.trim().toLowerCase()
+
   if (mode === 'on') {
     return true
   }
@@ -46,14 +46,16 @@ export const coreCommands: SlashCommand[] = [
         sections.push({ text: `${ctx.local.catalog.skillCount} skill commands available — /skills to browse` })
       }
 
-      sections.push({
-        rows: [
-          ['/details [hidden|collapsed|expanded|cycle]', 'set agent detail visibility mode'],
-          ['/fortune [random|daily]', 'show a random or daily local fortune']
-        ],
-        title: 'TUI'
-      })
-      sections.push({ rows: HOTKEYS, title: 'Hotkeys' })
+      sections.push(
+        {
+          rows: [
+            ['/details [hidden|collapsed|expanded|cycle]', 'set agent detail visibility mode'],
+            ['/fortune [random|daily]', 'show a random or daily local fortune']
+          ],
+          title: 'TUI'
+        },
+        { rows: HOTKEYS, title: 'Hotkeys' }
+      )
 
       ctx.transcript.panel(ctx.ui.theme.brand.helpHeader, sections)
     }

ui-tui/src/app/slash/commands/ops.ts

@@ -9,7 +9,7 @@ export const opsCommands: SlashCommand[] = [
       const [subcommand, ...names] = arg.trim().split(/\s+/).filter(Boolean)
 
       if (subcommand !== 'disable' && subcommand !== 'enable') {
-        return // py prints lists / show / usage
+        return
       }
 
       if (!names.length) {

ui-tui/src/app/slash/commands/session.ts

@@ -109,7 +109,7 @@ export const sessionCommands: SlashCommand[] = [
     name: 'personality',
     run: (arg, ctx) => {
       if (!arg) {
-        return // py handles listing
+        return
       }
 
       ctx.gateway.rpc<ConfigSetResponse>('config.set', { key: 'personality', session_id: ctx.sid, value: arg }).then(
@@ -200,11 +200,6 @@ export const sessionCommands: SlashCommand[] = [
     }
   },
 
-  // The four shims below call `config.set` directly because Python's `slash.exec`
-  // worker is a separate subprocess — it writes config but does NOT fire the
-  // live side-effects (`skin.changed` event, agent.reasoning_config,
-  // agent.verbose_logging, per-session yolo flip). Direct RPC does.
-
   {
     help: 'switch theme skin (fires skin.changed)',
     name: 'skin',

ui-tui/src/app/slash/registry.ts

@@ -5,14 +5,8 @@ import type { SlashCommand } from './types.js'
 
 export const SLASH_COMMANDS: SlashCommand[] = [...coreCommands, ...sessionCommands, ...opsCommands]
 
-const byName = new Map<string, SlashCommand>()
+const byName = new Map<string, SlashCommand>(
+  SLASH_COMMANDS.flatMap(cmd => [cmd.name, ...(cmd.aliases ?? [])].map(name => [name, cmd] as const))
+)
 
-for (const cmd of SLASH_COMMANDS) {
-  byName.set(cmd.name, cmd)
-
-  for (const alias of cmd.aliases ?? []) {
-    byName.set(alias, cmd)
-  }
-}
-
-export const findSlashCommand = (name: string): SlashCommand | undefined => byName.get(name.toLowerCase())
+export const findSlashCommand = (name: string) => byName.get(name.toLowerCase())

ui-tui/src/app/turnStore.ts

@@ -2,6 +2,28 @@ import { atom } from 'nanostores'
 
 import type { ActiveTool, ActivityItem, SubagentProgress } from '../types.js'
 
+const buildTurnState = (): TurnState => ({
+  activity: [],
+  reasoning: '',
+  reasoningActive: false,
+  reasoningStreaming: false,
+  reasoningTokens: 0,
+  streaming: '',
+  subagents: [],
+  toolTokens: 0,
+  tools: [],
+  turnTrail: []
+})
+
+export const $turnState = atom<TurnState>(buildTurnState())
+
+export const getTurnState = () => $turnState.get()
+
+export const patchTurnState = (next: Partial<TurnState> | ((state: TurnState) => TurnState)) =>
+  $turnState.set(typeof next === 'function' ? next($turnState.get()) : { ...$turnState.get(), ...next })
+
+export const resetTurnState = () => $turnState.set(buildTurnState())
+
 export interface TurnState {
   activity: ActivityItem[]
   reasoning: string
@@ -14,34 +36,3 @@ export interface TurnState {
   tools: ActiveTool[]
   turnTrail: string[]
 }
-
-function buildTurnState(): TurnState {
-  return {
-    activity: [],
-    reasoning: '',
-    reasoningActive: false,
-    reasoningStreaming: false,
-    reasoningTokens: 0,
-    streaming: '',
-    subagents: [],
-    toolTokens: 0,
-    tools: [],
-    turnTrail: []
-  }
-}
-
-export const $turnState = atom<TurnState>(buildTurnState())
-
-export const getTurnState = () => $turnState.get()
-
-export const patchTurnState = (next: Partial<TurnState> | ((state: TurnState) => TurnState)) => {
-  if (typeof next === 'function') {
-    $turnState.set(next($turnState.get()))
-
-    return
-  }
-
-  $turnState.set({ ...$turnState.get(), ...next })
-}
-
-export const resetTurnState = () => $turnState.set(buildTurnState())

ui-tui/src/app/uiStore.ts

@@ -5,37 +5,24 @@ import { DEFAULT_THEME } from '../theme.js'
 
 import type { UiState } from './interfaces.js'
 
-function buildUiState(): UiState {
-  return {
-    bgTasks: new Set(),
-    busy: false,
-    compact: false,
-    detailsMode: 'collapsed',
-    info: null,
-    sid: null,
-    status: 'summoning hermes…',
-    statusBar: true,
-    theme: DEFAULT_THEME,
-    usage: ZERO
-  }
-}
+const buildUiState = (): UiState => ({
+  bgTasks: new Set(),
+  busy: false,
+  compact: false,
+  detailsMode: 'collapsed',
+  info: null,
+  sid: null,
+  status: 'summoning hermes…',
+  statusBar: true,
+  theme: DEFAULT_THEME,
+  usage: ZERO
+})
 
 export const $uiState = atom<UiState>(buildUiState())
 
-export function getUiState() {
-  return $uiState.get()
-}
+export const getUiState = () => $uiState.get()
 
-export function patchUiState(next: Partial<UiState> | ((state: UiState) => UiState)) {
-  if (typeof next === 'function') {
-    $uiState.set(next($uiState.get()))
+export const patchUiState = (next: Partial<UiState> | ((state: UiState) => UiState)) =>
+  $uiState.set(typeof next === 'function' ? next($uiState.get()) : { ...$uiState.get(), ...next })
 
-    return
-  }
-
-  $uiState.set({ ...$uiState.get(), ...next })
-}
-
-export function resetUiState() {
-  $uiState.set(buildUiState())
-}
+export const resetUiState = () => $uiState.set(buildUiState())

ui-tui/src/app/useComposerState.ts

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process'
-import { mkdtempSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
@@ -97,11 +97,7 @@ export function useComposerState({ gw, onClipboardPaste, submitRef }: UseCompose
       }
     }
 
-    try {
-      unlinkSync(file)
-    } catch {
-      /* noop */
-    }
+    rmSync(file, { force: true })
   }, [input, inputBuf, submitRef])
 
   const actions = useMemo(

ui-tui/src/app/useConfigSync.ts

@@ -15,23 +15,16 @@ import { patchUiState } from './uiStore.js'
 const MTIME_POLL_MS = 5000
 
 const applyDisplay = (cfg: ConfigFullResponse | null, setBell: (v: boolean) => void) => {
-  const display = cfg?.config?.display ?? {}
+  const d = cfg?.config?.display ?? {}
 
-  setBell(!!display.bell_on_complete)
+  setBell(!!d.bell_on_complete)
   patchUiState({
-    compact: !!display.tui_compact,
-    detailsMode: resolveDetailsMode(display),
-    statusBar: display.tui_statusbar !== false
+    compact: !!d.tui_compact,
+    detailsMode: resolveDetailsMode(d),
+    statusBar: d.tui_statusbar !== false
   })
 }
 
-export interface UseConfigSyncOptions {
-  rpc: GatewayRpc
-  setBellOnComplete: (v: boolean) => void
-  setVoiceEnabled: (v: boolean) => void
-  sid: null | string
-}
-
 export function useConfigSync({ rpc, setBellOnComplete, setVoiceEnabled, sid }: UseConfigSyncOptions) {
   const mtimeRef = useRef(0)
 
@@ -45,8 +38,7 @@ export function useConfigSync({ rpc, setBellOnComplete, setVoiceEnabled, sid }:
       mtimeRef.current = Number(r?.mtime ?? 0)
     })
     rpc<ConfigFullResponse>('config.get', { key: 'full' }).then(r => applyDisplay(r, setBellOnComplete))
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [rpc, sid])
+  }, [rpc, setBellOnComplete, setVoiceEnabled, sid])
 
   useEffect(() => {
     if (!sid) {
@@ -79,6 +71,12 @@ export function useConfigSync({ rpc, setBellOnComplete, setVoiceEnabled, sid }:
     }, MTIME_POLL_MS)
 
     return () => clearInterval(id)
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [rpc, sid])
+  }, [rpc, setBellOnComplete, sid])
+}
+
+export interface UseConfigSyncOptions {
+  rpc: GatewayRpc
+  setBellOnComplete: (v: boolean) => void
+  setVoiceEnabled: (v: boolean) => void
+  sid: null | string
 }

ui-tui/src/app/useInputHandlers.ts

@@ -29,14 +29,14 @@ export function useInputHandlers(ctx: InputHandlerContext): InputHandlerResult {
     }
   }
 
-  const cancelOverlayFromCtrlC = (live: ReturnType<typeof getUiState>) => {
+  const cancelOverlayFromCtrlC = () => {
     if (overlay.clarify) {
       return actions.answerClarify('')
     }
 
     if (overlay.approval) {
       return gateway
-        .rpc<ApprovalRespondResponse>('approval.respond', { choice: 'deny', session_id: live.sid })
+        .rpc<ApprovalRespondResponse>('approval.respond', { choice: 'deny', session_id: getUiState().sid })
         .then(r => r && (patchOverlayState({ approval: null }), actions.sys('denied')))
     }
 
@@ -172,7 +172,7 @@ export function useInputHandlers(ctx: InputHandlerContext): InputHandlerResult {
       }
 
       if (isCtrl(key, ch, 'c')) {
-        cancelOverlayFromCtrlC(live)
+        cancelOverlayFromCtrlC()
       } else if (key.escape && overlay.picker) {
         patchOverlayState({ picker: false })
       }

ui-tui/src/app/useLongRunToolCharms.ts

@@ -47,10 +47,9 @@ export function useLongRunToolCharms(busy: boolean, tools: ActiveTool[]) {
         }
 
         slots.current.set(tool.id, { count: slot.count + 1, lastAt: now })
-
-        const sec = Math.round((now - tool.startedAt) / 1000)
-
-        turnController.pushActivity(`${pick(LONG_RUN_CHARMS)} (${toolTrailLabel(tool.name)} · ${sec}s)`)
+        turnController.pushActivity(
+          `${pick(LONG_RUN_CHARMS)} (${toolTrailLabel(tool.name)} · ${Math.round((now - tool.startedAt) / 1000)}s)`
+        )
       }
     }
 

ui-tui/src/app/useMainApp.ts

@@ -170,18 +170,16 @@ export function useMainApp(gw: GatewayClient) {
       }
 
       const sel = selection.getState() as null | SelectionSnap
+      const top = s.getViewportTop()
+      const bottom = top + s.getViewportHeight() - 1
 
-      const focusOutside = (top: number, bottom: number) =>
+      if (
         !sel?.anchor ||
         !sel.focus ||
         sel.anchor.row < top ||
         sel.anchor.row > bottom ||
         (!sel.isDragging && (sel.focus.row < top || sel.focus.row > bottom))
-
-      const top = s.getViewportTop()
-      const bottom = top + s.getViewportHeight() - 1
-
-      if (focusOutside(top, bottom)) {
+      ) {
         return s.scrollBy(delta)
       }
 
@@ -197,12 +195,11 @@ export function useMainApp(gw: GatewayClient) {
 
       if (actual > 0) {
         selection.captureScrolledRows(top, top + actual - 1, 'above')
-        shift(-actual, top, bottom)
       } else {
         selection.captureScrolledRows(bottom + actual + 1, bottom, 'below')
-        shift(-actual, top, bottom)
       }
 
+      shift(-actual, top, bottom)
       s.scrollBy(delta)
     },
     [selection]

ui-tui/src/app/useSubmission.ts

@@ -29,19 +29,6 @@ const expandSnips = (snips: PasteSnippet[]) => {
 const spliceMatches = (text: string, matches: RegExpMatchArray[], results: string[]) =>
   matches.reduceRight((acc, m, i) => acc.slice(0, m.index!) + results[i] + acc.slice(m.index! + m[0].length), text)
 
-export interface UseSubmissionOptions {
-  appendMessage: (msg: Msg) => void
-  composerActions: ComposerActions
-  composerRefs: ComposerRefs
-  composerState: ComposerState
-  gw: GatewayClient
-  maybeGoodVibes: (text: string) => void
-  setLastUserMsg: (value: string) => void
-  slashRef: MutableRefObject<(cmd: string) => boolean>
-  submitRef: MutableRefObject<(value: string) => void>
-  sys: (text: string) => void
-}
-
 export function useSubmission(opts: UseSubmissionOptions) {
   const {
     appendMessage,
@@ -183,7 +170,6 @@ export function useSubmission(opts: UseSubmissionOptions) {
         return
       }
 
-      // Slash + shell run regardless of session state (each handles its own sid needs).
       if (looksLikeSlashCommand(full)) {
         appendMessage({ kind: 'slash', role: 'system', text: full })
         composerActions.pushHistory(full)
@@ -201,7 +187,6 @@ export function useSubmission(opts: UseSubmissionOptions) {
 
       const live = getUiState()
 
-      // No session yet — queue the text and let the ready-flush effect send it.
       if (!live.sid) {
         composerActions.pushHistory(full)
         composerActions.enqueue(full)
@@ -246,7 +231,7 @@ export function useSubmission(opts: UseSubmissionOptions) {
 
       send(full)
     },
-    [appendMessage, composerActions, composerRefs, interpolate, send, sendQueued, shellExec, slashRef, sys]
+    [appendMessage, composerActions, composerRefs, interpolate, send, sendQueued, shellExec, slashRef]
   )
 
   const submit = useCallback(
@@ -256,7 +241,6 @@ export function useSubmission(opts: UseSubmissionOptions) {
 
         if (row?.text) {
           const text = row.text.startsWith('/') && composerState.compReplace > 0 ? row.text.slice(1) : row.text
-
           const next = value.slice(0, composerState.compReplace) + text
 
           if (next !== value) {
@@ -304,3 +288,16 @@ export function useSubmission(opts: UseSubmissionOptions) {
 
   return { dispatchSubmission, send, sendQueued, shellExec, submit }
 }
+
+export interface UseSubmissionOptions {
+  appendMessage: (msg: Msg) => void
+  composerActions: ComposerActions
+  composerRefs: ComposerRefs
+  composerState: ComposerState
+  gw: GatewayClient
+  maybeGoodVibes: (text: string) => void
+  setLastUserMsg: (value: string) => void
+  slashRef: MutableRefObject<(cmd: string) => boolean>
+  submitRef: MutableRefObject<(value: string) => void>
+  sys: (text: string) => void
+}