🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(tui): every console view opens in ruflo tui, with a menu, a go prompt, Back and opt-in mouse (ADR-489 phase 5)
re7c29326d408
diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.mdindex dd3c319737..bad3e8dd98 100644--- a/docs/USERGUIDE.md+++ b/docs/USERGUIDE.md@@ -596,6 +596,8 @@ npx ruflo tui --fps 12 # frames per second for moving pictures, 0-3npx ruflo tui --no-anim # draw the pictures still (same as --fps 0)npx ruflo tui --no-pictures # the words of each picture onlynpx ruflo tui --boot # play the look's start-up screen first+npx ruflo tui --mouse # click a page in the bar, scroll with the wheel (every action also has a key)+npx ruflo tui --view federation # open on any console page, not only the first sixnpx ruflo tui --plain | head -40 # print one plain frame and exit 0 (scripts, CI; the plain look, no colour)```@@ -610,6 +612,9 @@ Without a terminal and without `--plain`, `tui` prints a one-line hint and exits| `j` `k` or the arrow keys | Scroll || `r` | Read the files again || `t` | Next look: Classic BBS, Orbital, plain |+| `0` | The main menu: the console's board, with each entry's key (press it to open that page) |+| `:` or `/` | Go to any page by name, id or key: `settings`, `go federation`, `terminal` |+| `Esc` or Backspace | Back to the page you were on || `q` or `Ctrl-C` | Quit |**What each page shows.** It reads Ruflo's own files and the CLI's output in the current project, and says `n/a` for anything it cannot measure.@@ -637,7 +642,7 @@ y sends it · n cancels · it expires in 59 s- **OpenRouter** needs `OPENROUTER_API_KEY` in your environment. The key is named by its variable and never shown. Requests go only to `https://openrouter.ai` and to the HTTPS hosts you name with `--convo-targets` (or `RUFLO_TUI_CONVO_TARGETS`, syntax `endpoint:<name>=<https-base-url>|<KEY_ENV>|<model>;...`), with no redirects. `--model` picks the model (default `openrouter/auto`), and `--max-spend-usd` stops sending once the provider-reported spend reaches the cap (default `0.5`).- `--no-ai` turns the AI page off.-**Limits.** Read-only except the AI page. Tested on Linux in tmux with Node 22; Windows, macOS and Node 20 are untested. The animation was measured on Linux: at 8 frames per second it used about 2–3% of one core and 14–80 KB/s of terminal output depending on the look and window size (Orbital on a 200 by 50 window is the heaviest), and 30 frames per second about 9% and 230 KB/s. The pages beyond these six, the main menu with its grouped navigation, and clicking are the next stage of ADR-489. Design and decisions: [ADR-489](../v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md).+**Limits.** Read-only except the AI page. Tested on Linux in tmux with Node 22; Windows, macOS and Node 20 are untested. The animation was measured on Linux: at 8 frames per second it used about 2–3% of one core and 14–80 KB/s of terminal output depending on the look and window size (Orbital on a 200 by 50 window is the heaviest), and 30 frames per second about 9% and 230 KB/s. **Every console page opens here** (33 of them, from the main menu `0` or the go prompt `:`), each with the console's own body. What changes is recorded per page in ADR-489: most are read-only here because their action buttons wait for the confirm gate (the next stage); the Room needs a Claude Code session and says so on one screen; the console's terminal is this shell's AI page. On the menu the console's keys work (`b` Hive-Mind, `9` Memory Lab, …; `q` still quits and `p` is the go prompt), so a letter there is not the page-bar letter. Design and decisions: [ADR-489](../v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md).**In Claude Code**, the same console has an optional Orbital look and a Theme Studio: run `/ruflo themes`. See the [console README](../plugins/ruflo-console/README.md#orbital-theme).diff --git a/plugins/ruflo-console/tests/tui-nav.spec.ts b/plugins/ruflo-console/tests/tui-nav.spec.tsindex 98fded2d3e..391a0af735 100644--- a/plugins/ruflo-console/tests/tui-nav.spec.ts+++ b/plugins/ruflo-console/tests/tui-nav.spec.ts@@ -70,7 +70,7 @@ describe('keys', () => {expect([keyOf('o'), keyOf('c'), keyOf('s'), keyOf('e'), keyOf('m'), keyOf('a')]).toEqual([{ page: 'overview' }, { page: 'cost' }, { page: 'swarm' }, { page: 'events' }, { page: 'missions' }, { page: 'ai' }])expect([keyOf('\t'), keyOf(`${ESC}[C`), keyOf('l')]).toEqual(['next', 'next', 'next'])expect([keyOf(`${ESC}[Z`), keyOf(`${ESC}[D`), keyOf('h')]).toEqual(['prev', 'prev', 'prev'])- expect([keyOf('0'), keyOf('7'), keyOf('9'), keyOf('x'), keyOf(`${ESC}]0;t\u0007`)]).toEqual([null, null, null, null, null])+ expect([keyOf('7'), keyOf('8'), keyOf('9'), keyOf('x'), keyOf(`${ESC}]0;t\u0007`)]).toEqual([null, null, null, null, null])})it('has no key for Room: its content is a message box and Claude sessions this host does not have', () => {diff --git a/plugins/ruflo-console/tests/tui-parity.spec.ts b/plugins/ruflo-console/tests/tui-parity.spec.tsnew file mode 100644index 0000000000..c7aaf98ca6--- /dev/null+++ b/plugins/ruflo-console/tests/tui-parity.spec.ts@@ -0,0 +1,220 @@+/**+ * Every console view has a recorded decision for the standalone terminal (ADR-489 phase 5), the shell opens each one, and the go prompt, the+ * main-menu keys, Back and the mouse reach them. Run with+ * npx vitest run plugins/ruflo-console/tests/tui-parity.spec.ts+ */+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'+import { tmpdir } from 'node:os'+import { dirname, join } from 'node:path'+import { afterAll, beforeAll, describe, expect, it } from 'vitest'++import { VIEWS } from '../hooks/state'+import { navHit, navLine, runTui, type TuiIO } from '../tui/run'+import { PAGE_IDS, PARITY } from '../tui/parity'+import { openSession } from '../tui/session'+import { RUFLO_FILES } from './fixtures/ruflo-run'++const ESC = '\u001b'+const ADR = join(__dirname, '../../../v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md')+let root: string+let project: string++beforeAll(() => {+ root = mkdtempSync(join(tmpdir(), 'tui-parity-'))+ project = join(root, 'project')+ for (const [path, body] of Object.entries(RUFLO_FILES)) {+ mkdirSync(dirname(join(project, path)), { recursive: true })+ writeFileSync(join(project, path), body)+ }+})+afterAll(() => rmSync(root, { recursive: true, force: true }))++const settle = (ms = 150) => new Promise(resolve => setTimeout(resolve, ms))+const strip = (text: string) => text.replace(/\u001b\[[0-9;?<]*[A-Za-z]/g, '')++describe('a decision for every console view', () => {+ it('has a row in PARITY for each view in VIEWS, and for nothing else', () => {+ const ids = [...VIEWS.map(view => view.id), 'agent'].sort()++ expect(Object.keys(PARITY).sort()).toEqual(ids)+ expect(PAGE_IDS).toEqual([...VIEWS.map(view => view.id), 'ai'])+ for (const [id, entry] of Object.entries(PARITY)) {+ expect(['same', 'partial', 'equivalent', 'claude-only'], id).toContain(entry.status)+ expect(entry.why.length, id).toBeGreaterThan(8)+ }+ })++ it('is written out in ADR-489, row for row, so the guide and the code cannot disagree', () => {+ const adr = readFileSync(ADR, 'utf8')++ for (const view of [...VIEWS, { id: 'agent', label: 'Agent drill-down' }]) {+ const entry = PARITY[view.id as keyof typeof PARITY]++ expect(adr, view.id).toContain(`| \`${view.id}\` | ${view.label} | ${entry.status} | ${entry.why} |`)+ }+ })++ it('opens every view without throwing, in words only, with nothing but colour in the bytes', async () => {+ const session = openSession({ cwd: project, home: join(root, 'home'), look: 'plain', fps: 0 })++ await session.refresh()+ for (const view of VIEWS) {+ session.show(view.id)++ const lines = session.frame(100, 'none', 40)++ expect(lines.length, view.id).toBeGreaterThan(0)+ expect(lines.join('\n'), view.id).not.toMatch(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/)+ }+ session.stop()+ })++ it('sends the console terminal to the AI page and says plainly that the Room needs Claude Code', async () => {+ const session = openSession({ cwd: project, home: join(root, 'home'), look: 'plain', fps: 0, aiPage: {} })++ session.show('terminal')+ expect(session.page).toBe('ai')+ session.show('room')+ expect(session.page).toBe('room')++ const note = session.frame(100, 'none', 30).join('\n')++ expect(note).toContain('Room: Claude Code only')+ expect(note).toContain(PARITY.room.why)+ session.stop()+ })++ it('draws the main menu entries as words next to their keys (they were blank)', async () => {+ const session = openSession({ cwd: project, home: join(root, 'home'), look: 'plain', fps: 0 })++ await session.refresh()+ session.show('menu')++ const text = session.frame(100, 'none', 60).join('\n')++ for (const word of ['Missions', 'Overview', 'Hive-Mind', 'Memory Lab', 'Settings']) expect(text, word).toContain(word)+ session.stop()+ })+})++function terminal(columns = 110, rows = 36) {+ const out: string[] = []+ const listeners: Array<(chunk: string) => void> = []+ const io: TuiIO = {+ stdin: { isTTY: true, setRawMode: () => undefined, on: (_e, fn) => void listeners.push(fn as never), off: () => void listeners.splice(0), resume: () => undefined, pause: () => undefined },+ stdout: { isTTY: true, columns, rows, write: (text: string) => void out.push(text), on: () => undefined, off: () => undefined },+ stderr: { write: () => undefined },+ env: { TERM: 'xterm-256color' },+ }++ return { io, out, press: (key: string) => listeners.forEach(fn => fn(key)), screen: () => strip(out.join('').split(`${ESC}[H`).pop() ?? '') }+}++const options = { look: 'plain' as const, fps: 0 }++describe('getting to every view from the keys', () => {+ it('0 opens the menu, a menu key opens that view, and Esc comes back to where you were', async () => {+ const t = terminal()+ const running = runTui({ cwd: project, home: join(root, 'home'), ...options }, t.io)++ await settle()+ t.press('0')+ await settle()+ expect(t.screen()).toContain('Main Menu')+ expect(navLine('menu', 110, 'none')).toContain('[Main Menu]')+ t.press('b') // Hive-Mind on the board (b is Page Up everywhere else)+ await settle()+ expect(t.screen()).toMatch(/Hive-Mind/)+ t.press(ESC)+ await settle()+ expect(t.screen()).toContain('Main Menu')+ t.press(ESC)+ await settle()+ expect(t.screen()).toMatch(/Overview/)+ t.press('q')+ await running+ })++ it('has a go prompt that takes a name, an id or a prefix, and says so when there is no such page', async () => {+ const t = terminal()+ const running = runTui({ cwd: project, home: join(root, 'home'), ...options }, t.io)++ await settle()+ t.press(':')+ for (const ch of 'go federation') t.press(ch)+ expect(t.screen()).toContain('go> go federation')+ t.press('\r')+ await settle()+ expect(t.screen()).toContain('Federation')+ t.press('/')+ for (const ch of 'nonsense') t.press(ch)+ t.press('\r')+ await settle()+ expect(t.screen()).toContain('no page called "nonsense"')+ t.press(':')+ for (const ch of 'term') t.press(ch)+ t.press('\r')+ await settle()+ expect(t.screen()).toMatch(/AI/)+ t.press('q')+ await running+ })++ it('lets a pasted escape sequence into the prompt as nothing (the prompt keeps text, not bytes)', async () => {+ const t = terminal()+ const running = runTui({ cwd: project, home: join(root, 'home'), ...options }, t.io)++ await settle()+ t.press(':')+ t.press(`${ESC}]0;evil\u0007`)+ expect(t.screen()).toContain('go> ▌')+ t.press(ESC)+ t.press('q')+ await running+ })++ it('--view takes any page', async () => {+ const t = terminal()+ const running = runTui({ cwd: project, home: join(root, 'home'), view: 'federation', ...options }, t.io)++ await settle()+ expect(t.screen()).toContain('Federation')+ t.press('q')+ await running+ })+})++describe('the mouse', () => {+ it('is off unless asked for: no reporting is switched on, and report bytes are not read as keys', async () => {+ const t = terminal()+ const running = runTui({ cwd: project, home: join(root, 'home'), ...options }, t.io)++ await settle()+ expect(t.out.join('')).not.toContain('?1000h')+ t.press(`${ESC}[<0;14;1M`)+ await settle()+ expect(t.screen()).toMatch(/Overview/)+ t.press('q')+ await running+ })++ it('with --mouse: a click on a page chip opens it, the wheel scrolls, and reporting is switched off on q', async () => {+ const t = terminal(110, 12)+ const running = runTui({ cwd: project, home: join(root, 'home'), mouse: true, ...options }, t.io)++ await settle()+ expect(t.out.join('')).toContain(`${ESC}[?1000h${ESC}[?1006h`)+ expect(navHit(1, 110)).toBe('overview')+ expect(navHit(14, 110)).toBe('cost')+ t.press(`${ESC}[<0;14;1M`)+ await settle()+ expect(t.screen()).toMatch(/Cost/)+ t.press(`${ESC}[<65;5;5M`)+ await settle()+ expect(t.screen()).toMatch(/\d+-\d+\/\d+/)+ t.press(`${ESC}[<0;14;1m`) // a release is not a click+ t.press('q')+ await running+ expect(t.out.join('').endsWith(`${ESC}[?1006l${ESC}[?1000l${ESC}[?1004l${ESC}[?25h${ESC}[?1049l`)).toBe(true)+ })+})diff --git a/plugins/ruflo-console/tui/ansi.ts b/plugins/ruflo-console/tui/ansi.tsindex f2c0c6181e..e7ca886ffd 100644--- a/plugins/ruflo-console/tui/ansi.ts+++ b/plugins/ruflo-console/tui/ansi.ts@@ -298,6 +298,9 @@ export function render(node: unknown, width: number, depth: Depth): string[] {if (label.includes('✦')) return []+ // A main-menu entry is a label next to its key chip, and the key is what opens it here (the shell reads it): the words stay, as text.+ if (typeof props.key === 'string' && props.key.startsWith('menu-go-')) return [cut(` ${label} `, width)]+if (typeof props.key === 'string' && props.key.startsWith('sec-')) return [cut(`${sgr({ bold: true }, depth)}${label.replace(/^[▾▸]\s*/, '')}${depth === 'none' ? '' : RESET}`, width)]return /^[●○]/.test(label) ? [cut(`${sgr({ dimColor: true }, depth)}${label} ${depth === 'none' ? '' : RESET}`, width)] : []@@ -305,6 +308,9 @@ export function render(node: unknown, width: number, depth: Depth): string[] {if (type !== 'Box') return []+ // A box that asks for a width (the main menu's two groups side by side) is no wider than that, as on the console.+ if (typeof props.width === 'number' && Number.isFinite(props.width) && props.width >= 3) width = Math.min(width, Math.floor(props.width))+const frame = props.borderStyle === 'round' || props.borderStyle === 'single' ? BORDER[props.borderStyle] : nullconst padX = typeof props.paddingX === 'number' && props.paddingX > 0 ? Math.min(4, Math.floor(props.paddingX)) : 0const inner = Math.max(1, width - (frame === null ? 0 : 2) - padX * 2)diff --git a/plugins/ruflo-console/tui/main.ts b/plugins/ruflo-console/tui/main.tsindex df4c29f922..cda815cb96 100644--- a/plugins/ruflo-console/tui/main.ts+++ b/plugins/ruflo-console/tui/main.ts@@ -1,4 +1,4 @@/** The bundle entry (ADR-489): what `ruflo tui` loads. Built to dist/tui.mjs by scripts/build-tui.mjs. */-export { runTui, isTuiView, keyOf, depthOf } from './run'+export { runTui, isTuiView, isPage, keyOf, depthOf } from './run'export type { TuiIO, TuiOptions } from './run'export { TUI_VIEWS } from './session'diff --git a/plugins/ruflo-console/tui/parity.ts b/plugins/ruflo-console/tui/parity.tsnew file mode 100644index 0000000000..f5ffcb488f--- /dev/null+++ b/plugins/ruflo-console/tui/parity.ts@@ -0,0 +1,54 @@+/**+ * Every console view and what `ruflo tui` does with it (ADR-489 phase 5). A view is a decision, not an accident: `parity.spec.ts` fails when a view+ * is added to the console's `VIEWS` without an entry here, and when ADR-489's table does not name each view.+ *+ * - `same` the console's own page body, read-only, as in Claude Code.+ * - `partial` the console's own page body, but part of it needs Claude Code (or the confirm gate of phase 6): `why` says which.+ * - `equivalent` the job is done by another standalone page (`opens`).+ * - `claude-only` the page is about a Claude Code session this terminal does not have: it opens a one-screen note, never an empty fake.+ */+import { VIEWS, type ViewId } from '../hooks/state'++export type Parity = { status: 'same' | 'partial' | 'equivalent' | 'claude-only'; why: string; opens?: 'ai' }++const READ_ONLY = 'read-only here: its action buttons are not drawn until the confirm gate of phase 6'++export const PARITY: Record<ViewId | 'agent', Parity> = {+ menu: { status: 'same', why: 'entries open by their key, as on the console board' },+ missions: { status: 'partial', why: 'the mission record only: entering a goal, planning and research start a Claude turn' },+ overview: { status: 'same', why: 'the Claude-only controls are not drawn' },+ swarm: { status: 'same', why: 'topology, agents and votes as ruflo wrote them' },+ hive: { status: 'partial', why: READ_ONLY },+ claims: { status: 'partial', why: READ_ONLY },+ workflows: { status: 'partial', why: 'the ruflo swarm side; Claude Code workflow runs are not visible outside a session' },+ federation: { status: 'partial', why: READ_ONLY },+ plugins: { status: 'partial', why: 'what is installed and loaded; "loaded as a mod" is a Claude Code fact and reads n/a' },+ learning: { status: 'same', why: 'router picks, outcomes and the pipeline as on disk' },+ metaharness: { status: 'partial', why: READ_ONLY },+ memory: { status: 'partial', why: READ_ONLY },+ cost: { status: 'partial', why: 'provider ledger and router counts; Claude Code spend, context and the budget ladder read n/a' },+ timeline: { status: 'partial', why: 'agent lanes from status reports; Claude Code tool-call lanes need a session' },+ approvals: { status: 'partial', why: 'shows what waits; answering is a write and waits for the confirm gate of phase 6' },+ events: { status: 'same', why: 'the event stream as it is on disk; Ask Claude is not drawn' },+ room: { status: 'claude-only', why: 'it is what people said to Claude in a session, plus a message box; this terminal has neither' },+ xruv: { status: 'partial', why: READ_ONLY },+ terminal: { status: 'equivalent', why: 'the standalone AI page (Codex or OpenRouter, each question after a card)', opens: 'ai' },+ skills: { status: 'partial', why: READ_ONLY },+ secure: { status: 'partial', why: READ_ONLY },+ perf: { status: 'partial', why: READ_ONLY },+ automate: { status: 'partial', why: READ_ONLY },+ neural: { status: 'partial', why: READ_ONLY },+ vector: { status: 'partial', why: READ_ONLY },+ evolve: { status: 'partial', why: READ_ONLY },+ devtools: { status: 'partial', why: READ_ONLY },+ sandbox: { status: 'partial', why: READ_ONLY },+ market: { status: 'partial', why: READ_ONLY },+ adrs: { status: 'partial', why: READ_ONLY },+ whatsnew: { status: 'same', why: 'changelogs of the installed plugins' },+ themes: { status: 'partial', why: 'the look is chosen with t or --look; the colour picker and generated themes are not here yet' },+ settings: { status: 'partial', why: 'shown read-only; changing a setting waits for the confirm gate of phase 6' },+ agent: { status: 'partial', why: 'the drill-down from a Swarm selection; selecting needs the host keys, so it says so' },+}++/** The views the standalone shell can open by name: every console view and the AI page. */+export const PAGE_IDS: readonly (ViewId | 'ai')[] = [...VIEWS.map(view => view.id), 'ai']diff --git a/plugins/ruflo-console/tui/run.ts b/plugins/ruflo-console/tui/run.tsindex 1475d27d00..6ceda27b9f 100644--- a/plugins/ruflo-console/tui/run.ts+++ b/plugins/ruflo-console/tui/run.ts@@ -5,7 +5,9 @@*/import type { Depth } from './ansi'import { cells, clean, widthOf } from './ansi'-import { openSession, TUI_VIEWS, type Look, type Session, type SessionOptions, type TuiView } from './session'+import { VIEWS, viewOf } from '../hooks/state'+import { PAGE_IDS } from './parity'+import { openSession, TUI_VIEWS, type Look, type Page, type Session, type SessionOptions, type TuiView } from './session'export type TuiInput = {isTTY?: boolean@@ -24,9 +26,11 @@ export type TuiOutput = {off?: (event: 'resize', fn: () => void) => unknown}export type TuiIO = { stdin: TuiInput; stdout: TuiOutput; stderr: { write: (text: string) => unknown }; env: Record<string, string | undefined>; signal?: AbortSignal }-export type TuiOptions = { cwd: string; view?: TuiView; plain?: boolean; cliEntry?: string; configDir?: string; home?: string; pluginRoot?: string; refreshMs?: number; /** The look (bbs | orbital | plain: default bbs) and the frames per second of moving pictures (default 8, at most 30; 0 draws them still). */ look?: Look; fps?: number; /** False: no animation (a still frame, like fps 0). */ anim?: boolean; /** False: no pictures, only their words. */ pictures?: boolean; /** True: play the start-up screen first (as the console's boot setting). */ boot?: boolean; /** The AI page's settings; absent: the page is off. */ aiPage?: SessionOptions['aiPage'] }+export type TuiOptions = { cwd: string; view?: Page; /** True: read SGR mouse reports (a click on the page bar, the wheel to scroll). Off by default; every mouse action has a key. */ mouse?: boolean; plain?: boolean; cliEntry?: string; configDir?: string; home?: string; pluginRoot?: string; refreshMs?: number; /** The look (bbs | orbital | plain: default bbs) and the frames per second of moving pictures (default 8, at most 30; 0 draws them still). */ look?: Look; fps?: number; /** False: no animation (a still frame, like fps 0). */ anim?: boolean; /** False: no pictures, only their words. */ pictures?: boolean; /** True: play the start-up screen first (as the console's boot setting). */ boot?: boolean; /** The AI page's settings; absent: the page is off. */ aiPage?: SessionOptions['aiPage'] }export const isTuiView = (value: unknown): value is TuiView => typeof value === 'string' && (TUI_VIEWS as readonly string[]).includes(value)+/** Any page the shell can open, which is every console view and the AI page (`--view`, the go prompt). */+export const isPage = (value: unknown): value is Page => typeof value === 'string' && (PAGE_IDS as readonly string[]).includes(value)/** Colour depth from the environment: NO_COLOR and a dumb terminal get none, COLORTERM truecolor/24bit gets 24-bit, the rest 256. */export function depthOf(env: Record<string, string | undefined>): Depth {@@ -48,20 +52,46 @@ const LABELS: Record<TuiView, string> = { overview: 'Overview', cost: 'Cost', swconst LETTER: Partial<Record<string, TuiView>> = { o: 'overview', c: 'cost', s: 'swarm', e: 'events', m: 'missions', a: 'ai' }/** The page bar: every page with its number (the current one in reverse), or `‹ 3/6 Swarm ›` when the terminal is too narrow for all of them. Page names are ours, never from a file. */-export function navLine(view: TuiView, columns: number, depth: Depth): string {+export function navLine(view: Page, columns: number, depth: Depth): string {const wide = TUI_VIEWS.map((page, i) => {const text = ` ${i + 1} ${LABELS[page]} `return page === view && depth !== 'none' ? `${ESC}[7m${text}${ESC}[0m` : page === view ? `[${text.trim()}]` : text}).join(' ')+ const other = (TUI_VIEWS as readonly string[]).includes(view) ? null : (VIEWS.find(entry => entry.id === view)?.label ?? view)- return widthOf(wide) <= columns ? wide : `‹ ${TUI_VIEWS.indexOf(view) + 1}/${TUI_VIEWS.length} ${LABELS[view]} ›`+ // A page that is not one of the six shows after them, as the one chip that is on.+ if (other !== null) {+ const chip = depth !== 'none' ? `${ESC}[7m ${other} ${ESC}[0m` : `[${other}]`+ const all = `${wide} ${chip}`++ return widthOf(all) <= columns ? all : `‹ ${clean(other)} › (Esc back)`.slice(0, columns)+ }++ return widthOf(wide) <= columns ? wide : `‹ ${TUI_VIEWS.indexOf(view as TuiView) + 1}/${TUI_VIEWS.length} ${LABELS[view as TuiView]} ›`+}++/** Which of the six page chips a click at column `x` (1-based) lands on, or null: the same positions `navLine` draws when it fits. */+export function navHit(x: number, columns: number): TuiView | null {+ const chips = TUI_VIEWS.map((page, k) => ` ${k + 1} ${LABELS[page]} `)++ if (chips.join(' ').length > columns) return null++ let at = 1++ for (const [k, chip] of chips.entries()) {+ if (x >= at && x < at + chip.length) return TUI_VIEWS[k] as TuiView+ at += chip.length + 1+ }++ return null}/** The key line under the page: every key when there is room, fewer keys as the terminal narrows, always inside `columns` (the scroll position, when there is one, is counted in). `own` replaces the page keys (the AI page has its own). */export function keyLine(columns: number, place = '', own?: readonly string[]): string {const pages = `1-${TUI_VIEWS.length}`- const tiers = own ?? [`${pages} or o c s e m a page · tab next · r refresh · t look · j/k scroll · q quit · read-only`, `${pages} page · tab next · r refresh · j/k scroll · q quit`, `${pages} page · j/k scroll · q quit`, `${pages} page · q quit`]+ const menu = '0 menu · : go to any page · Esc back'+ const tiers = own ?? [`${pages} or o c s e m a page · ${menu} · tab next · r refresh · t look · j/k scroll · q quit · read-only`, `${pages} or o c s e m a page · 0 menu · : go · tab next · r refresh · j/k scroll · q quit · read-only`, `${pages} page · 0 menu · : go · Esc back · tab next · r refresh · j/k scroll · q quit`, `${pages} page · tab next · r refresh · j/k scroll · q quit`, `${pages} page · j/k scroll · q quit`, `${pages} page · q quit`]const fits = tiers.find(line => cells(line + place) <= columns) ?? tiers[tiers.length - 1] as stringreturn `${fits}${place}`.slice(0, columns)@@ -76,7 +106,7 @@ export function aiKeyTiers(mode: 'type' | 'nav', hasCard: boolean): string[] {}/** One keypress as an action, from the bytes a terminal sends. Anything else is ignored. */-export type Key = 'quit' | 'look' | { page: TuiView } | 'next' | 'prev' | 'refresh' | 'down' | 'up' | 'pagedown' | 'pageup' | 'top' | 'bottom' | null+export type Key = 'quit' | 'look' | 'menu' | 'prompt' | 'back' | { page: TuiView } | 'next' | 'prev' | 'refresh' | 'down' | 'up' | 'pagedown' | 'pageup' | 'top' | 'bottom' | nullexport function keyOf(chunk: string): Key {switch (chunk) {@@ -92,6 +122,15 @@ export function keyOf(chunk: string): Key {case 'h':case `${ESC}[D`:return 'prev'+ case '0':+ return 'menu'+ case ':':+ case '/':+ return 'prompt'+ case `${ESC}`:+ case '\u007f':+ case '\b':+ return 'back'case 'r':return 'refresh'case 't':@@ -150,7 +189,7 @@ function writeTick(io: TuiIO, screen: string[], memory: Memory, columns: number,if (out !== '') io.stdout.write(out)}-function paint(session: Session, io: TuiIO, depth: Depth, scroll: number, memory: Memory, clear = false, tick = false): number {+function paint(session: Session, io: TuiIO, depth: Depth, scroll: number, memory: Memory, clear = false, tick = false, line = ''): number {const ai = session.page === 'ai' ? session.ai : nullconst raw = io.stdout.columns ?? 100const rows = Math.max(5, io.stdout.rows ?? 30)@@ -177,7 +216,7 @@ function paint(session: Session, io: TuiIO, depth: Depth, scroll: number, memory// The AI page fits its own conversation to the room and follows the tail; the others scroll.const top = session.page === 'ai' ? 0 : Math.max(0, Math.min(scroll, Math.max(0, lines.length - room)))const place = lines.length > room ? ` · ${top + 1}-${Math.min(lines.length, top + room)}/${lines.length}` : ''- const footer = `${depth === 'none' ? '' : `${ESC}[2m`}${clean(keyLine(columns, place, session.page === 'ai' && session.ai !== null ? aiKeyTiers(session.ai.mode, session.ai.card !== null) : undefined))}${depth === 'none' ? '' : `${ESC}[0m`}`+ const footer = `${depth === 'none' ? '' : `${ESC}[2m`}${line !== '' ? clean(line).slice(0, columns) : clean(keyLine(columns, place, session.page === 'ai' && session.ai !== null ? aiKeyTiers(session.ai.mode, session.ai.card !== null) : undefined))}${depth === 'none' ? '' : `${ESC}[0m`}`const body = [...lines.slice(top, top + room), ...Array.from({ length: Math.max(0, room - (lines.length - top)) }, () => '')]@@ -193,7 +232,7 @@ function paint(session: Session, io: TuiIO, depth: Depth, scroll: number, memory}/** `--plain`: one frame as plain text on stdout (the same views, read-only, no escapes) and exit 0. Nothing on stderr, so a script's output is only the frame. */-async function once(session: Session, io: TuiIO, view: TuiView): Promise<number> {+async function once(session: Session, io: TuiIO, view: Page): Promise<number> {session.show(view)await session.refresh()const columns = Math.max(MIN_COLUMNS, Math.min(200, io.stdout.columns ?? 100))@@ -216,7 +255,7 @@ export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {}const session = openSession({ cwd: options.cwd, ...((options.look ?? (options.plain === true ? 'plain' : undefined)) !== undefined && { look: options.look ?? 'plain' }), fps: options.anim === false ? 0 : fpsOf(options.fps), ...(options.pictures === false && { pictures: false }), ...(options.boot === true && { boot: true }), ...(options.cliEntry !== undefined && { cliEntry: options.cliEntry }), ...(options.configDir !== undefined && { configDir: options.configDir }), ...(options.home !== undefined && { home: options.home }), ...(options.pluginRoot !== undefined && { pluginRoot: options.pluginRoot }), ...(options.aiPage !== undefined && { aiPage: options.aiPage }) })- let view: TuiView = options.view ?? 'overview'+ let view: Page = options.view ?? 'overview'try {if (options.plain === true || !interactive || io.stdin.setRawMode === undefined) return await once(session, io, view)@@ -228,28 +267,107 @@ export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {let finish: () => void = () => undefinedconst done = new Promise<void>(resolve => void (finish = resolve))const memory: Memory = { lines: [], columns: 0, rows: 0 }- const draw = (tick = false) => void (scroll = paint(session, io, depth, scroll, memory, false, tick))+ // The go prompt (":" or "/"): a page by its name, id or key, read from the keys, shown in the key line. `notice` is one line of news until the next key.+ let prompt: string | null = null+ let notice = ''+ const history: Page[] = []+ const line = () => (prompt !== null ? `go> ${prompt}▌ (a page name · Enter opens · Esc cancels)` : notice)+ const draw = (tick = false) => void (scroll = paint(session, io, depth, scroll, memory, false, tick, line()))const reread = async () => {await session.refresh()if (!isDone) draw()}session.onChange(() => void (isDone || draw()))+ const open = (next: Page) => {+ if (next !== view) history.push(view), history.length > 30 && history.shift()++ view = next+ scroll = 0+ session.show(view)+ view = session.page+ if (session.page === 'ai') session.ai?.enter()+ else if (!(TUI_VIEWS as readonly string[]).includes(view)) void reread()+ }+ const goTo = (word: string) => {+ const name = word.trim().replace(/^(go|open)\s+/i, '')+ const found = name.toLowerCase() === 'ai' ? 'ai' : viewOf(name)++ if (found === null || found === 'agent') notice = `no page called "${clean(name).slice(0, 30)}": try 0 for the menu`+ else open(found)+ }+ const onMouse = (chunk: string): boolean => {+ const hit = /^\u001b\[<(\d+);(\d+);(\d+)([Mm])$/.exec(chunk)++ if (hit === null) return false++ const [button, x, y] = [Number(hit[1]), Number(hit[2]), Number(hit[3])]++ if (hit[4] !== 'M') return true+ if (button === 64) scroll = Math.max(0, scroll - 3)+ else if (button === 65) scroll += 3+ else if (button === 0 && y === 1) {+ const page = navHit(x, Math.min(200, io.stdout.columns ?? 100))++ if (page !== null) open(page)+ }++ draw()++ return true+ }+const onKey = (chunk: Buffer | string) => {// The AI page takes the keys while you type (digits and letters are text there): Esc hands them back to the shell, and Ctrl-C always quits.- if (view === 'ai' && session.ai !== null && session.ai.press(chunk.toString()).consumed) return draw()+ if (session.page === 'ai' && session.ai !== null && session.ai.press(chunk.toString()).consumed) return draw()// Focus reports (the terminal tells us when it is behind another window): a hidden terminal draws nothing, and a refocused one draws at once.if (chunk.toString() === `${ESC}[O`) return void (isFocused = false)if (chunk.toString() === `${ESC}[I`) return void ((isFocused = true), draw())- const key = keyOf(chunk.toString())+ if (options.mouse === true && onMouse(chunk.toString())) return++ const text = chunk.toString()++ notice = ''++ if (prompt !== null) {+ if (text === '\r' || text === '\n') {+ const word = prompt++ prompt = null+ goTo(word)+ } else if (text === ESC || text === '\u0003') prompt = null+ else if (text === '\u007f' || text === '\b') prompt = prompt.slice(0, -1)+ else if (text.length === 1 && text >= ' ' && text !== '\u007f' && prompt.length < 40) prompt += text+ else if (text.length > 1 && !text.includes(ESC) && prompt.length + text.length <= 40) prompt += clean(text).replace(/[\r\n]/g, '')++ return draw()+ }++ // The main menu's keys are the console's own: an entry opens by its key chip (q still quits, and p is the palette, here the go prompt).+ if (view === 'menu' && text.length === 1 && text !== 'q') {+ const entry = VIEWS.find(candidate => candidate.key !== '' && candidate.key === text)++ if (entry !== undefined) return void (open(entry.id), draw())+ if (text === 'p') return void ((prompt = ''), draw())+ }++ const key = keyOf(text)const page = Math.max(1, (io.stdout.rows ?? 30) - 2)if (key === 'quit') return finish()- if (typeof key === 'object' && key !== null) (view = key.page), (scroll = 0), session.show(view), view === 'ai' && session.ai?.enter()- else if (key === 'next') (view = TUI_VIEWS[(TUI_VIEWS.indexOf(view) + 1) % TUI_VIEWS.length] as TuiView), (scroll = 0), session.show(view)- else if (key === 'prev') (view = TUI_VIEWS[(TUI_VIEWS.indexOf(view) + TUI_VIEWS.length - 1) % TUI_VIEWS.length] as TuiView), (scroll = 0), session.show(view)+ if (typeof key === 'object' && key !== null) open(key.page)+ else if (key === 'menu') open('menu')+ else if (key === 'prompt') prompt = ''+ else if (key === 'back') {+ const previous = history.pop()++ if (previous === undefined) notice = 'nothing to go back to'+ else (view = previous), (scroll = 0), session.show(view), (view = session.page)+ }+ else if (key === 'next') open(TUI_VIEWS[(TUI_VIEWS.indexOf(view as TuiView) + 1) % TUI_VIEWS.length] as TuiView)+ else if (key === 'prev') open(TUI_VIEWS[(TUI_VIEWS.indexOf(view as TuiView) + TUI_VIEWS.length - 1) % TUI_VIEWS.length] as TuiView)else if (key === 'down') scroll += 1else if (key === 'up') scroll = Math.max(0, scroll - 1)else if (key === 'pagedown') scroll += page@@ -264,7 +382,7 @@ export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {}session.show(view)- io.stdout.write(`${ESC}[?1049h${ESC}[?25l${ESC}[?1004h`)+ io.stdout.write(`${ESC}[?1049h${ESC}[?25l${ESC}[?1004h${options.mouse === true ? `${ESC}[?1000h${ESC}[?1006h` : ''}`)io.stdin.setRawMode(true)io.stdin.resume()io.stdin.on('data', onKey)@@ -301,7 +419,7 @@ export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {io.stdout.off?.('resize', resize)io.stdin.setRawMode(false)io.stdin.pause()- io.stdout.write(`${ESC}[?1004l${ESC}[?25h${ESC}[?1049l`)+ io.stdout.write(`${options.mouse === true ? `${ESC}[?1006l${ESC}[?1000l` : ''}${ESC}[?1004l${ESC}[?25h${ESC}[?1049l`)}return 0diff --git a/plugins/ruflo-console/tui/session.ts b/plugins/ruflo-console/tui/session.tsindex 8662ce9665..72a356651d 100644--- a/plugins/ruflo-console/tui/session.ts+++ b/plugins/ruflo-console/tui/session.ts@@ -8,6 +8,8 @@ import type { Host } from '../hooks/host'import { newState, type State } from '../hooks/state'import { picturesOf } from '../hooks/views/frames'import { BODIES, NARROW } from '../hooks/views/pane'+import { VIEWS, type ViewId } from '../hooks/state'+import { PARITY } from './parity'import { standalonePane } from '../hooks/views/standalone-pane'import { render, terminalKit, type Depth } from './ansi'import { aiConfigOf, openAi, type Ai, type AiOptions as AiPageOptions } from './ai'@@ -23,6 +25,8 @@ export const TUI_VIEWS = ['overview', 'cost', 'swarm', 'events', 'missions', 'aiexport type TuiView = (typeof TUI_VIEWS)[number]/** The pages that are the console's own views. `ai` is the terminal's own page (ADR-489 phase 3): ask Codex or OpenRouter. */export type ConsoleView = Exclude<TuiView, 'ai'>+/** Any page the shell can show: every console view (ADR-489 phase 5, `parity.ts` says what each does here) and the AI page. */+export type Page = ViewId | 'ai'/** What the AI page may do. Absent: the page says it is off and the host refuses every spawn, send and key read (phase 2). */export type Look = 'bbs' | 'orbital' | 'plain'@@ -57,10 +61,10 @@ export type Session = {/** True when this frame has anything that moves (a picture drawn at fps above 0): the shell redraws on its clock only then. */moving: () => boolean/** The page now showing. */- page: TuiView+ page: Page/** Reads the disk again and runs the page's read-only probes, then returns. Never throws. */refresh: () => Promise<void>- show: (view: TuiView) => void+ show: (view: Page) => void/** The page as terminal lines, `columns` wide. `rows` is how many the terminal has for it (the AI page fits its conversation to them). */frame: (columns: number, depth: Depth, rows?: number) => string[]/** Something changed that the screen should show (streamed output): the shell redraws. */@@ -101,7 +105,7 @@ export function openSession(options: SessionOptions, host?: Host): Session {const controller = createController(state, node)const ai = page === undefined ? null : openAi(state, node, page)const aiStatus: AiStatus = { codex: ai === null ? 'off' : 'checking…', openrouter: ai === null ? 'off' : 'checking…' }- let current: TuiView = 'overview'+ let current: Page = 'overview'let cardFits = falselet isMoving = false@@ -148,11 +152,12 @@ export function openSession(options: SessionOptions, host?: Host): Session {}},show: view => {- current = view+ // A page whose job another page does (the console's AI terminal is this shell's AI page) opens that page.+ current = view === 'ai' ? 'ai' : (PARITY[view]?.opens ?? view)- if (view !== 'ai') {- state.view = view- state.back = view+ if (current !== 'ai') {+ state.view = current+ state.back = current}},frame: (columns, depth, rows = 30) => {@@ -168,6 +173,13 @@ export function openSession(options: SessionOptions, host?: Host): Session {return drawn.lines}+ // A page about a Claude Code session says so in one screen, not as a page of empty cards.+ if (PARITY[current as ViewId]?.status === 'claude-only') {+ const entry = VIEWS.find(view => view.id === current)++ return [`${entry?.label ?? current}: Claude Code only`, '', PARITY[current as ViewId].why, '', 'Open it in the ruflo console inside Claude Code. Press 0 for the main menu, Esc to go back.']+ }+// Pictures need colour and room: without either the views say in words what the picture shows (the same fallback the console has below NARROW columns).const draws = options.pictures !== false && depth !== 'none' && columns >= NARROWconst now = Date.now()diff --git a/v3/@claude-flow/cli/__tests__/tui-command.test.ts b/v3/@claude-flow/cli/__tests__/tui-command.test.tsindex f8bf3fc949..34225277e2 100644--- a/v3/@claude-flow/cli/__tests__/tui-command.test.ts+++ b/v3/@claude-flow/cli/__tests__/tui-command.test.ts@@ -64,8 +64,8 @@ describe('tui command', () => {expect(result).toMatchObject({ success: false, exitCode: 1 });});- it.skipIf(locateTuiBundle() === null)('opens each of the six pages with --plain, and refuses Room and anything else with exit 2 (real bundle)', async () => {- for (const view of ['overview', 'cost', 'swarm', 'events', 'missions', 'ai']) {+ it.skipIf(locateTuiBundle() === null)('opens each of the six pages and any other console view with --plain, and refuses an unknown name with exit 2 (real bundle)', async () => {+ for (const view of ['overview', 'cost', 'swarm', 'events', 'missions', 'ai', 'menu', 'federation', 'settings', 'room']) {const lines: string[] = [];const real = process.stdout.write.bind(process.stdout);process.stdout.write = ((chunk: string | Uint8Array) => (lines.push(String(chunk)), true)) as typeof process.stdout.write;@@ -80,7 +80,7 @@ describe('tui command', () => {expect(lines.join(''), view).not.toContain(process.env.OPENROUTER_API_KEY ?? '\u0000never');}- for (const view of ['room', 'nope']) {+ for (const view of ['nope', 'federation; rm -rf /']) {expect(await tuiCommand.action!({ args: [], flags: { view, plain: true }, cwd: tmp() } as never), view).toMatchObject({ success: false, exitCode: 2 });}});@@ -152,7 +152,7 @@ describe('tui command', () => {describe('the look and motion flags', () => {it('pass a valid look, an fps from 0 to 30 (a number or digits), --no-anim, --no-pictures and --boot, and nothing else', () => {expect(lookFlags({})).toEqual({});- expect(lookFlags({ look: 'orbital', fps: 12, anim: false, pictures: false, boot: true })).toEqual({ look: 'orbital', fps: 12, anim: false, pictures: false, boot: true });+ expect(lookFlags({ look: 'orbital', fps: 12, anim: false, pictures: false, boot: true, mouse: true })).toEqual({ look: 'orbital', fps: 12, anim: false, pictures: false, boot: true, mouse: true });expect(lookFlags({ look: 'bbs', fps: '30' })).toEqual({ look: 'bbs', fps: 30 });expect(lookFlags({ fps: 0 })).toEqual({ fps: 0 });});@@ -166,6 +166,6 @@ describe('the look and motion flags', () => {});it('are listed in the command\'s options', () => {- expect((tuiCommand.options ?? []).map(option => option.name)).toEqual(expect.arrayContaining(['look', 'fps', 'anim', 'pictures', 'boot']));+ expect((tuiCommand.options ?? []).map(option => option.name)).toEqual(expect.arrayContaining(['look', 'fps', 'anim', 'pictures', 'boot', 'mouse']));});});diff --git a/v3/@claude-flow/cli/src/commands/tui.ts b/v3/@claude-flow/cli/src/commands/tui.tsindex db87c06fa0..82e4934a04 100644--- a/v3/@claude-flow/cli/src/commands/tui.ts+++ b/v3/@claude-flow/cli/src/commands/tui.ts@@ -25,7 +25,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));const VIEWS = ['overview', 'cost', 'swarm', 'events', 'missions', 'ai'] as const;-type TuiModule = { runTui: (options: Record<string, unknown>, io: Record<string, unknown>) => Promise<number>; isTuiView: (value: unknown) => boolean };+type TuiModule = { runTui: (options: Record<string, unknown>, io: Record<string, unknown>) => Promise<number>; isTuiView: (value: unknown) => boolean; isPage?: (value: unknown) => boolean };/** `<own install>/plugins/ruflo-console/dist/tui.mjs`, the first that exists. */export function locateTuiBundle(startDir: string = __dirname): string | null {@@ -43,7 +43,7 @@ function cliEntry(): string | undefined {}/** The look and motion flags: `--look bbs|orbital|plain` (default bbs, as in the console), `--fps N` (0-30, default 8; 0 draws pictures still), `--no-anim`, `--no-pictures`. A bad value is ignored, never passed on. */-export function lookFlags(flags: Record<string, unknown> | undefined): { look?: string; fps?: number; anim?: boolean; pictures?: boolean; boot?: boolean } {+export function lookFlags(flags: Record<string, unknown> | undefined): { look?: string; fps?: number; anim?: boolean; pictures?: boolean; boot?: boolean; mouse?: boolean } {const look = flags?.look;const fps = flags?.fps;const number = typeof fps === 'number' ? fps : typeof fps === 'string' && /^\d{1,2}$/.test(fps) ? Number(fps) : undefined;@@ -54,6 +54,7 @@ export function lookFlags(flags: Record<string, unknown> | undefined): { look?:...(flags?.anim === false ? { anim: false } : {}),...(flags?.pictures === false ? { pictures: false } : {}),...(flags?.boot === true ? { boot: true } : {}),+ ...(flags?.mouse === true ? { mouse: true } : {}),};}@@ -71,7 +72,7 @@ export const tuiCommand: Command = {name: 'tui',description: 'The ruflo console in your terminal: Overview, Cost, Swarm, Events, Missions (read-only) and an AI page that asks Codex or OpenRouter, each question after a card.',options: [- { name: 'view', description: `Page to open: ${VIEWS.join(' | ')}`, type: 'string' as const, default: 'overview' },+ { name: 'view', description: `Page to open: ${VIEWS.join(' | ')}, or any console view (menu, federation, settings, ...): 0 opens the menu and : goes to a page by name`, type: 'string' as const, default: 'overview' },{ name: 'ai', description: 'The AI page (ask Codex read-only or OpenRouter, each question after a confirm card). --no-ai turns it off', type: 'boolean' as const, default: true },{ name: 'model', description: 'OpenRouter model for this session (default openrouter/auto)', type: 'string' as const },{ name: 'max-spend-usd', description: 'Stop sending to OpenRouter once the provider-reported spend reaches this (default 0.5)', type: 'number' as const },@@ -80,6 +81,7 @@ export const tuiCommand: Command = {{ name: 'fps', description: 'Frames per second for moving pictures, 0-30 (default 8; 0 draws every picture still)', type: 'number' as const },{ name: 'anim', description: 'Animate the pictures. --no-anim draws them still', type: 'boolean' as const, default: true },{ name: 'pictures', description: 'Draw the pictures of the console (title art, swarm graph, gauges). --no-pictures shows their words only', type: 'boolean' as const, default: true },+ { name: 'mouse', description: 'Read mouse reports: click a page in the bar, scroll with the wheel (every action also has a key)', type: 'boolean' as const, default: false },{ name: 'boot', description: 'Play the look\'s start-up screen first (as the console\'s boot setting)', type: 'boolean' as const, default: false },{ name: 'plain', description: 'Print one frame as plain text and exit 0 (scripts and CI). Without it, a non-terminal gets a hint and exit 2', type: 'boolean' as const, default: false },],@@ -93,7 +95,10 @@ export const tuiCommand: Command = {const ctx = context as { args?: string[]; flags?: Record<string, unknown>; cwd?: string };const wanted = (ctx.flags?.view as string | undefined) ?? ctx.args?.find(arg => !arg.startsWith('-')) ?? 'overview';- if (!(VIEWS as readonly string[]).includes(wanted)) {+ // The six pages are known here; any other console view (menu, federation, settings, …) is checked against the bundle's own list once it is loaded.+ const isKnown = (VIEWS as readonly string[]).includes(wanted);++ if (!isKnown && !/^[a-z]{2,16}$/.test(wanted)) {output.writeln(output.error(`tui: unknown view "${String(wanted).slice(0, 40)}". Use one of: ${VIEWS.join(', ')}`));return { success: false, exitCode: 2, data: { error: 'unknown-view' } };}@@ -113,6 +118,11 @@ export const tuiCommand: Command = {return { success: false, exitCode: 1, data: { error: 'bundle-load-failed' } };}+ if (!isKnown && mod.isPage?.(wanted) !== true) {+ output.writeln(output.error(`tui: unknown view "${String(wanted).slice(0, 40)}". Use one of: ${VIEWS.join(', ')}, or any console view such as menu, federation, settings`));+ return { success: false, exitCode: 2, data: { error: 'unknown-view' } };+ }+const stop = new AbortController();const onSignal = () => stop.abort();process.once('SIGTERM', onSignal);diff --git a/v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md b/v3/docs/adr/ADR-489-ruflo-tui-standalone-console.mdindex f699f87fa5..71601add37 100644--- a/v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md+++ b/v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md@@ -1,6 +1,6 @@# ADR 489: `ruflo tui`: the console in a terminal of its own, over the same views-Status: Accepted. The owner accepted decisions A to E on 2026-10-11 (section 8). Phase 1 (read-only Overview and Cost, `--plain`, publish wiring) is implemented in PR #4059; phase 2 (Swarm, Events and Missions, page bar and keys, resize, host capability flag) is implemented in PR #4075; phase 3 (the AI page: Codex and OpenRouter, each question after a card) is implemented in PR 2 of the continuation; phase 4 (pictures, looks and motion) is implemented in console 0.44.0; phase 5 (every console view through this host) and phase 6 (actions) are the roadmap and must follow those decisions.+Status: Accepted. The owner accepted decisions A to E on 2026-10-11 (section 8). Phase 1 (read-only Overview and Cost, `--plain`, publish wiring) is implemented in PR #4059; phase 2 (Swarm, Events and Missions, page bar and keys, resize, host capability flag) is implemented in PR #4075; phase 3 (the AI page: Codex and OpenRouter, each question after a card) is implemented in PR 2 of the continuation; phase 4 (pictures, looks and motion) is implemented in console 0.44.0; phase 5 (every console view through this host, the menu, the go prompt, Back and the mouse) is implemented in the next change; phase 6 (actions) is the roadmap and must follow those decisions.Date: 2026-10-11@@ -159,7 +159,7 @@ not a replacement and not a second implementation.- **Spend.** `--max-spend-usd` (default 0.5) stops the next OpenRouter question once the provider-reported total reaches it. Codex reports no dollars: its turns are counted and its cost reads n/a. The multi-provider ledger (ADR-437) reads Codex's own rollouts and OpenRouter's key usage; this page adds no writer to it.- **Not in this PR:** the per-session **workspace-write opt-in**. The host accepts `workspace-write` when built with `allowWrite` and the guard pins it (tests), but the page offers no toggle and the console's Codex argv is read-only, so no write path exists yet; it needs a card that names the files Codex may change, which is phase 4.4. **Pictures, looks and motion (done, console 0.44.0).** The kit gains `Raster` (`tui/ansi.ts`): the Grid's cells drawn as coloured glyphs, 24-bit when `COLORTERM` says so and the nearest of the 256 otherwise. A cell is data: a control, escape, invisible, surrogate or wide code point becomes a space, `cells` that are not exactly `columns*rows` u32 triplets (or exceed 200*90) draw nothing, and the secret-line filter still applies. The standalone pane now leads each page with the same `art()` the console uses (title or masthead, the swarm graph and the other pictures), in the console's three looks (Classic BBS default, Orbital, plain; `--look`, `t`), with `--boot` for the start-up screen. Pictures move at `--fps` (default 8, max 30, `--no-anim` or 0 for still): key presses and resizes write a whole frame as before, animation ticks write only the rows that changed with absolute positioning; ticks are skipped while a frame is being written, and stop while the terminal reports focus lost (`ESC[?1004h`). No colour (`NO_COLOR`, `TERM=dumb`), `--no-pictures`, or under 44 columns: the words of each picture, as before. No new network and no new write path. Measured on Linux/tmux: bundle +1.2 KB gzip; about 2-3% of one core and 14-80 KB/s at 8 fps, about 9% and 230 KB/s at 30 fps (Orbital, 200x50 is the worst case). Unverified: Windows, macOS, terminals other than tmux/xterm-256color.-5. **Every console view through this host (roadmap).** Each view in the console's `VIEWS` list gets a recorded decision in the parity table below (identical, "Claude Code only" with a one-line reason, or needs a host capability), a main menu with grouped navigation, `go <view>` by name and optional mouse reporting with key fallback.+5. **Every console view through this host (done).** The six pages stay the page bar. Every other console view opens with the console's own body: `0` is the main menu (its keys open entries, `p` is the go prompt), `:` or `/` is the go prompt (name, id, key or prefix, via the console's own `viewOf`), `Esc` or Backspace is Back (a 30-deep history), `--view` takes any page. Each view has a decision in `tui/parity.ts` (`same`, `partial`, `equivalent`, `claude-only`) and a row in the table below; `tests/tui-parity.spec.ts` fails when a view in the console's `VIEWS` has no decision or no row. The terminal renderer now honours a Box's `width` (the board's two groups sit side by side, as on the console) and draws the board's entry labels (they were blank). **Mouse** is opt-in (`--mouse`, SGR reports): a click on a page chip opens it and the wheel scrolls; reports are switched on only with the flag and off on exit, and report bytes are ignored without it. Buttons inside a page are not clickable here, because they act and acting waits for phase 6.6. **Actions.** Pressable buttons and fields (an optional lazily loaded input dependency, or hand-rolled), the confirm card, the palette; each write goes through `Runner` as in the mod.### Parity with the console (decisions recorded per item; the table is completed in phase 5)@@ -169,7 +169,46 @@ not a replacement and not a second implementation.| Title art, masthead, pictures, looks, boot, animation | Same drawings (phase 4) | `art()` and `picturesOf()` are shared; only the Raster surface differs || Overview, Cost, Swarm, Events, Missions, AI | Shipped | phases 1 to 3 || Ask Claude buttons, Claude control card, prompt-box band, toasts, session-tool server, live session transcript (Room) | Claude Code only | they act on, or read from, a running Claude Code session that this host does not have |-| Remaining views, main menu, command palette, mouse, settings pages | Roadmap (phase 5/6) | not yet decided per view |++**Per view (checked by `tests/tui-parity.spec.ts`, which fails when a console view has no row here):**++| View | Name | In `ruflo tui` | Why |+|---|---|---|---|+| `menu` | Main Menu | same | entries open by their key, as on the console board |+| `missions` | Missions | partial | the mission record only: entering a goal, planning and research start a Claude turn |+| `overview` | Overview | same | the Claude-only controls are not drawn |+| `swarm` | Swarm | same | topology, agents and votes as ruflo wrote them |+| `hive` | Hive-Mind | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `claims` | Claims | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `workflows` | Workflows | partial | the ruflo swarm side; Claude Code workflow runs are not visible outside a session |+| `federation` | Federation | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `plugins` | Plugins | partial | what is installed and loaded; "loaded as a mod" is a Claude Code fact and reads n/a |+| `learning` | Learning | same | router picks, outcomes and the pipeline as on disk |+| `metaharness` | MetaHarness | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `memory` | Memory | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `cost` | Cost | partial | provider ledger and router counts; Claude Code spend, context and the budget ladder read n/a |+| `timeline` | Timeline | partial | agent lanes from status reports; Claude Code tool-call lanes need a session |+| `approvals` | Approvals | partial | shows what waits; answering is a write and waits for the confirm gate of phase 6 |+| `events` | Events | same | the event stream as it is on disk; Ask Claude is not drawn |+| `room` | Room | claude-only | it is what people said to Claude in a session, plus a message box; this terminal has neither |+| `xruv` | x.ruv.io | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `terminal` | Terminal | equivalent | the standalone AI page (Codex or OpenRouter, each question after a card) |+| `skills` | Skills | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `secure` | Security & Doctor | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `perf` | Performance | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `automate` | Automation | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `neural` | Learning Lab | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `vector` | Vector Lab | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `evolve` | Self-Evolution | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `devtools` | Dev Tools | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `sandbox` | Sandbox | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `market` | Plugin Catalog | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `adrs` | ADRs | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |+| `whatsnew` | What’s new | same | changelogs of the installed plugins |+| `themes` | Theme Studio | partial | the look is chosen with t or --look; the colour picker and generated themes are not here yet |+| `settings` | Settings | partial | shown read-only; changing a setting waits for the confirm gate of phase 6 |+| `agent` | Agent drill-down | partial | the drill-down from a Swarm selection; selecting needs the host keys, so it says so |+## 5. Risks