🌊 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(cli,console): ruflo tui --plain, exit 2 without a terminal, bundle staged for publish, esbuild declared (ADR-489 A-E)
r11cc8cd648f5
diff --git a/package-lock.json b/package-lock.jsonindex 2f188d0e07..fc03ea8507 100644--- a/package-lock.json+++ b/package-lock.json@@ -55,6 +55,7 @@"@openai/codex": "^0.98.0","@types/bcrypt": "^5.0.2","@types/node": "^20.0.0",+ "esbuild": "^0.27.2","eslint": "^8.0.0","tsx": "^4.21.0","typescript": "^5.0.0",diff --git a/package.json b/package.jsonindex e6df58f38f..5afad42273 100644--- a/package.json+++ b/package.json@@ -152,6 +152,7 @@"@openai/codex": "^0.98.0","@types/bcrypt": "^5.0.2","@types/node": "^20.0.0",+ "esbuild": "^0.27.2","eslint": "^8.0.0","tsx": "^4.21.0","typescript": "^5.0.0",diff --git a/plugins/ruflo-console/README.md b/plugins/ruflo-console/README.mdindex 7da4c9b91f..3bd0c1cbcd 100644--- a/plugins/ruflo-console/README.md+++ b/plugins/ruflo-console/README.md@@ -45,6 +45,19 @@ CONSOLE_DRIVE_INSTALL="$PWD:ruflo-mods@ruflo" RUFLO_E2E_LIVE=1 bash plugins/rufl- **Missions, loops, swarms.** Attach ADRs to the active mission (the page suggests some from the goal's words; you decide). Claude's mission context, each task's instruction and spawned swarm agents (ruflo-swarm 0.3.5) are told the accepted decisions, masked and capped. At *verify*, changed files are compared with the paths the attached accepted ADRs name: a warning in the mission record. **That compares paths only. It does not prove a change follows or breaks a decision, and it never blocks.** When a mission is done, *draft an ADR from this mission* prepares a proposed record from its goal and tasks; the decision is yours to write.- **For Claude.** `/ruflo run adr-propose <title>`, `adr-accept <n>`, `adr-supersede <old> <new>`, `adr-attach <n>` and the rest are palette entries, so Claude reaches them through `console_run` at the *write* control level (reading the page is *read*); a change still waits for your Yes on the diff.+## 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).++```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 --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).+## Toasts (ADR-477)Settings → Interface and updates → **Toasts** sets what the ruflo plugins may show over the transcript: `all`, `important` (warnings and errors) or `off`, with a mute chip each for `console`, `swarm`, `protector` and `mods`. It is kept in the console's store and mirrored to `.claude-flow/console/toast-prefs.json`, which the other plugins read. Every toast, drawn or not, becomes an event on the Events page (`toast <source> <glyph> <text> [off|muted|deduped|…]`); the other plugins' digests are read from `.claude-flow/console/toasts/<source>.jsonl`, masked and capped. The console itself also toasts a mission that finishes (`ok`) or loses a task (`error`), and its update notes by level. Design and contract: [ADR-477](../../v3/docs/adr/ADR-477-mod-toasts.md).diff --git a/plugins/ruflo-console/tests/tui-session.spec.ts b/plugins/ruflo-console/tests/tui-session.spec.tsindex 64848189af..82f766426a 100644--- a/plugins/ruflo-console/tests/tui-session.spec.ts+++ b/plugins/ruflo-console/tests/tui-session.spec.ts@@ -8,7 +8,7 @@ import { tmpdir } from 'node:os'import { dirname, join } from 'node:path'import { afterAll, beforeAll, describe, expect, it } from 'vitest'-import { depthOf, keyOf, runTui, type TuiIO } from '../tui/run'+import { depthOf, keyOf, NOT_A_TERMINAL_HINT, runTui, type TuiIO } from '../tui/run'import { openSession } from '../tui/session'import { RUFLO_FILES } from './fixtures/ruflo-run'@@ -136,22 +136,52 @@ describe('the same views over real ruflo files', () => {})describe('headless', () => {- it('prints one plain frame to stdout, a note to stderr, and returns 0', async () => {+ it('--plain prints one plain frame to stdout, nothing to stderr, and returns 0', async () => {const { io, out, err } = fakeIO(false)- const code = await runTui({ cwd: project, home: join(root, 'home') }, io)+ const code = await runTui({ cwd: project, home: join(root, 'home'), plain: true }, io)expect(code).toBe(0)expect(out.join('')).toContain('swarm-1790903031804-y9rnjr')expect(out.join('')).not.toContain(ESC)- expect(err.join('')).toMatch(/not an interactive terminal/)+ expect(err.join('')).toBe('')})- it('opens the page asked for', async () => {+ it('--plain opens the page asked for', async () => {const { io, out } = fakeIO(false)- await runTui({ cwd: project, home: join(root, 'home'), view: 'cost' }, io)+ await runTui({ cwd: project, home: join(root, 'home'), view: 'cost', plain: true }, io)expect(out.join('')).toContain('Where it goes')})++ it('--plain in a real terminal still prints one frame and never enters the alternate screen or raw mode', async () => {+ const { io, out, raw } = fakeIO(true)+ const code = await runTui({ cwd: project, home: join(root, 'home'), plain: true }, io)++ expect(code).toBe(0)+ expect(out.join('')).toContain('swarm-1790903031804-y9rnjr')+ expect(out.join('')).not.toContain(ESC)+ expect(raw).toEqual([])+ })++ it('without a terminal and without --plain prints a one-line hint to stderr and returns 2, with nothing on stdout', async () => {+ const { io, out, err } = fakeIO(false)+ const code = await runTui({ cwd: project, home: join(root, 'home') }, io)++ expect(code).toBe(2)+ expect(out).toEqual([])+ expect(err.join('')).toBe(NOT_A_TERMINAL_HINT)+ expect(NOT_A_TERMINAL_HINT.trimEnd().split('\n')).toHaveLength(1)+ expect(NOT_A_TERMINAL_HINT).toMatch(/--plain/)+ })++ it('a terminal that cannot do raw mode counts as no terminal', async () => {+ const { io, out, err } = fakeIO(true)+ const code = await runTui({ cwd: project, home: join(root, 'home') }, { ...io, stdin: { ...io.stdin, setRawMode: undefined } })++ expect(code).toBe(2)+ expect(out).toEqual([])+ expect(err.join('')).toBe(NOT_A_TERMINAL_HINT)+ })})describe('interactive', () => {diff --git a/plugins/ruflo-console/tui/run.ts b/plugins/ruflo-console/tui/run.tsindex 48021cdfbf..bd26c0153a 100644--- a/plugins/ruflo-console/tui/run.ts+++ b/plugins/ruflo-console/tui/run.ts@@ -23,7 +23,7 @@ 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; cliEntry?: string; configDir?: string; home?: string; pluginRoot?: string; refreshMs?: number }+export type TuiOptions = { cwd: string; view?: TuiView; plain?: boolean; cliEntry?: string; configDir?: string; home?: string; pluginRoot?: string; refreshMs?: number }export const isTuiView = (value: unknown): value is TuiView => typeof value === 'string' && (TUI_VIEWS as readonly string[]).includes(value)@@ -98,22 +98,32 @@ function paint(session: Session, io: TuiIO, depth: Depth, scroll: number): numbereturn top}-/** Headless: one frame as plain text on stdout (the same views, read-only), a note on stderr. Returns the exit code. */+/** `--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> {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`)- io.stderr.write('ruflo tui: not an interactive terminal, so one plain frame was printed. Run it in a terminal for the live view.\n')return 0}+/** Without a terminal and without `--plain` the live view cannot run: say so in one line and exit 2 (a usage error), so a script notices instead of reading a silent frame. */+export const NOT_A_TERMINAL_HINT = 'ruflo tui: not an interactive terminal. Run it in a terminal, or pass --plain to print one frame and exit 0.\n'+export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {+ const interactive = io.stdin.isTTY === true && io.stdout.isTTY === true && io.stdin.setRawMode !== undefined++ if (options.plain !== true && !interactive) {+ io.stderr.write(NOT_A_TERMINAL_HINT)++ return 2+ }+const session = openSession({ cwd: options.cwd, ...(options.cliEntry !== undefined && { cliEntry: options.cliEntry }), ...(options.configDir !== undefined && { configDir: options.configDir }), ...(options.home !== undefined && { home: options.home }), ...(options.pluginRoot !== undefined && { pluginRoot: options.pluginRoot }) })let view: TuiView = options.view ?? 'overview'try {- if (io.stdin.isTTY !== true || io.stdout.isTTY !== true || io.stdin.setRawMode === undefined) return await once(session, io, view)+ if (options.plain === true || !interactive || io.stdin.setRawMode === undefined) return await once(session, io, view)const depth = depthOf(io.env)let scroll = 0diff --git a/v3/@claude-flow/cli/__tests__/tui-command.test.ts b/v3/@claude-flow/cli/__tests__/tui-command.test.tsindex 24178f970c..4691544c3f 100644--- a/v3/@claude-flow/cli/__tests__/tui-command.test.ts+++ b/v3/@claude-flow/cli/__tests__/tui-command.test.ts@@ -64,12 +64,17 @@ describe('tui command', () => {expect(result).toMatchObject({ success: false, exitCode: 1 });});- it.skipIf(locateTuiBundle() === null)('prints one plain frame headless and exits 0 (real bundle)', async () => {+ 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);+ });++ it.skipIf(locateTuiBundle() === null)('--plain prints one plain frame to stdout and exits 0 (real bundle)', async () => {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: 'overview' }, cwd: tmp() } as never);+ const result = await tuiCommand.action!({ args: [], flags: { view: 'overview', plain: true }, cwd: tmp() } as never);expect(result).toMatchObject({ success: true, exitCode: 0 });} finally {@@ -78,4 +83,24 @@ describe('tui command', () => {expect(lines.join('')).toContain('what ruflo is doing here');expect(existsSync(locateTuiBundle()!)).toBe(true);});++ // Needs a non-terminal stdin and stdout, which is what a test runner has; skipped when someone runs the suite from a real terminal.+ it.skipIf(locateTuiBundle() === null || process.stdin.isTTY === true || process.stdout.isTTY === true)('without a terminal and without --plain prints a hint on stderr, nothing on stdout, and exits 2 (real bundle)', async () => {+ const out: string[] = [];+ const errs: string[] = [];+ const realOut = process.stdout.write.bind(process.stdout);+ const realErr = process.stderr.write.bind(process.stderr);+ process.stdout.write = ((chunk: string | Uint8Array) => (out.push(String(chunk)), true)) as typeof process.stdout.write;+ process.stderr.write = ((chunk: string | Uint8Array) => (errs.push(String(chunk)), true)) as typeof process.stderr.write;+ try {+ const result = await tuiCommand.action!({ args: [], flags: { view: 'overview' }, cwd: tmp() } as never);++ expect(result).toMatchObject({ success: false, exitCode: 2 });+ } finally {+ process.stdout.write = realOut;+ process.stderr.write = realErr;+ }+ expect(out.join('')).toBe('');+ expect(errs.join('')).toMatch(/not an interactive terminal.*--plain/s);+ });});diff --git a/v3/@claude-flow/cli/scripts/prepare-publish.mjs b/v3/@claude-flow/cli/scripts/prepare-publish.mjsindex 1036ab0617..c76967b023 100644--- a/v3/@claude-flow/cli/scripts/prepare-publish.mjs+++ b/v3/@claude-flow/cli/scripts/prepare-publish.mjs@@ -39,6 +39,21 @@ await cp({ recursive: true },);+// ADR-489: `ruflo tui` loads one bundled file from the CLI's own install+// (plugins/ruflo-console/dist/tui.mjs, see src/commands/tui.ts). Build it from+// the plugin's source with the repo's esbuild and stage only that file, so the+// registry install runs the console and the tarball carries no console source.+const tuiBundle = join(pluginsDir, 'ruflo-console', 'dist', 'tui.mjs');+const tuiBuild = spawnSync(+ process.execPath,+ [join(repoRoot, 'plugins', 'ruflo-console', 'scripts', 'build-tui.mjs'), '--outfile', tuiBundle],+ { cwd: repoRoot, stdio: 'inherit' },+);+if (tuiBuild.error) throw tuiBuild.error;+if (tuiBuild.status !== 0) {+ throw new Error(`build-tui.mjs failed with exit code ${tuiBuild.status ?? 'unknown'}`);+}+for (const script of ['generate-catalog-manifest.mjs','sign-helpers.mjs',diff --git a/v3/@claude-flow/cli/src/commands/tui.ts b/v3/@claude-flow/cli/src/commands/tui.tsindex 318e95a399..373539f7f0 100644--- a/v3/@claude-flow/cli/src/commands/tui.ts+++ b/v3/@claude-flow/cli/src/commands/tui.ts@@ -4,11 +4,13 @@* 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* CLI's OWN install only (never from the working directory: opening a repository must not run code that repository supplies).- * No bundle, or no terminal, is a message and a clean exit, never a crash; ruflo stays operational without it.+ * 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 | cat # not a terminal: one plain frame, then exit+ * 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*/import { existsSync } from 'node:fs';import { dirname, join } from 'node:path';@@ -42,10 +44,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.',- options: [{ name: 'view', description: `Page to open: ${VIEWS.join(' | ')}`, type: 'string' as const, default: 'overview' }],+ 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 --plain | head -40', description: 'One plain frame, exit 0: for scripts and CI (no terminal needed)' },],async action(context: CommandContext): Promise<CommandResult> {const ctx = context as { args?: string[]; flags?: Record<string, unknown>; cwd?: string };@@ -78,7 +84,7 @@ export const tuiCommand: Command = {try {const code = await mod.runTui(- { cwd: ctx.cwd ?? process.cwd(), view: wanted, ...(cliEntry() !== undefined && { cliEntry: cliEntry() }), ...(process.env.CLAUDE_CONFIG_DIR !== undefined && { configDir: process.env.CLAUDE_CONFIG_DIR }) },+ { cwd: ctx.cwd ?? process.cwd(), view: wanted, ...(ctx.flags?.plain === true && { plain: true }), ...(cliEntry() !== undefined && { cliEntry: cliEntry() }), ...(process.env.CLAUDE_CONFIG_DIR !== undefined && { configDir: process.env.CLAUDE_CONFIG_DIR }) },{ stdin: process.stdin, stdout: process.stdout, stderr: process.stderr, env: process.env, signal: stop.signal },);return { success: code === 0, exitCode: code };diff --git a/v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md b/v3/docs/adr/ADR-489-ruflo-tui-standalone-console.mdindex 647b8df7db..cb3862bc31 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: Proposed (phase 1, a read-only Overview and Cost, is implemented in the draft PR that adds this file; phases 2 to 4 are a roadmap)+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.Date: 2026-10-11@@ -32,75 +32,7 @@ Static check over all 343 `.ts` files under `hooks/` (comments stripped; the rul|---|---|---|---|| host-neutral | no engine call, no Node module, no package; reads files through `Host.fs`, runs the ruflo CLI through `Host.run` | **315** | top level 97, `data/` 103, `views/` 98, `gfx/` 17 || host-engine-dependent | calls a `Host` member only the Claude Code host can answer (panes, `blit`, prompt box, `toolCall`, `rufloSnapshot`, dialogs, toasts) | **26** | top level 23, `views/` 3 (`wf-control`, `wf-guide`, `wf-templates`) |-| Claude-Code-only | touches `# ADR 489: `ruflo tui`: the console in a terminal of its own, over the same views--Status: Proposed (phase 1, a read-only Overview and Cost, is implemented in the draft PR that adds this file; phases 2 to 4 are a roadmap)--Date: 2026-10-11--Builds on: ADR-407 (the cockpit), ADR-446 (plugin mods), ADR-448 (the Room), ADR-481 (one sanitiser for drawn text), ADR-486 (session workspace), ADR-150 (plugin skills dispatched by the CLI, with graceful degradation), ADR-437 (multi-provider cost ledger). Security inputs: #3983 (every confirm route bound to the card the person saw), #3981 (no transcript text or path in a model-facing answer).--Numbering: 488 is the highest on `main` and no open pull request names 489 (checked 2026-10-11 before committing). ADR-487 exists twice, so check again at merge.--## 1. Context--rUv's goal: a TUI for ruflo, part of `npx ruflo`, that reuses the ruflo-console components and works both on its own and as the mod inside Claude Code-(ruflo-mods). A standalone host should eventually drive Codex and OpenRouter. The agreed starting point was a **thin shell first**: a `ruflo tui` entry-that embeds the existing views, Codex and OpenRouter through their own CLI or API, Claude Code staying a supported host, and not a new agent harness.--This ADR records what the code showed, the decision, and the first slice. Every number below was measured on `main` at 72255a2f4 unless it says otherwise.--## 2. Findings (evidence)--### 2.1 The host boundary already exists--`plugins/ruflo-console/hooks/host.ts` defines `Host`, "the engine as `session.start` bound it": 31 required members and 3 optional ones (`fs`, `run`, `spawn`,-`every`, `after`, `storeGet/Set`, `openPane`, `blit`, `toolCall`, `rufloSnapshot`, `httpSend` …). Its contract says any member may be refused and a refusal is-a missing fact, never a crash. `register.ts` `hostOf($, …)` is the one place that spells `$.noun.method(...)`: the Claude Code adapter. The controller-(`createController(state, host)`), every view (`(ctx) => RenderElement`, built only from `ctx.kit.Box|Text|Button`, optional `Raster|Input`) and the page-(`paneView`) are plain functions over that interface.--Static check over all 343 `.ts` files under `hooks/` (comments stripped; the rules are asserted by `tests/tui-boundary.spec.ts`):--| class | meaning | files | where |-|---|---|---|---|-| host-neutral | no engine call, no Node module, no package; reads files through `Host.fs`, runs the ruflo CLI through `Host.run` | **315** | top level 97, `data/` 103, `views/` 98, `gfx/` 17 |-| host-engine-dependent | calls a `Host` member only the Claude Code host can answer (panes, `blit`, prompt box, `toolCall`, `rufloSnapshot`, dialogs, toasts) | **26** | top level 23, `views/` 3 (`wf-control`, `wf-guide`, `wf-templates`) |- or `on(...)` directly | **2** | `register.ts` (the one file that binds `# ADR 489: `ruflo tui`: the console in a terminal of its own, over the same views--Status: Proposed (phase 1, a read-only Overview and Cost, is implemented in the draft PR that adds this file; phases 2 to 4 are a roadmap)--Date: 2026-10-11--Builds on: ADR-407 (the cockpit), ADR-446 (plugin mods), ADR-448 (the Room), ADR-481 (one sanitiser for drawn text), ADR-486 (session workspace), ADR-150 (plugin skills dispatched by the CLI, with graceful degradation), ADR-437 (multi-provider cost ledger). Security inputs: #3983 (every confirm route bound to the card the person saw), #3981 (no transcript text or path in a model-facing answer).--Numbering: 488 is the highest on `main` and no open pull request names 489 (checked 2026-10-11 before committing). ADR-487 exists twice, so check again at merge.--## 1. Context--rUv's goal: a TUI for ruflo, part of `npx ruflo`, that reuses the ruflo-console components and works both on its own and as the mod inside Claude Code-(ruflo-mods). A standalone host should eventually drive Codex and OpenRouter. The agreed starting point was a **thin shell first**: a `ruflo tui` entry-that embeds the existing views, Codex and OpenRouter through their own CLI or API, Claude Code staying a supported host, and not a new agent harness.--This ADR records what the code showed, the decision, and the first slice. Every number below was measured on `main` at 72255a2f4 unless it says otherwise.--## 2. Findings (evidence)--### 2.1 The host boundary already exists--`plugins/ruflo-console/hooks/host.ts` defines `Host`, "the engine as `session.start` bound it": 31 required members and 3 optional ones (`fs`, `run`, `spawn`,-`every`, `after`, `storeGet/Set`, `openPane`, `blit`, `toolCall`, `rufloSnapshot`, `httpSend` …). Its contract says any member may be refused and a refusal is-a missing fact, never a crash. `register.ts` `hostOf($, …)` is the one place that spells `$.noun.method(...)`: the Claude Code adapter. The controller-(`createController(state, host)`), every view (`(ctx) => RenderElement`, built only from `ctx.kit.Box|Text|Button`, optional `Raster|Input`) and the page-(`paneView`) are plain functions over that interface.--Static check over all 343 `.ts` files under `hooks/` (comments stripped; the rules are asserted by `tests/tui-boundary.spec.ts`):--| class | meaning | files | where |-|---|---|---|---|-| host-neutral | no engine call, no Node module, no package; reads files through `Host.fs`, runs the ruflo CLI through `Host.run` | **315** | top level 97, `data/` 103, `views/` 98, `gfx/` 17 |-| host-engine-dependent | calls a `Host` member only the Claude Code host can answer (panes, `blit`, prompt box, `toolCall`, `rufloSnapshot`, dialogs, toasts) | **26** | top level 23, `views/` 3 (`wf-control`, `wf-guide`, `wf-templates`) |-), `model-tools.ts` (the model-facing `console_*` tool server over `on`; it also exports helpers such as `modelLine` that the controller imports, so it is in the standalone bundle but its server is never started: only `register.ts` calls it, asserted by the boundary test) |+| Claude-Code-only | touches `$` or `on(...)` directly | **2** | `register.ts` (the one file that binds `$`), `model-tools.ts` (the model-facing `console_*` tool server over `on`; it also exports helpers such as `modelLine` that the controller imports, so it is in the standalone bundle but its server is never started: only `register.ts` calls it, asserted by the boundary test) |95 files import `claude-code`, all as types; no file imports a Node module or a package. The "about 113 files" in the question is thetop level of `hooks/` (122 `.ts` files: 97 host-neutral, 23 engine-dependent, 2 engine-only); the whole folder has 343. "Host-neutral" is a statement about imports, not about usefulness: many neutral views@@ -166,10 +98,12 @@ member and shows `n/a` where it is absent. No view forks per host.Nothing is copied or forked; `tui/` imports `../hooks/*` by relative path.- `plugins/ruflo-console/scripts/build-tui.mjs` bundles `tui/main.ts` to `plugins/ruflo-console/dist/tui.mjs` (gitignored).- `@claude-flow/cli` gains `src/commands/tui.ts`: it finds `plugins/ruflo-console/dist/tui.mjs` in its own install (`ownPluginDirs`, never the working directory),- imports it, and calls `runTui`. No bundle is a message and exit 1; no terminal is one plain frame and exit 0. Ruflo works without it.-- Publishing: `scripts/prepare-publish.mjs` must run the build and copy `plugins/ruflo-console/dist` into `plugins/ruflo-console/` of the CLI tarball, as it- does for `ruflo-metaharness`. **This PR does not change the publish path** (it cannot be exercised without a release); until it does, `npx ruflo tui` reports the- bundle as missing on a registry install and works from a checkout after `node plugins/ruflo-console/scripts/build-tui.mjs`. See decision B.+ imports it, and calls `runTui`. No bundle is a message and exit 1. With no terminal, `--plain` prints one plain frame and exits 0; without `--plain` it prints a one-line hint and exits 2 (decision E). Ruflo works without it.+- Publishing (decisions A and B, done in PR #4059): `v3/@claude-flow/cli/scripts/prepare-publish.mjs` runs `plugins/ruflo-console/scripts/build-tui.mjs` with `--outfile`+ into `plugins/ruflo-console/dist/tui.mjs` of the CLI tarball, next to `ruflo-metaharness`, and stages only that one file (no console source ships). `esbuild` is a+ declared root devDependency (`^0.27.2`, already locked at 0.27.2). The `ruflo` wrapper depends on `@claude-flow/cli`, so it carries the bundle. The `claude-flow`+ umbrella ships the CLI's `dist` but not its `plugins/` directory (it does not ship `ruflo-metaharness` either), so `npx claude-flow tui` reports the bundle as missing; use `ruflo` or `@claude-flow/cli`.+ Measured on a real pack: the bundle is 1,278,143 bytes (1248 KiB; 447,965 bytes gzip); the CLI tarball grows from 2,762,840 to 3,212,185 bytes (+449,345 bytes, +1 file).- This is not a new npm package and not one of the four bundled leaves: no `@claude-flow/*` version, pin or standalone publish changes. The CLI's "bundledversus standalone leaves" rule is untouched; the cost is the +437 KiB gzip tarball weight in phase 1b.@@ -200,7 +134,13 @@ The console already has an AI terminal (`harness.ts`) that asks `codex`, `claudeendpoints through `Host.httpSend` with the key named by `keyEnv` (`OPENROUTER_API_KEY`; `convoTargets`, `data/wf-targets.ts`), plus the multi-provider cost ledger (ADR-437). Thestandalone host reuses all of it by **implementing `spawn` and `httpSend`**, not by writing a harness: `spawn` for an allowlist of binaries (`codex`, `claude`) in aread-only sandbox mode by default, `httpSend` for the configured hosts only with the key read from the environment at call time and never stored, logged or drawn.-Both stay refused in phase 1.+Both stay refused in phase 1. The accepted constraints for phase 3 (decision D) are:++- **Codex**: runs in the **read-only sandbox by default**, through the pinned-by-path binary and never the 0.162.1 build (it crashes with a #GP; the `current` links are not touched). Workspace-write is an **explicit per-session opt-in**.+ There is **no `danger-full-access` path in the TUI**: no flag, option or environment variable reaches it.+- **OpenRouter**: `httpSend` may reach only `https://openrouter.ai` plus the hosts named in `convoTargets`; **https only, no redirect to another host**. Keys are referenced **by environment variable+ name only** and are never rendered, logged or stored. Model output is **sanitised through `ansi.ts` `clean` before it is drawn**.+- **Writes**: any write action requires the confirm-gate binding from #3983 (a card shown to the person, answered by its id).### 3.6 Claude Code remains a first-class host@@ -209,9 +149,9 @@ not a replacement and not a second implementation.## 4. Phases-1. **Phase 1 (this PR, draft): the vertical slice.** `ruflo tui [--view overview|cost]`; alternate screen, keys `o c Tab r j k PgUp PgDn g G q`, auto-refresh every 3 s; headless prints one plain frame after the CLI's own startup lines; read-only; the boundary and security tests; ADR.-1b. **Publish wiring.** `prepare-publish.mjs` builds and stages the bundle; a CI job runs `ruflo tui` headless from the packed tarball; decide on `esbuild` as a declared devDependency.-2. **Host capabilities and more pages.** `Host.capabilities` so chrome and rows that need Claude Code are hidden, not drawn inert; Swarm, Room, Events, Missions read-only; Raster to half-block cells; Windows and tmux verification; `NO_COLOR` and width (CJK, emoji) handling.+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.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.@@ -237,12 +177,23 @@ all passing; `tsc -p plugins/ruflo-console` reports no error in `tui/` or the nereal CLI version (`v3.56.5`), the real swarm id, daemon state and helpers manifest; the pty run entered the alternate screen once, switched to Cost on `c`, scrolled on `j`, quit on `q`, left raw mode and thealternate screen, exit 0.-**Unverified:** Node 20 (the declared floor; the bundle targets it but only 22 was run), macOS Terminal, iTerm2, kitty, Windows Terminal and conhost (raw mode and SGR), tmux/screen colour depth, a terminal narrower than 40 columns, `npx ruflo tui` from a registry install (the bundle is not staged by `prepare-publish.mjs` yet), and every page other than Overview and Cost.-## 8. Decisions for the owner+Added with decisions A, B and E (2026-10-11, Linux, Node 22.23.2): 43 vitest tests in `plugins/ruflo-console/tests/tui-{host,render,session,boundary}.spec.ts` (the headless group now covers `--plain`, `--plain` in a terminal,+no terminal without `--plain`, and a terminal without raw mode) and 8 in `__tests__/tui-command.test.ts`, all passing. Through the real CLI: `ruflo tui --plain | head` printed the frame, exit 0, nothing from the TUI on stderr;+`ruflo tui | head` and `ruflo tui </dev/null` printed the one-line hint on stderr, nothing on stdout, exit 2. A pty sized 45x120 entered the alternate screen once, showed Overview, switched to Cost on `c`, left the alternate screen once on `q`, exit 0.+`npm pack` of the CLI contains `package/plugins/ruflo-console/dist/tui.mjs` and `package/dist/src/commands/tui.js`; a throwaway `npm install` of that tarball added 615 packages in 8 s and `node node_modules/@claude-flow/cli/bin/cli.js tui` drew the Overview. `npm ci --dry-run` is clean with `esbuild` declared.++**Unverified:** Node 20 (the declared floor; the bundle targets it but only 22 was run), macOS Terminal, iTerm2, kitty, Windows Terminal and conhost (raw mode and SGR), tmux/screen colour depth, a terminal narrower than 40 columns, `npx ruflo tui` from a *published* registry package (the staging step and a throwaway install of the packed tarball were exercised, section 7, but nothing has been published), and every page other than Overview and Cost.++## 8. Decisions (Accepted 2026-10-11)++The owner delegated these to be optimised and recorded; each is **Accepted**. A, B and E are implemented in PR #4059. C and D are documented decisions that bind phases 2 and 3; no phase 2 or 3 code is in that PR.-- **A.** Declare `esbuild` as a root devDependency (build-time only, changes `package-lock.json`)? Today it resolves only because another tool pulls it in.-- **B.** Wire the bundle into `prepare-publish.mjs` now (adds ~437 KiB gzip to the CLI tarball and a build step to the release) or hold until phase 2 makes the page set worth it?-- **C.** Which pages are in the standalone shell after Overview and Cost: Swarm, Room, Events, Missions? Each is read-only first.-- **D.** For Codex and OpenRouter: is read-only sandboxing by default the right default, and may `httpSend` reach only `openrouter.ai` plus hosts named in `convoTargets`?-- **E.** Exit code when `tui` is not in a terminal: it prints one frame and exits 0 so pipes and CI do not fail; say if a non-zero exit is preferred.+- **A. Accepted, done.** `esbuild` is a root devDependency (`^0.27.2`, build-time only; `package-lock.json` changed by one line, proven with `npm ci --dry-run`).+- **B. Accepted, done.** `prepare-publish.mjs` builds and stages `plugins/ruflo-console/dist/tui.mjs` into the CLI tarball now (+449,345 bytes gzip-packed, measured), so `npx ruflo tui` works from the registry package, not only a checkout.+- **C. Accepted (phase 2).** Pages after Overview and Cost, all read-only, in this order: **Swarm, then Events, then Missions, then Room last.**+- **D. Accepted (phase 3).** Codex: read-only sandbox by default through the pinned-by-path binary (never the 0.162.1 build), an explicit per-session opt-in for workspace-write, and **no `danger-full-access` path in the TUI**.+ OpenRouter: `httpSend` only to `https://openrouter.ai` plus hosts named in `convoTargets`, https only, no redirects to other hosts, keys referenced by environment variable name only and never rendered or logged,+ model output sanitised through `ansi.ts` `clean` before drawing, and the confirm-gate binding (#3983) required for any write action. Detail in section 3.5.+- **E. Accepted, done.** `ruflo tui --plain` prints one frame as plain text and exits 0 (`ruflo tui --plain | head`). **Without a TTY and without `--plain`** it prints a one-line hint on stderr and exits **2**.+ This replaces the earlier "print one frame, exit 0" behaviour: a script that forgot `--plain` now notices instead of reading a silent frame.diff --git a/v3/docs/adr/INDEX-mod-system.md b/v3/docs/adr/INDEX-mod-system.mdindex 6c16752805..d451125a00 100644--- a/v3/docs/adr/INDEX-mod-system.md+++ b/v3/docs/adr/INDEX-mod-system.md@@ -87,4 +87,4 @@ Other ADRs outside 404-451 that the mod ADRs lean on: 150 (removable integration- **ADRs with no stated parent:** 434, 436, 437, 438, 439, 440, 441 carry no `Builds on` or `Extends` line.- **2026-10-07 additions.** Rows for 477, 478 and 479 were added. 478's link is to a file added by the change that builds that page. 479 is not a mod ADR; it is listed because 476 (hive-mind gating) and the toasts sit on the same MCP and console surfaces. ADRs 454 to 476 are not in these tables.| 487 | Optional ruvnet-brain grounding (detect-only) in the console and mods | Accepted | 10-09 | 404, 443, 444, 481 | — | this PR | console 0.42.0, mods 0.5.0 | `grounding.spec`, `grounding.test.ts` |-| 489 | `ruflo tui`: the console in a terminal of its own, over the same `Host` boundary (standalone adapter, read-only Overview and Cost) | Proposed (phase 1 in draft PR) | 10-11 | 407, 446, 448, 481, 486; related 150 | — | draft PR | not shipped | `tui-boundary.spec`, `tui-host.spec`, `tui-render.spec`, `tui-session.spec`, `tui-command.test.ts` |+| 489 | `ruflo tui`: the console in a terminal of its own, over the same `Host` boundary (standalone adapter, read-only Overview and Cost) | Accepted (phase 1 in PR #4059) | 10-11 | 407, 446, 448, 481, 486; related 150 | — | PR #4059 | not shipped | `tui-boundary.spec`, `tui-host.spec`, `tui-render.spec`, `tui-session.spec`, `tui-command.test.ts` |