Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

feat(tui): Swarm, Events and Missions pages, page bar and keys, resize, and no Claude-only chrome (ADR-489 phase 2)

rba6f9273a301
diff --git a/plugins/ruflo-console/.claude-plugin/plugin.json b/plugins/ruflo-console/.claude-plugin/plugin.json
index b1b744a676..b11ff5353c 100644
--- a/plugins/ruflo-console/.claude-plugin/plugin.json
+++ b/plugins/ruflo-console/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-console",
"description": "ruflo's cockpit inside Claude Code and the one /ruflo command for every ruflo mod (function hooks, early access). Views: overview with health alerts, swarm topology graph, claims flow with TTL rings, federation map, plugin health matrix, learning curve and pipeline, MetaHarness radar and audit trend, memory, cost gauge, agent timeline, approvals queue, event stream, a main menu, an x.ruv.io federation board, an AI terminal (codex, claude or both in remembered sessions, streamed), Skills (npx skills), a Hive-Mind view, a MetaHarness lab, agent drill-down; a command palette for confirm-gated actions through the ruflo CLI; a band above the prompt. Reads ruflo's files and the CLI's local JSON; anything not measured reads n/a. The one network call it makes by itself is a daily read of the published plugin.json at github.com/ruvnet/ruflo to offer an update (Settings → Updates: ask, auto, or off); it installs only through Claude Code's own claude plugin update, and never a new major version without asking.",
- "version": "0.42.6",
+ "version": "0.42.7",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-console/CHANGELOG.md b/plugins/ruflo-console/CHANGELOG.md
index df9b047452..9d94411de1 100644
--- a/plugins/ruflo-console/CHANGELOG.md
+++ b/plugins/ruflo-console/CHANGELOG.md
@@ -2,6 +2,11 @@
Newest first. One `## <version> — <date>` heading per version, then `feat:`, `fix:`, `breaking:` and `chore:` bullets (ADR-478). Built from git history; older versions: `git log -- plugins/ruflo-console`.
+## 0.42.7 — 2026-10-11
+- feat: `ruflo tui` has five pages: Overview, Cost, Swarm, Events and Missions (keys 1 to 5, or o c s e m; Tab and Shift-Tab cycle). A page bar shows where you are, a key line says what the keys are, and the terminal redraws on a resize (a short bar under 60 columns, a one-line notice under 40). Room is left out on purpose: it is a message box and Claude sessions this host does not have (ADR-489)
+- fix: on the standalone terminal the shared chrome no longer draws what only Claude Code can do: no tab bar, footer buttons, Launch section, Ask Claude buttons or Claude control card, and buttons that nobody can press are not drawn (a state chip such as `● all 0` and a section title are). Under Claude Code nothing changes: every new branch is behind `state.isStandalone`
+- fix: Missions on the standalone terminal reads the mission record only (ADR-406); the goal field, plan and research launch are Claude turns and are not shown
+
## 0.42.6 — 2026-10-10
- fix: the Plugin Catalog says "mod synced here, plugin not installed" (and marks the row ◇) for a mod Claude Code loaded by sync, such as ruflo-arena@synced, instead of a flat "not installed" that contradicted the Plugins page; the install button stays (#3979)
- chore: work-in-progress and merge lines are dropped from the console and mods changelogs shown on What's new (#3979)
diff --git a/plugins/ruflo-console/README.md b/plugins/ruflo-console/README.md
index 3bd0c1cbcd..48279b5a2d 100644
--- a/plugins/ruflo-console/README.md
+++ b/plugins/ruflo-console/README.md
@@ -47,16 +47,16 @@ CONSOLE_DRIVE_INSTALL="$PWD:ruflo-mods@ruflo" RUFLO_E2E_LIVE=1 bash plugins/rufl
## In a terminal of its own: `ruflo tui` (ADR-489)
-The same Overview and Cost views, drawn by a small standalone terminal host instead of Claude Code. Read-only; `npx ruflo tui` (the `ruflo` package and `@claude-flow/cli` carry the bundle).
+The same views the mod draws, on five pages (Overview, Cost, Swarm, Events, Missions), drawn by a small standalone terminal host instead of Claude Code. Read-only; `npx ruflo tui` (the `ruflo` package and `@claude-flow/cli` carry the bundle).
```bash
-npx ruflo tui # interactive: o overview, c cost, Tab, j/k, PgUp/PgDn, g/G, r refresh, q quit
-npx ruflo tui --view cost # start on the Cost page
+npx ruflo tui # interactive: 1-5 or o c s e m pick a page, Tab/Shift-Tab cycle, j/k, PgUp/PgDn, g/G, r refresh, q quit
+npx ruflo tui --view swarm # start on the Swarm page
npx ruflo tui --plain | head -40 # one plain frame, exit 0: for scripts and CI
npx ruflo tui | cat # no terminal and no --plain: a one-line hint on stderr, exit 2
```
-From a checkout, build the bundle first: `node plugins/ruflo-console/scripts/build-tui.mjs`. Swarm, Events, Missions and Room come next, in that order; Codex and OpenRouter later, read-only by default (decisions C and D in the ADR).
+From a checkout, build the bundle first: `node plugins/ruflo-console/scripts/build-tui.mjs`. Room is not in the terminal (it is a message box and Claude sessions); Codex and OpenRouter come next, read-only by default (decision D in the ADR). A terminal narrower than 60 columns gets a short page bar, and under 40 a one-line notice.
## Toasts (ADR-477)
diff --git a/plugins/ruflo-console/hooks/state.ts b/plugins/ruflo-console/hooks/state.ts
index dd35fc3a37..15a341cd04 100644
--- a/plugins/ruflo-console/hooks/state.ts
+++ b/plugins/ruflo-console/hooks/state.ts
@@ -197,6 +197,8 @@ export type State = {
configDir: string | null
/** False in a session with no pane to show (claude -p, an SDK host): views are then answered as text. */
isInteractive: boolean
+ /** True on the standalone terminal host (ADR-489): there is no Claude session, prompt box, tab bar or mouse, so the shared chrome and the Claude-only controls are not drawn. False under Claude Code. */
+ isStandalone: boolean
/** When this module loaded: "since the console loaded" series and stall times count from here. */
loadedAtMs: number
view: ViewId
@@ -343,6 +345,7 @@ export function newState(raw: PluginOptions | undefined): State {
nostrKeyVerifiedAtMs: null,
configDir: null,
isInteractive: true,
+ isStandalone: false,
loadedAtMs: Date.now(),
view: 'overview',
back: 'overview',
diff --git a/plugins/ruflo-console/hooks/version.ts b/plugins/ruflo-console/hooks/version.ts
index 4152115a56..4dedca65dd 100644
--- a/plugins/ruflo-console/hooks/version.ts
+++ b/plugins/ruflo-console/hooks/version.ts
@@ -2,4 +2,4 @@
* The console's version, shown on the header so a person can tell which build is running. Kept equal to the plugin's manifest
* (`.claude-plugin/plugin.json`); tests/version.spec.ts fails if the two drift.
*/
-export const CONSOLE_VERSION = '0.42.6'
+export const CONSOLE_VERSION = '0.42.7'
diff --git a/plugins/ruflo-console/hooks/views/control.ts b/plugins/ruflo-console/hooks/views/control.ts
index 98545f5718..1c488ff638 100644
--- a/plugins/ruflo-console/hooks/views/control.ts
+++ b/plugins/ruflo-console/hooks/views/control.ts
@@ -8,7 +8,7 @@ const MARK = { ok: '✓', waiting: '…', denied: '✕', error: '!' } as const
const COLOR = { ok: THEME.ok, waiting: THEME.warn, denied: THEME.bad, error: THEME.bad } as const
/** True while control is on or Claude has acted this session: then the dashboard leads the page, so it is never below the fold. */
-export const isControlActive = (ctx: Ctx): boolean => levelOf(settingsOf(ctx.state).ai.modelControl) !== 'off' || ctx.state.control.log.length > 0
+export const isControlActive = (ctx: Ctx): boolean => !ctx.state.isStandalone && levelOf(settingsOf(ctx.state).ai.modelControl) !== 'off' || ctx.state.control.log.length > 0
/**
* The "Claude control" dashboard (ADR-444): whether Claude may drive the console and how far, what it has done this session, and the
@@ -16,6 +16,9 @@ export const isControlActive = (ctx: Ctx): boolean => levelOf(settingsOf(ctx.sta
*/
export function controlRows(ctx: Ctx): RenderElement[] {
const { state } = ctx
+
+ // The standalone terminal has no Claude session to control the console: the card would describe a thing that cannot happen here.
+ if (state.isStandalone) return []
const ai = settingsOf(state).ai
const level = levelOf(ai.modelControl)
const control = state.control
diff --git a/plugins/ruflo-console/hooks/views/events-parts.ts b/plugins/ruflo-console/hooks/views/events-parts.ts
index 65a71a2712..9acc51b3ac 100644
--- a/plugins/ruflo-console/hooks/views/events-parts.ts
+++ b/plugins/ruflo-console/hooks/views/events-parts.ts
@@ -74,7 +74,7 @@ export function detailRows(ctx: Ctx, entry: Row, around: readonly ConsoleEvent[]
else if (ref !== undefined) out.push(line(ctx, 'now: nothing in the last read for this ref', { dimColor: true }))
const buttons: Btn[] = [
- { key: 'ev-ask', label: ' ✦ ask Claude ', onPress: () => act.ask(event) },
+ ...(ctx.state.isStandalone ? [] : [{ key: 'ev-ask', label: ' ✦ ask Claude ', onPress: () => act.ask(event) }]),
{ key: 'ev-pin', label: ' 📌 pin ', onPress: () => act.pin(event) },
{ key: 'ev-copy', label: ' ⧉ copy line ', onPress: () => act.copy(event) },
{ key: 'ev-mute-kind', label: ` mute ${event.kind} `, onPress: () => act.muteKind(event.kind) },
diff --git a/plugins/ruflo-console/hooks/views/mission-control.ts b/plugins/ruflo-console/hooks/views/mission-control.ts
index 38f618bf10..81ba5d2029 100644
--- a/plugins/ruflo-console/hooks/views/mission-control.ts
+++ b/plugins/ruflo-console/hooks/views/mission-control.ts
@@ -223,6 +223,9 @@ const flowRows = (ctx: Ctx): RenderElement[] => wrap(FLOW, Math.max(20, ctx.colu
* mission or starts a Claude turn; ▶ auto-run is the person's opt-in to skip that confirm for the next ready task.
*/
export function missionControlView(ctx: Ctx): RenderElement {
+ // The standalone terminal reads the mission record (ADR-406) and nothing else: planning, launching and research start a Claude turn.
+ if (ctx.state.isStandalone) return col(ctx, observationRows(ctx), 'mission-record')
+
const mc = mcOf(ctx.state)
const mission = activeMission(ctx.state)
const rows: RenderElement[] = [rule(ctx, 'Mission Control', mission === null ? 'goal → SPARC plan → tasks → Claude' : `${mission.id.slice(0, 12)}…`)]
diff --git a/plugins/ruflo-console/hooks/views/missions.ts b/plugins/ruflo-console/hooks/views/missions.ts
index 97145e82fd..1644308359 100644
--- a/plugins/ruflo-console/hooks/views/missions.ts
+++ b/plugins/ruflo-console/hooks/views/missions.ts
@@ -48,7 +48,7 @@ export function observationRows(ctx: Ctx): RenderElement[] {
rows.push(...researchRows(ctx))
if (observation === null) {
- rows.push(text(ctx, ' No mission record yet (ADR-406): create one from a goal in Plan.', { color: THEME.warn }))
+ rows.push(text(ctx, ctx.state.isStandalone ? ' No mission record yet (ADR-406). Missions are made from a goal in the Claude Code console; this page shows the record once one exists.' : ' No mission record yet (ADR-406): create one from a goal in Plan.', { color: THEME.warn }))
return rows
}
diff --git a/plugins/ruflo-console/hooks/views/optimizer.ts b/plugins/ruflo-console/hooks/views/optimizer.ts
index fe4445a730..82580f9ea8 100644
--- a/plugins/ruflo-console/hooks/views/optimizer.ts
+++ b/plugins/ruflo-console/hooks/views/optimizer.ts
@@ -21,7 +21,8 @@ function findingRows(ctx: Ctx, finding: Finding): RenderElement[] {
return [
row(ctx, [ctx.kit.Text({ bold: true, color: COLOR[finding.level](), children: ` ${GLYPH[finding.level]} ${clip(finding.title, Math.max(20, ctx.columns - 34))} ` }), ctx.kit.Text({ dimColor: true, children: `· ${finding.area} · ${finding.metric}` })], `opt-head-${finding.id}`),
text(ctx, ` ${clip(finding.why, Math.max(20, ctx.columns - 6))}`, { dimColor: true }),
- row(
+ // The standalone terminal has no buttons, so a row of fixes (or "no button for this one") would say something false there.
+ ...(ctx.state.isStandalone ? [] : [row(
ctx,
[
...fixes.map(item => ctx.kit.Button({ key: `opt-fix-${finding.id}-${item.id}`, label: ` ▸ ${item.label} `, plain: true, onPress: () => ctx.act.optimizer.fix(finding.id, item.id) })),
@@ -29,7 +30,7 @@ function findingRows(ctx: Ctx, finding: Finding): RenderElement[] {
ctx.kit.Button({ key: `opt-ask-${finding.id}`, label: ' ✦ ask Claude ', plain: true, dimColor: true, onPress: () => ctx.act.optimizer.ask(finding.id) }),
],
`opt-fixes-${finding.id}`,
- ),
+ )]),
...(before === undefined ? [] : [text(ctx, ` after ${cfg.ran.get(finding.id) ?? 'a fix'}: ${before} → now ${now ?? 'resolved (no longer a finding)'} (refresh r re-reads)`, { color: now === null ? THEME.ok : THEME.info })]),
]
}
diff --git a/plugins/ruflo-console/hooks/views/pane.ts b/plugins/ruflo-console/hooks/views/pane.ts
index e22a156eaa..1eab9b168e 100644
--- a/plugins/ruflo-console/hooks/views/pane.ts
+++ b/plugins/ruflo-console/hooks/views/pane.ts
@@ -66,7 +66,7 @@ const NETWORKS: readonly (readonly [string, ViewId])[] = [['x.ruv.io', 'xruv'],
/** Width from which every tab spells its name beside its emoji (the 1-9 row is about 128 columns with names). */
const WIDE_TABS = 140
-const BODIES: Record<ViewId, (ctx: Ctx) => RenderElement> = {
+export const BODIES: Record<ViewId, (ctx: Ctx) => RenderElement> = {
menu: menuView,
overview: overviewView,
swarm: swarmView,
diff --git a/plugins/ruflo-console/hooks/views/standalone-pane.ts b/plugins/ruflo-console/hooks/views/standalone-pane.ts
new file mode 100644
index 0000000000..c55ec2bc50
--- /dev/null
+++ b/plugins/ruflo-console/hooks/views/standalone-pane.ts
@@ -0,0 +1,26 @@
+/**
+ * The page on the standalone terminal host (ADR-489): the view's own body in its cards, under one line that says what the page is
+ * for. Everything else paneView draws is Claude Code's surface and is left out here: the tab bar, the icon row, the footer buttons,
+ * the BBS furniture and the plugin Launch section are all mouse controls or Claude turns, and this host has neither. The terminal
+ * shell (tui/run.ts) draws its own page bar and key line in their place.
+ */
+import type { RenderElement } from 'claude-code'
+
+import { isCompactPane, VIEWS } from '../state'
+import { CARD_COLUMNS, hasCards, withCards } from './card'
+import { col, setLook, text, THEME, type Ctx } from './common'
+import { stepsRows } from './steps'
+
+export function standalonePane(base: Ctx, body: (ctx: Ctx) => RenderElement): RenderElement {
+ setLook(base.state.options.look)
+
+ const ctx = base
+ const cardsOn = hasCards(ctx.columns, isCompactPane(ctx.state))
+ const bodyCtx: Ctx = cardsOn ? { ...ctx, columns: ctx.columns - CARD_COLUMNS, cards: true, kit: withCards(ctx.kit, undefined) } : ctx
+ const view = VIEWS.find(entry => entry.id === ctx.state.view)
+ // The purpose line, minus what only Claude Code can do: Missions here is the record, and Events has no filter key.
+ const purpose = view === undefined ? '' : view.id === 'missions' ? 'the mission record ruflo wrote: state, tasks and evidence as recorded (read-only)' : view.blurb.replace(/\s*\(f filters them\)/, '')
+ const about = view === undefined ? [] : [text(ctx, `${view.icon} ${view.label} — ${purpose}`, { color: THEME.head, bold: true })]
+
+ return col(ctx, [...about, ...(cardsOn ? stepsRows(bodyCtx) : []), body(bodyCtx)], 'standalone-pane')
+}
diff --git a/plugins/ruflo-console/scripts/smoke.sh b/plugins/ruflo-console/scripts/smoke.sh
index f09288217f..56b7dcec88 100755
--- a/plugins/ruflo-console/scripts/smoke.sh
+++ b/plugins/ruflo-console/scripts/smoke.sh
@@ -11,9 +11,9 @@ step() { printf "→ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares ruflo-console 0.42.6"
+step "1. plugin.json declares ruflo-console 0.42.7"
grep -q '"name": "ruflo-console"' "$ROOT/.claude-plugin/plugin.json" \
- && grep -q '"version": "0.42.6"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
+ && grep -q '"version": "0.42.7"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
step "2. hooks.json names exactly one module and no classic hook commands"
grep -q '"modules": \["./register.ts"\]' "$HOOKS/hooks.json" && ! grep -q '"command"' "$HOOKS/hooks.json" \
diff --git a/plugins/ruflo-console/tests/tui-nav.spec.ts b/plugins/ruflo-console/tests/tui-nav.spec.ts
new file mode 100644
index 0000000000..92fb89067f
--- /dev/null
+++ b/plugins/ruflo-console/tests/tui-nav.spec.ts
@@ -0,0 +1,252 @@
+/**
+ * `ruflo tui` phase 2 (ADR-489): the five pages, the page bar and keys, resize and narrow terminals, and the chrome that must not
+ * be drawn on a host with no Claude session and no mouse. Real ruflo files on disk, an injected terminal, no engine.
+ * npx vitest run plugins/ruflo-console/tests/tui-nav.spec.ts
+ */
+import { mkdirSync, mkdtempSync, 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 { widthOf } from '../tui/ansi'
+import { keyLine, keyOf, MIN_COLUMNS, navLine, runTui, type TuiIO } from '../tui/run'
+import { openSession, TUI_VIEWS } from '../tui/session'
+import { RUFLO_FILES } from './fixtures/ruflo-run'
+
+const ESC = '\u001b'
+let root: string
+let project: string
+let hostile: string
+
+const put = (base: string, files: Record<string, string>) => {
+ for (const [path, body] of Object.entries(files)) {
+ mkdirSync(dirname(join(base, path)), { recursive: true })
+ writeFileSync(join(base, path), body)
+ }
+}
+
+beforeAll(() => {
+ root = mkdtempSync(join(tmpdir(), 'tui-nav-'))
+ project = join(root, 'project')
+ hostile = join(root, 'hostile')
+ put(project, RUFLO_FILES)
+ // A mission record whose objective and blocked reason carry an escape sequence and a token: the Missions page must show words only.
+ put(hostile, {
+ ...RUFLO_FILES,
+ '.claude-flow/missions/observation.json': JSON.stringify({
+ schemaVersion: 1,
+ contract: 'ruflo.mission-observation/1',
+ observedAt: new Date().toISOString(),
+ missions: [{ missionId: 'msn_one', objective: `ship it ${ESC}]0;pwned\u0007 ghp_abcdefghijklmnopqrstuvwxyz0123456789`, state: 'blocked', blockedReason: `needs ${ESC}[31mred${ESC}[0m review`, revision: 2, plan: { revision: 1, taskCount: 1, tasks: [{ id: 't1', title: `do ${ESC}[2Jthings`, status: 'ready' }] }, evidence: { count: 1, verified: 0 } }],
+ }),
+ })
+})
+afterAll(() => rmSync(root, { recursive: true, force: true }))
+
+function terminal(columns = 100, rows = 30) {
+ const out: string[] = []
+ const listeners: Array<(chunk: string) => void> = []
+ const resizers: Array<() => void> = []
+ const stdout = { isTTY: true, columns, rows, write: (text: string) => void out.push(text), on: (_e: 'resize', fn: () => void) => void resizers.push(fn), off: () => void resizers.splice(0) }
+ 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,
+ stderr: { write: () => undefined },
+ env: { TERM: 'xterm-256color' },
+ }
+
+ return { io, out, stdout, press: (key: string) => listeners.forEach(fn => fn(key)), resize: (c: number, r = rows) => { stdout.columns = c; stdout.rows = r; resizers.forEach(fn => fn()) } }
+}
+
+const settle = (ms = 200) => new Promise(resolve => setTimeout(resolve, ms))
+const plain = (screen: string) => screen.replace(/\u001b\[[0-9;?]*[A-Za-z]/g, '')
+/** The lines of the last frame drawn (a frame starts at cursor-home), as plain text. */
+const lastFrame = (chunks: string[]) => plain((chunks.join('').split(`${ESC}[H`).pop() ?? '').replace(/\r/g, '')).split('\n')
+
+describe('keys', () => {
+ it('maps digits and letters to the five pages, tab and arrows to neighbours, and ignores the rest', () => {
+ expect(TUI_VIEWS).toEqual(['overview', 'cost', 'swarm', 'events', 'missions'])
+ expect(['1', '2', '3', '4', '5'].map(keyOf)).toEqual(TUI_VIEWS.map(page => ({ page })))
+ expect([keyOf('o'), keyOf('c'), keyOf('s'), keyOf('e'), keyOf('m')]).toEqual([{ page: 'overview' }, { page: 'cost' }, { page: 'swarm' }, { page: 'events' }, { page: 'missions' }])
+ 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('6'), 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', () => {
+ expect(keyOf('R')).toBeNull()
+ expect(TUI_VIEWS as readonly string[]).not.toContain('room')
+ })
+})
+
+describe('page bar and key line', () => {
+ it('lists the pages with the current one marked, and shortens to a position when narrow', () => {
+ expect(navLine('swarm', 100, 'none')).toBe(' 1 Overview 2 Cost [3 Swarm] 4 Events 5 Missions ')
+ expect(navLine('swarm', 100, '256')).toContain(`${ESC}[7m 3 Swarm ${ESC}[0m`)
+ expect(navLine('swarm', 59, 'none')).toBe('‹ 3/5 Swarm ›')
+ expect(widthOf(navLine('missions', 60, '256'))).toBeLessThanOrEqual(60)
+ })
+
+ it('has a short key line for a narrow terminal and says read-only on a wide one', () => {
+ expect(keyLine(100)).toContain('read-only')
+ expect(keyLine(100)).toContain('q quit')
+ expect(keyLine(50)).toBe('1-5 page · j/k scroll · q quit')
+ expect(keyLine(25)).toBe('1-5 page · q quit')
+ for (const columns of [40, 50, 59, 60, 70, 80, 99, 120]) for (const place of ['', ' · 1-18/42']) expect(widthOf(keyLine(columns, place)), `${columns}${place}`).toBeLessThanOrEqual(columns)
+ })
+})
+
+describe('every page, on a host with no Claude session and no mouse', () => {
+ for (const columns of [80, 120]) {
+ it(`draws all five pages at ${columns} columns, no wider than the terminal, with none of Claude Code's chrome`, async () => {
+ for (const view of TUI_VIEWS) {
+ const session = openSession({ cwd: project, home: join(root, 'home') })
+
+ try {
+ session.show(view)
+ await session.refresh()
+
+ const lines = session.frame(columns, 'none')
+ const text = lines.join('\n')
+
+ expect(lines.length, view).toBeGreaterThan(3)
+ for (const line of lines) expect(widthOf(line), `${view}: ${line}`).toBeLessThanOrEqual(columns)
+ // Claude Code's surface: Ask Claude, the Claude-control card, the footer and tab buttons, hotkey brackets.
+ expect(text, view).not.toMatch(/ask claude|✦|Claude control|Take back control/i)
+ expect(text, view).not.toMatch(/Palette|Actions\]|\bClose\b|\[\s*[0-9a-z]\s{2}/)
+ expect(text, view).not.toMatch(/\[[^\]\n]*[▸▶⇩⧉🔔★][^\]\n]*\]/)
+ } finally {
+ session.stop()
+ }
+ }
+ })
+ }
+
+ it('the Missions page reads the mission record only: no goal field, no plan, no research launch', async () => {
+ const session = openSession({ cwd: project, home: join(root, 'home') })
+
+ try {
+ session.show('missions')
+ await session.refresh()
+
+ const text = session.frame(100, 'none').join('\n')
+
+ expect(text).toContain('Mission record')
+ expect(text).not.toMatch(/goal:|Plan options|Start research|use the palette/i)
+ } finally {
+ session.stop()
+ }
+ })
+
+ it('hostile mission text: words only reach the screen (no escape, no token)', async () => {
+ const session = openSession({ cwd: hostile, home: join(root, 'home') })
+
+ try {
+ session.show('missions')
+ await session.refresh()
+
+ const text = session.frame(120, '256').join('\n')
+
+ expect(text).toContain('msn_one')
+ expect(text).not.toContain(']0;pwned')
+ expect(text).not.toContain('ghp_abcdefghijklmnopqrstuvwxyz0123456789')
+ expect(text.replace(/\u001b\[[0-9;]*m/g, '')).not.toContain(ESC)
+ } finally {
+ session.stop()
+ }
+ })
+})
+
+describe('the terminal loop', () => {
+ it('jumps to a page on a digit, cycles with tab and shift-tab, and the page bar follows', async () => {
+ const t = terminal()
+ const running = runTui({ cwd: project, home: join(root, 'home') }, t.io)
+
+ await settle()
+ t.press('3')
+ t.press('\t')
+ t.press(`${ESC}[Z`)
+ t.press('e')
+ t.press('5')
+ t.press('q')
+ await expect(running).resolves.toBe(0)
+
+ const bars = plain(t.out.join('')).match(/1 Overview {1,3}2 Cost {1,3}3 Swarm {1,3}4 Events {1,3}5 Missions/g) ?? []
+
+ expect(bars.length).toBeGreaterThanOrEqual(5)
+ expect(t.out.join('')).toContain(`${ESC}[7m 3 Swarm ${ESC}[0m`)
+ expect(t.out.join('')).toContain(`${ESC}[7m 4 Events ${ESC}[0m`)
+ expect(t.out.join('')).toContain(`${ESC}[7m 5 Missions ${ESC}[0m`)
+ })
+
+ it('fills the terminal exactly: the page bar on the first row, the key line on the last', async () => {
+ for (const rows of [24, 40]) {
+ const t = terminal(100, rows)
+ const running = runTui({ cwd: project, home: join(root, 'home') }, t.io)
+
+ await settle()
+ t.press('4')
+ await settle(50)
+ t.press('q')
+ await running
+
+ const frame = lastFrame(t.out)
+
+ expect(frame, `${rows} rows`).toHaveLength(rows)
+ expect(frame[0]).toContain('4 Events')
+ expect(frame[rows - 1]).toMatch(/^1-5 or o c s e m page/)
+ }
+ })
+
+ it('redraws at the new width on a resize, clearing the screen first', async () => {
+ const t = terminal(120, 30)
+ const running = runTui({ cwd: project, home: join(root, 'home') }, t.io)
+
+ await settle()
+
+ const before = t.out.length
+
+ t.resize(70, 20)
+ await settle(50)
+
+ const after = t.out.slice(before).join('')
+
+ expect(after.startsWith(`${ESC}[2J`)).toBe(true)
+ for (const line of lastFrame(t.out)) expect(widthOf(line), line).toBeLessThanOrEqual(70)
+ t.press('q')
+ await running
+ })
+
+ it('under 60 columns it draws the position bar and the short key line; under 40 it says how wide it needs to be', async () => {
+ const narrow = terminal(52, 24)
+ const running = runTui({ cwd: project, home: join(root, 'home') }, narrow.io)
+
+ await settle()
+ expect(plain(narrow.out.join(''))).toContain('‹ 1/5 Overview ›')
+ expect(plain(narrow.out.join(''))).toContain('1-5 page · j/k scroll · q quit')
+ for (const line of lastFrame(narrow.out)) expect(widthOf(line), line).toBeLessThanOrEqual(52)
+
+ const before = narrow.out.length
+
+ narrow.resize(MIN_COLUMNS - 1)
+ await settle(50)
+ expect(plain(narrow.out.slice(before).join(''))).toContain('Too narrow: need 40 columns')
+ narrow.press('q')
+ await expect(running).resolves.toBe(0)
+ })
+
+ it('--plain prints the page bar then the frame, with no escapes, for any page', async () => {
+ for (const view of TUI_VIEWS) {
+ const out: string[] = []
+ const code = await runTui(
+ { cwd: project, home: join(root, 'home'), plain: true, view },
+ { stdin: { on: () => undefined, off: () => undefined, resume: () => undefined, pause: () => undefined }, stdout: { columns: 90, rows: 30, write: text => void out.push(text) }, stderr: { write: () => undefined }, env: {} },
+ )
+ const text = out.join('')
+
+ expect(code).toBe(0)
+ expect(text).not.toContain(ESC)
+ expect(text.split('\n')[0]).toContain(`[${{ overview: '1 Overview', cost: '2 Cost', swarm: '3 Swarm', events: '4 Events', missions: '5 Missions' }[view]}]`)
+ }
+ })
+})
diff --git a/plugins/ruflo-console/tests/tui-render.spec.ts b/plugins/ruflo-console/tests/tui-render.spec.ts
index c4477a55b5..5ba69ea4bb 100644
--- a/plugins/ruflo-console/tests/tui-render.spec.ts
+++ b/plugins/ruflo-console/tests/tui-render.spec.ts
@@ -88,8 +88,14 @@ describe('render', () => {
expect(widthOf(render(text('🏠'.repeat(20), { wrap: 'truncate-end' }), 11, 'none')[0] as string)).toBeLessThanOrEqual(11)
})
- it('draws a button as an inert bracketed label and skips hidden boxes', () => {
- expect(render(kit.Button({ key: 'k', label: 'Refresh' } as never), 30, 'none')).toEqual(['[Refresh]'])
+ it('draws only a state chip from a button (a control nobody can press is not drawn), and skips hidden boxes', () => {
+ expect(render(kit.Button({ key: 'k', label: 'Refresh' } as never), 30, 'none')).toEqual([])
+ expect(render(kit.Button({ key: 'k', label: ' ✦ ask Claude ' } as never), 30, 'none')).toEqual([])
+ expect(render(kit.Button({ key: 'k', label: ' ● all 3 ', hotkey: 'a' } as never), 30, 'none')).toEqual(['● all 3 '])
+ expect(render(kit.Button({ key: 'k', label: ' ○ bad 0 ' } as never), 30, 'none')).toEqual(['○ bad 0 '])
+ // A section title stays, without the fold mark (nothing folds in a terminal).
+ expect(render(kit.Button({ key: 'sec-optimizer', label: '▾ Optimizer' } as never), 30, 'none')).toEqual(['Optimizer'])
+ expect(render(kit.Button({ key: 'sec-plan', label: '▸ Plan options' } as never), 30, 'none')).toEqual(['Plan options'])
expect(render(box([text('gone')], { hidden: true }), 30, 'none')).toEqual([])
})
diff --git a/plugins/ruflo-console/tests/tui-session.spec.ts b/plugins/ruflo-console/tests/tui-session.spec.ts
index 82f766426a..822d2ca16e 100644
--- a/plugins/ruflo-console/tests/tui-session.spec.ts
+++ b/plugins/ruflo-console/tests/tui-session.spec.ts
@@ -1,6 +1,6 @@
/**
* `ruflo tui` end to end without a terminal (ADR-489): real ruflo files on disk, the mod's own controller and views over the Node
- * host, drawn by the mod's own paneView, headless and with an injected terminal. Run with
+ * host, drawn by the mod's own page bodies in the standalone pane, headless and with an injected terminal. Run with
* npx vitest run plugins/ruflo-console/tests/tui-session.spec.ts
*/
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
@@ -199,7 +199,7 @@ describe('interactive', () => {
expect(screen.startsWith(`${ESC}[?1049h`)).toBe(true)
expect(screen).toContain('Where it goes')
- expect(screen).toContain('cost ·')
+ expect(screen).toContain('2 Cost')
expect(screen.endsWith(`${ESC}[?25h${ESC}[?1049l`)).toBe(true)
expect(raw).toEqual([true, false])
})
@@ -219,7 +219,7 @@ describe('interactive', () => {
describe('keys and colour depth', () => {
it('maps the documented keys and ignores the rest', () => {
- expect([keyOf('q'), keyOf('\u0003'), keyOf('o'), keyOf('c'), keyOf('r'), keyOf('j'), keyOf(`${ESC}[A`), keyOf(' ')]).toEqual(['quit', 'quit', 'overview', 'cost', 'refresh', 'down', 'up', 'pagedown'])
+ expect([keyOf('q'), keyOf('\u0003'), keyOf('o'), keyOf('c'), keyOf('r'), keyOf('j'), keyOf(`${ESC}[A`), keyOf(' ')]).toEqual(['quit', 'quit', { page: 'overview' }, { page: 'cost' }, 'refresh', 'down', 'up', 'pagedown'])
expect([keyOf('x'), keyOf(`${ESC}]0;t\u0007`), keyOf('')]).toEqual([null, null, null])
})
diff --git a/plugins/ruflo-console/tui/ansi.ts b/plugins/ruflo-console/tui/ansi.ts
index 190c1595c2..285d657f4d 100644
--- a/plugins/ruflo-console/tui/ansi.ts
+++ b/plugins/ruflo-console/tui/ansi.ts
@@ -176,10 +176,18 @@ export function render(node: unknown, width: number, depth: Depth): string[] {
return lines.map(line => (open === '' ? line : `${open}${line}${RESET}`))
}
+ // A Button is a mouse or hotkey control of the Claude Code host, and this terminal has neither: a control that would act is not drawn
+ // (a bracketed "button" nobody can press is a lie), and one that starts a Claude turn (✦) never is. What stays is information:
+ // a section title (key `sec-…`, without its fold mark since nothing folds here), and a chip that shows a state, such as `● all 0`
+ // against `○ bad 0`, with a gap after it so neighbours do not run together.
if (type === 'Button') {
- const label = clean(props.label)
+ const label = clean(props.label).trim()
- return [cut(`${sgr({ dimColor: true }, depth)}[${props.hotkey === undefined ? '' : `${clean(props.hotkey)} `}${label}]${depth === 'none' ? '' : RESET}`, width)]
+ if (label.includes('✦')) return []
+
+ 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)] : []
}
if (type !== 'Box') return []
diff --git a/plugins/ruflo-console/tui/run.ts b/plugins/ruflo-console/tui/run.ts
index bd26c0153a..bb0378e849 100644
--- a/plugins/ruflo-console/tui/run.ts
+++ b/plugins/ruflo-console/tui/run.ts
@@ -4,6 +4,7 @@
* a test drives it without a terminal.
*/
import type { Depth } from './ansi'
+import { cells, clean } from './ansi'
import { openSession, TUI_VIEWS, type Session, type TuiView } from './session'
export type TuiInput = {
@@ -35,11 +36,37 @@ export function depthOf(env: Record<string, string | undefined>): Depth {
return env.COLORTERM === 'truecolor' || env.COLORTERM === '24bit' ? 'truecolor' : '256'
}
-const KEYS = 'o overview · c cost · r refresh · j/k scroll · q quit'
const ESC = '\u001b'
+/** Below this the frame is a short message, not a squeezed page; below NARROW the bar and the key line are the short forms. */
+export const MIN_COLUMNS = 40
+export const NARROW_COLUMNS = 60
+
+const LABELS: Record<TuiView, string> = { overview: 'Overview', cost: 'Cost', swarm: 'Swarm', events: 'Events', missions: 'Missions' }
+const LETTER: Partial<Record<string, TuiView>> = { o: 'overview', c: 'cost', s: 'swarm', e: 'events', m: 'missions' }
+
+/** The page bar: every page with its number (the current one in reverse), or `‹ 3/5 Swarm ›` when the terminal is narrow. Page names are ours, never from a file. */
+export function navLine(view: TuiView, columns: number, depth: Depth): string {
+ const at = TUI_VIEWS.indexOf(view)
+
+ if (columns < NARROW_COLUMNS) return `‹ ${at + 1}/${TUI_VIEWS.length} ${LABELS[view]} ›`
+
+ return 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(' ')
+}
+
+/** 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). */
+export function keyLine(columns: number, place = ''): string {
+ const tiers = [`1-${TUI_VIEWS.length} or o c s e m page · tab next · r refresh · j/k scroll · q quit · read-only`, '1-5 page · tab next · r refresh · j/k scroll · q quit', '1-5 page · j/k scroll · q quit', '1-5 page · q quit']
+ const fits = tiers.find(line => cells(line + place) <= columns) ?? tiers[tiers.length - 1] as string
+
+ return `${fits}${place}`.slice(0, columns)
+}
/** One keypress as an action, from the bytes a terminal sends. Anything else is ignored. */
-export type Key = 'quit' | 'overview' | 'cost' | 'next' | 'refresh' | 'down' | 'up' | 'pagedown' | 'pageup' | 'top' | 'bottom' | null
+export type Key = 'quit' | { page: TuiView } | 'next' | 'prev' | 'refresh' | 'down' | 'up' | 'pagedown' | 'pageup' | 'top' | 'bottom' | null
export function keyOf(chunk: string): Key {
switch (chunk) {
@@ -47,12 +74,14 @@ export function keyOf(chunk: string): Key {
case '\u0003':
case '\u0004':
return 'quit'
- case 'o':
- return 'overview'
- case 'c':
- return 'cost'
case '\t':
+ case 'l':
+ case `${ESC}[C`:
return 'next'
+ case `${ESC}[Z`:
+ case 'h':
+ case `${ESC}[D`:
+ return 'prev'
case 'r':
return 'refresh'
case 'j':
@@ -73,15 +102,29 @@ export function keyOf(chunk: string): Key {
case 'G':
case `${ESC}[F`:
return 'bottom'
- default:
- return null
+ default: {
+ const digit = /^[1-9]$/.test(chunk) ? TUI_VIEWS[Number(chunk) - 1] : undefined
+ const page = digit ?? LETTER[chunk]
+
+ return page === undefined ? null : { page }
+ }
}
}
-function paint(session: Session, io: TuiIO, depth: Depth, scroll: number): number {
- const columns = Math.max(40, Math.min(200, io.stdout.columns ?? 100))
+function paint(session: Session, io: TuiIO, depth: Depth, scroll: number, clear = false): number {
+ const raw = io.stdout.columns ?? 100
const rows = Math.max(5, io.stdout.rows ?? 30)
- const room = rows - 1
+ const reset = clear ? `${ESC}[2J` : ''
+
+ // Too narrow for a page: say so in a line that fits, rather than a squeezed frame of broken cards.
+ if (raw < MIN_COLUMNS) {
+ io.stdout.write(`${reset}${ESC}[H${'Too narrow: need 40 columns (q quits)'.slice(0, Math.max(1, raw))}${ESC}[K${ESC}[J`)
+
+ return 0
+ }
+
+ const columns = Math.min(200, raw)
+ const room = rows - 2
let lines: string[]
try {
@@ -91,9 +134,10 @@ function paint(session: Session, io: TuiIO, depth: Depth, scroll: number): numbe
}
const top = Math.max(0, Math.min(scroll, Math.max(0, lines.length - room)))
- const footer = `${depth === 'none' ? '' : `${ESC}[7m`} ${session.state.view} · ${top + 1}-${Math.min(lines.length, top + room)}/${lines.length} · ${KEYS} · read-only ${depth === 'none' ? '' : `${ESC}[0m`}`
+ 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))}${depth === 'none' ? '' : `${ESC}[0m`}`
- io.stdout.write(`${ESC}[H${lines.slice(top, top + room).map(line => `${line}${ESC}[K`).join('\r\n')}${ESC}[J\r\n${footer.slice(0, columns + 12)}`)
+ io.stdout.write(`${reset}${ESC}[H${navLine(session.state.view as TuiView, columns, depth)}${ESC}[K\r\n${[...lines.slice(top, top + room), ...Array.from({ length: Math.max(0, room - (lines.length - top)) }, () => '')].map(line => `${line}${ESC}[K`).join('\r\n')}${ESC}[J\r\n${footer}`)
return top
}
@@ -102,7 +146,9 @@ function paint(session: Session, io: TuiIO, depth: Depth, scroll: number): numbe
async function once(session: Session, io: TuiIO, view: TuiView): Promise<number> {
session.show(view)
await session.refresh()
- io.stdout.write(`${session.frame(Math.max(40, Math.min(200, io.stdout.columns ?? 100)), 'none').join('\n')}\n`)
+ const columns = Math.max(MIN_COLUMNS, Math.min(200, io.stdout.columns ?? 100))
+
+ io.stdout.write(`${navLine(view, columns, 'none')}\n${session.frame(columns, 'none').join('\n')}\n`)
return 0
}
@@ -140,8 +186,9 @@ export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {
const page = Math.max(1, (io.stdout.rows ?? 30) - 2)
if (key === 'quit') return finish()
- if (key === 'overview' || key === 'cost') (view = key), (scroll = 0), session.show(view)
+ if (typeof key === 'object' && key !== null) (view = key.page), (scroll = 0), session.show(view)
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)
else if (key === 'down') scroll += 1
else if (key === 'up') scroll = Math.max(0, scroll - 1)
else if (key === 'pagedown') scroll += page
@@ -159,7 +206,9 @@ export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {
io.stdin.setRawMode(true)
io.stdin.resume()
io.stdin.on('data', onKey)
- io.stdout.on?.('resize', draw)
+ const resize = () => void (scroll = paint(session, io, depth, scroll, true))
+
+ io.stdout.on?.('resize', resize)
io.signal?.addEventListener('abort', finish, { once: true })
draw()
@@ -173,7 +222,7 @@ export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {
isDone = true
clearInterval(timer)
io.stdin.off('data', onKey)
- io.stdout.off?.('resize', draw)
+ io.stdout.off?.('resize', resize)
io.stdin.setRawMode(false)
io.stdin.pause()
io.stdout.write(`${ESC}[?25h${ESC}[?1049l`)
diff --git a/plugins/ruflo-console/tui/session.ts b/plugins/ruflo-console/tui/session.ts
index c31d7193e6..3bd95c1f07 100644
--- a/plugins/ruflo-console/tui/session.ts
+++ b/plugins/ruflo-console/tui/session.ts
@@ -1,16 +1,21 @@
/**
- * One standalone console session (ADR-489): the mod's own state and controller over the Node host, drawn by the mod's own
- * `paneView` into terminal lines. This is the "same code path": nothing below `paneView` is forked; only the Host and the Kit differ.
+ * One standalone console session (ADR-489): the mod's own state and controller over the Node host, with the mod's own page bodies
+ * (`BODIES`, the same functions `paneView` calls) drawn by `standalonePane` into terminal lines. This is the "same code path": no view is
+ * forked; only the Host, the Kit and the pane around the body differ (Claude Code's tab bar, footer and Launch section are not drawn here).
*/
import { createController, type Controller } from '../hooks/controller'
import type { Host } from '../hooks/host'
import { newState, type State, type ViewId } from '../hooks/state'
-import { paneView } from '../hooks/views/pane'
+import { BODIES } from '../hooks/views/pane'
+import { standalonePane } from '../hooks/views/standalone-pane'
import { render, terminalKit, type Depth } from './ansi'
import { createNodeHost, type NodeHostOptions } from './node-host'
-/** The pages the standalone shell opens in this phase: the rest need the Claude Code host's panes, prompt or dialogs. */
-export const TUI_VIEWS = ['overview', 'cost'] as const satisfies readonly ViewId[]
+/**
+ * The pages the standalone shell opens: Overview and Cost, then Swarm, Events and Missions (ADR-489 decision C). Room is left out on purpose:
+ * its content is what people said to Claude in a session and a message box, neither of which this host has, so it could only draw empty cards.
+ */
+export const TUI_VIEWS = ['overview', 'cost', 'swarm', 'events', 'missions'] as const satisfies readonly ViewId[]
export type TuiView = (typeof TUI_VIEWS)[number]
export type Session = {
@@ -30,6 +35,7 @@ export function openSession(options: NodeHostOptions, host: Host = createNodeHos
state.cwd = options.cwd
state.isInteractive = true
+ state.isStandalone = true
// The controller draws and probes only for a pane that is open and shown; here the whole terminal is that pane.
state.pane.isOpen = true
state.pane.isShown = true
@@ -59,7 +65,7 @@ export function openSession(options: NodeHostOptions, host: Host = createNodeHos
},
frame: (columns, depth) => {
state.pane.columns = columns
- const tree = paneView({ kit: terminalKit(), state, nowMs: Date.now(), columns, pictures: new Map(), act: controller.actions })
+ const tree = standalonePane({ kit: terminalKit(), state, nowMs: Date.now(), columns, pictures: new Map(), act: controller.actions }, BODIES[state.view])
return render(tree, columns, depth)
},
diff --git a/v3/@claude-flow/cli/__tests__/tui-command.test.ts b/v3/@claude-flow/cli/__tests__/tui-command.test.ts
index 4691544c3f..d58bf3fb7c 100644
--- a/v3/@claude-flow/cli/__tests__/tui-command.test.ts
+++ b/v3/@claude-flow/cli/__tests__/tui-command.test.ts
@@ -64,6 +64,26 @@ describe('tui command', () => {
expect(result).toMatchObject({ success: false, exitCode: 1 });
});
+ it.skipIf(locateTuiBundle() === null)('opens each of the five pages with --plain, and refuses Room and anything else with exit 2 (real bundle)', async () => {
+ for (const view of ['overview', 'cost', 'swarm', 'events', 'missions']) {
+ 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;
+ try {
+ const result = await tuiCommand.action!({ args: [], flags: { view, plain: true }, cwd: tmp() } as never);
+
+ expect(result, view).toMatchObject({ success: true, exitCode: 0 });
+ } finally {
+ process.stdout.write = real;
+ }
+ expect(lines.join(''), view).toContain('1 Overview');
+ }
+
+ for (const view of ['room', 'nope']) {
+ expect(await tuiCommand.action!({ args: [], flags: { view, plain: true }, cwd: tmp() } as never), view).toMatchObject({ success: false, exitCode: 2 });
+ }
+ });
+
it('declares --plain as a boolean option and lists it in the examples', () => {
expect(tuiCommand.options?.find(option => option.name === 'plain')).toMatchObject({ type: 'boolean', default: false });
expect(tuiCommand.examples?.some(example => example.command.includes('--plain'))).toBe(true);
diff --git a/v3/@claude-flow/cli/src/commands/tui.ts b/v3/@claude-flow/cli/src/commands/tui.ts
index 373539f7f0..c31a6cc41d 100644
--- a/v3/@claude-flow/cli/src/commands/tui.ts
+++ b/v3/@claude-flow/cli/src/commands/tui.ts
@@ -2,13 +2,13 @@
* `ruflo tui` — the ruflo console in a terminal of its own (ADR-489).
*
* Runs the same views the Claude Code mod (plugins/ruflo-console) draws, over a Node host instead of the mod host. Read-only in
- * this phase: Overview and Cost. The bundle is built from the plugin's source (scripts/build-tui.mjs) and loaded from this
+ * this phase: Overview, Cost, Swarm, Events and Missions (keys 1-5). The bundle is built from the plugin's source (scripts/build-tui.mjs) and loaded from this
* CLI's OWN install only (never from the working directory: opening a repository must not run code that repository supplies).
* No bundle is a message and exit 1, never a crash; ruflo stays operational without it. Without a terminal (a pipe, CI) the live view cannot run:
* a one-line hint and exit 2, unless --plain asks for one frame as plain text and exit 0 (ADR-489 decision E).
*
* npx ruflo tui # interactive, in a terminal
- * npx ruflo tui --view cost # start on the Cost page
+ * npx ruflo tui --view swarm # start on the Swarm page (keys 1-5 or o c s e m switch pages)
* npx ruflo tui --plain | head # one plain frame, exit 0 (scripts, CI)
* npx ruflo tui | cat # not a terminal and no --plain: a hint on stderr, exit 2
*/
@@ -22,7 +22,7 @@ import { ownPluginDirs } from '../plugins/own-install.js';
const __dirname = dirname(fileURLToPath(import.meta.url));
-const VIEWS = ['overview', 'cost'] as const;
+const VIEWS = ['overview', 'cost', 'swarm', 'events', 'missions'] as const;
type TuiModule = { runTui: (options: Record<string, unknown>, io: Record<string, unknown>) => Promise<number>; isTuiView: (value: unknown) => boolean };
@@ -43,14 +43,14 @@ function cliEntry(): string | undefined {
export const tuiCommand: Command = {
name: 'tui',
- description: 'The ruflo console in your terminal (Overview and Cost, read-only). Same views as the Claude Code mod.',
+ description: 'The ruflo console in your terminal (Overview, Cost, Swarm, Events, Missions; read-only). Same views as the Claude Code mod.',
options: [
{ name: 'view', description: `Page to open: ${VIEWS.join(' | ')}`, type: 'string' as const, default: 'overview' },
{ 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 },
],
examples: [
{ command: 'npx ruflo tui', description: 'Open the console in this terminal' },
- { command: 'npx ruflo tui --view cost', description: 'Start on the Cost page' },
+ { command: 'npx ruflo tui --view swarm', description: 'Start on the Swarm page (keys 1-5 switch pages, tab cycles, q quits)' },
{ command: 'npx ruflo tui --plain | head -40', description: 'One plain frame, exit 0: for scripts and CI (no terminal needed)' },
],
async action(context: CommandContext): Promise<CommandResult> {
diff --git a/v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md b/v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md
index cb3862bc31..3e0ff7e679 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; phases 2 to 4 are a roadmap that 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 1 of the continuation; phases 3 and 4 are a roadmap that must follow those decisions.
Date: 2026-10-11
@@ -151,14 +151,14 @@ not a replacement and not a second implementation.
1. **Phase 1 (PR #4059): the vertical slice.** `ruflo tui [--view overview|cost] [--plain]`; alternate screen, keys `o c Tab r j k PgUp PgDn g G q`, auto-refresh every 3 s; `--plain` prints one plain frame and exits 0, and without a terminal and without `--plain` it prints a one-line hint and exits 2 (decision E); read-only; the boundary and security tests; ADR.
1b. **Publish wiring (done in PR #4059, decisions A and B).** `prepare-publish.mjs` builds and stages the bundle and `esbuild` is a declared devDependency. Still to do: a CI job that runs `ruflo tui --plain` from the packed tarball.
-2. **Host capabilities and more pages.** `Host.capabilities` so chrome and rows that need Claude Code are hidden, not drawn inert; pages in the accepted order (decision C): Swarm, then Events, then Missions, then Room, all read-only; Raster to half-block cells; Windows and tmux verification; `NO_COLOR` and width (CJK, emoji) handling.
+2. **Host capabilities and more pages (done).** `state.isStandalone` is the capability flag: the shared chrome and the Claude-only rows are not drawn on this host (no tab bar, footer buttons, Launch section, Ask Claude, Claude control card; a button that cannot be pressed is not drawn, a state chip and a section title are). Pages in the accepted order (decision C): Overview, Cost, **Swarm, Events, Missions**, all read-only; keys `1`-`5`, `o c s e m`, Tab and Shift-Tab, a page bar, a key line that shortens with the width, a clear-and-redraw on resize, a position bar under 60 columns and a one-line notice under 40. **Room is not shipped, on purpose:** its content is what people said to Claude in a session plus a message box, neither of which this host has, so it could only draw empty cards; it comes back if a host source for it exists. Missions shows the ADR-406 mission record only (goal entry, planning and research start a Claude turn). Still open: Raster to half-block cells, Windows verification, CJK and emoji width beyond the table in `ansi.ts`.
3. **Drive Codex and OpenRouter** (3.5) behind the confirm gate, with #3983's tests ported; the AI terminal page; per-provider spend read from the CLIs' own reports and the ledger.
4. **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.
## 5. Risks
- **Cell width.** Width is counted in terminal cells with a small table (CJK, fullwidth, the emoji blocks, combining marks); a symbol the table does not list, or a terminal that draws an emoji at another width, can still shift a border. Tested for the emoji the pane header uses.
-- **Chrome that lies.** Inert Claude-only controls are visible until phase 2. They are dimmed and the footer says read-only; still a rough edge.
+- **Chrome that lies (closed in phase 2).** The Claude-only controls are no longer drawn. Residual: some page text still names a button (a hint such as "open Memory"), because the view's words are shared with Claude Code.
- **Drift.** A new view may import something engine-specific. Mitigation: `tui-boundary.spec.ts` (imports) and a headless smoke over the pages the TUI opens.
- **Bundle size.** 437 KiB gzip for a feature many will not use. It loads lazily, only for `tui`. Dropping the unused pages from the bundle (tree-shaking by an explicit page list) is a phase 2 option.
- **A second place to sanitise.** The engine's escape handling is not inherited. `clean` is one function with a test; any new drawing path must go through `render`.