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(ruflo-console): a self-check the boot log reports; run buttons say what they need; results go back to Claude (ADR 426)

ruv2dc45aef2273
diff --git a/plugins/ruflo-console/hooks/boot-checks.ts b/plugins/ruflo-console/hooks/boot-checks.ts
new file mode 100644
index 0000000000..ccc68eb39d
--- /dev/null
+++ b/plugins/ruflo-console/hooks/boot-checks.ts
@@ -0,0 +1,14 @@
+/**
+ * Where the boot log reads the self-check's results. A leaf with no imports: the drawing code (frames, the boot picture) must not
+ * import the self-check itself, because the self-check reaches the pages, which reach the drawing code. `register.ts`, the root,
+ * runs the check once and sets the results here; until it has, the boot log draws as it always did.
+ */
+export type BootCheck = { area: string; ok: boolean; problems: readonly string[] }
+
+let held: readonly BootCheck[] | undefined
+
+export const setBootChecks = (results: readonly BootCheck[] | undefined): void => {
+ held = results
+}
+
+export const getBootChecks = (): readonly BootCheck[] | undefined => held
diff --git a/plugins/ruflo-console/hooks/gfx/boot.ts b/plugins/ruflo-console/hooks/gfx/boot.ts
index 8324da5ecd..4767ae673e 100644
--- a/plugins/ruflo-console/hooks/gfx/boot.ts
+++ b/plugins/ruflo-console/hooks/gfx/boot.ts
@@ -2,9 +2,11 @@
* The BBS boot screen, played for the first seconds after the pane opens: a modem dials and connects, then the RuFlo
* neon sign strikes up tube by tube on its brick wall (gfx/neon.ts), then a handshake line and a bar that fills with
* the first ruflo reads, and under them a boot log that brings every area of the console online, one line at a time,
- * for as many rows as the pane has (it scrolls when the pane is short). The boot is the one animation in the console
- * that is decoration; it ends by itself.
+ * for as many rows as the pane has (it scrolls when the pane is short). The sign and the modem are decoration and end by
+ * themselves; the log is not, when the self-check's results are passed: an area shows [ OK ] only if its check passed, and
+ * [FAIL] with the first problem if not, so what the screen claims is what was verified.
*/
+import type { BootCheck } from '../boot-checks'
import { neonPicture, NEON_ROWS } from './neon'
import { Grid } from './raster'
@@ -57,7 +59,7 @@ const NAME_WIDTH = 15
* `total`), so it moves before any read returns and reads 100% before the boot ends at BOOT_MIN_MS. `rows` is the
* pane's body height when it is known: the boot log fills what is left under the sign (0: the sign alone).
*/
-export function bootPicture(project: string, columns: number, age: number, done: number, total: number, rows = 0): Grid {
+export function bootPicture(project: string, columns: number, age: number, done: number, total: number, rows = 0, checks?: readonly BootCheck[]): Grid {
const height = Math.max(BOOT_ROWS, rows)
const grid = new Grid(columns, height)
const type = (y: number, from: number, text: string, color: number, msPerChar = 22) => {
@@ -78,7 +80,11 @@ export function bootPicture(project: string, columns: number, age: number, done:
// The boot log: one area comes online every LOG_MS_PER, [ .. ] while it starts and [ OK ] once the next one has begun; the
// newest lines stay in view when the pane is shorter than the list, and READY closes it.
- const entries = [...BOOT_MODULES.map(entry => ({ ...entry, ready: false })), { name: 'READY', note: `${BOOT_MODULES.length} areas online · press a key or click`, ready: true }]
+ // With the self-check's results the log is a report: READY counts what was verified, and an area that failed says why. Without
+ // them (nothing has run the check) it draws as it always did.
+ const failedAreas = checks === undefined ? 0 : BOOT_MODULES.filter(entry => checks.find(result => result.area === entry.name)?.ok === false).length
+ const readyNote = checks === undefined ? `${BOOT_MODULES.length} areas online · press a key or click` : `${BOOT_MODULES.length - failedAreas} of ${BOOT_MODULES.length} areas verified${failedAreas > 0 ? ` · ${failedAreas} failed` : ''} · press a key or click`
+ const entries = [...BOOT_MODULES.map(entry => ({ ...entry, ready: false })), { name: 'READY', note: readyNote, ready: true }]
const room = height - BOOT_ROWS - 1
const started = age < LOG_FROM_MS ? 0 : Math.min(entries.length, Math.floor((age - LOG_FROM_MS) / LOG_MS_PER) + 1)
const logProgress = started / entries.length
@@ -92,12 +98,15 @@ export function bootPicture(project: string, columns: number, age: number, done:
const isOn = i < started - 1 || started === entries.length
if (entry.ready) {
- grid.text(0, y, `[ OK ] ${entry.name}`, GREEN)
+ grid.text(0, y, failedAreas > 0 ? `[FAIL] ${entry.name}` : `[ OK ] ${entry.name}`, failedAreas > 0 ? PINK : GREEN)
grid.text(7 + 'READY '.length, y, entry.note.slice(0, Math.max(0, columns - 13)), PINK)
} else {
- grid.text(0, y, isOn ? '[ OK ]' : '[ .. ]', isOn ? GREEN : CYAN)
+ // An area that is on has its verdict: [ OK ] only if its check passed; [FAIL] and the first problem, if it did not.
+ const problem = isOn ? checks?.find(result => result.area === entry.name && !result.ok)?.problems[0] : undefined
+
+ grid.text(0, y, problem !== undefined ? '[FAIL]' : isOn ? '[ OK ]' : '[ .. ]', problem !== undefined ? PINK : isOn ? GREEN : CYAN)
grid.text(7, y, entry.name.padEnd(NAME_WIDTH).slice(0, NAME_WIDTH), 0xe6e6e6)
- grid.text(7 + NAME_WIDTH + 1, y, entry.note.slice(0, Math.max(0, columns - 7 - NAME_WIDTH - 1)), DIM)
+ grid.text(7 + NAME_WIDTH + 1, y, (problem ?? entry.note).slice(0, Math.max(0, columns - 7 - NAME_WIDTH - 1)), problem !== undefined ? PINK : DIM)
}
}
}
diff --git a/plugins/ruflo-console/hooks/register.ts b/plugins/ruflo-console/hooks/register.ts
index 4ff6fb3805..e5782ec300 100644
--- a/plugins/ruflo-console/hooks/register.ts
+++ b/plugins/ruflo-console/hooks/register.ts
@@ -10,6 +10,8 @@ import type { Host } from './host'
import { ownerLine, ownerOf } from './tool-owner'
import { newState, PANE_ID, restore, restoreSessions, storeKeyOf, termStoreKeyOf } from './state'
import { BAR_KEY, barView } from './views/bar'
+import { setBootChecks } from './boot-checks'
+import { selfCheckResults } from './self-check'
import type { Kit } from './views/common'
import { picturesOf } from './views/frames'
import { withClearing } from './views/clearing'
@@ -88,6 +90,14 @@ function hostOf($: EngineInterface, cwd: string): Host {
* drill-down, timeline, approvals, events). Every change goes through the ruflo CLI with fixed argv after a confirm.
*/
export const register: Register = (on, raw: PluginOptions) => {
+ // The boot log reports this check, so an [ OK ] on screen means the area's commands resolved. It spawns nothing and takes a
+ // moment; a failure of the check itself leaves the log drawing as it did, never stops the console.
+ try {
+ setBootChecks(selfCheckResults())
+ } catch {
+ setBootChecks(undefined)
+ }
+
const state = newState(raw)
let host: Host | null = null
let control: Controller | null = null
diff --git a/plugins/ruflo-console/hooks/self-check.ts b/plugins/ruflo-console/hooks/self-check.ts
new file mode 100644
index 0000000000..c57b802539
--- /dev/null
+++ b/plugins/ruflo-console/hooks/self-check.ts
@@ -0,0 +1,152 @@
+/**
+ * The console's self-check, pure and spawn-free: for every area the boot log names, does what a press would run still resolve
+ * to a well-formed command? It reads the same registries the buttons read (Security, Performance, Dev Tools, the MetaHarness
+ * lab), so a verb whose argv is empty, whose text field accepts what its rule forbids, or whose documented input is refused is
+ * caught here, not by a person pressing it. It does not run the CLI: that every command is built right is proved here, that the CLI
+ * answers is the Doctor's job. The boot log shows these results, so an `[ OK ]` on screen means this passed for that area.
+ * Tested in tests/self-check.spec.ts, including that a broken entry fails (so a pass is not vacuous).
+ */
+import { VIEW_ASK } from './ask-claude'
+import { emptyFields, type DevFields } from './data/devtools'
+import { DEV, type DevEntry } from './devtools'
+import { BOOT_MODULES } from './gfx/boot'
+import { LAB, type LabEntry } from './mh-lab'
+import { PERF, type PerfEntry } from './perf'
+import { SECURE, SECURE_TEXT, type SecEntry, type SecText } from './secure'
+import { newState, VIEWS, type State, type ViewId } from './state'
+
+export type CheckResult = { area: string; ok: boolean; checked: number; problems: string[] }
+
+/** Each boot area and the page it opens: every area must name a real page, and the spec fails on an area with no row here. */
+export const AREA_VIEW: Record<string, ViewId> = {
+ Missions: 'missions', Overview: 'overview', Swarm: 'swarm', 'Hive-Mind': 'hive', Claims: 'claims', Approvals: 'approvals', Automation: 'automate',
+ Learning: 'learning', Neural: 'neural', 'Vector Lab': 'vector', 'Memory Lab': 'memory', MetaHarness: 'metaharness', 'Self-Evolution': 'evolve',
+ Security: 'secure', Federation: 'federation', 'x.ruv.io': 'xruv', 'Plugins & Mods': 'plugins', Skills: 'skills', 'Plugin Catalog': 'market',
+ 'Dev Tools': 'devtools', 'Cost & Budget': 'cost', Timeline: 'timeline', Events: 'events', Performance: 'perf', 'AI Terminal': 'terminal', Settings: 'settings',
+}
+
+export type Registries = { secure: readonly SecEntry[]; secureText: readonly SecText[]; perf: readonly PerfEntry[]; dev: readonly DevEntry[]; lab: readonly LabEntry[] }
+export const REGISTRIES: Registries = { secure: SECURE, secureText: SECURE_TEXT, perf: PERF, dev: DEV, lab: LAB }
+
+/** One value per field that its rule accepts, so every runnable Dev Tools row has an input that runs. */
+export const SAMPLE_FIELDS: DevFields = { ref: 'HEAD~1', path: 'memory/sample.rvf', label: 'ckpt-1', url: 'https://example.com', target: '@e1', query: 'auth', task: 'review my pull request', cmd: 'ls', id: 'agent-1', note: 'hello' }
+
+/** Free text, then an action type (policy-eval takes one): a text verb passes when any of these builds its command. */
+const SAMPLE_TEXTS = ['hello world', 'deploy']
+const isArgv = (value: unknown): value is readonly string[] => Array.isArray(value) && value.length > 0 && value.every(part => typeof part === 'string' && part !== '' && !/[\u0000-\u001f]/.test(part))
+
+function checkArgs(id: string, args: unknown, problems: string[]): void {
+ if (!isArgv(args)) problems.push(`${id}: its command is empty or has an empty or control-character part`)
+}
+
+function checkSecure(entries: readonly SecEntry[], text: readonly SecText[], perf: readonly PerfEntry[], problems: string[]): number {
+ for (const entry of [...entries, ...perf]) {
+ checkArgs(entry.id, entry.args, problems)
+ if (typeof entry.read !== 'function') problems.push(`${entry.id}: nothing reads its output`)
+ if (entry.label.trim() === '') problems.push(`${entry.id}: no label for the confirm row`)
+ }
+
+ for (const entry of text) {
+ const empty = entry.argv('')
+ const sample = SAMPLE_TEXTS.find(candidate => isArgv(entry.argv(candidate)))
+
+ if (empty !== null) problems.push(`${entry.id}: an empty field must be refused, but it builds a command`)
+ if (entry.argv('-rf') !== null) problems.push(`${entry.id}: text starting with - must be refused (it could be read as a flag)`)
+ if (sample === undefined) problems.push(`${entry.id}: no sample input (${SAMPLE_TEXTS.join(', ')}) builds its command, so its button can never run`)
+ else if (!(entry.argv(sample) ?? []).some(part => part.includes(sample))) problems.push(`${entry.id}: the text does not reach the command`)
+ if (typeof entry.read !== 'function') problems.push(`${entry.id}: nothing reads its output`)
+ }
+
+ return entries.length + text.length + perf.length
+}
+
+function checkDev(entries: readonly DevEntry[], problems: string[]): number {
+ for (const entry of entries) {
+ if (entry.na !== undefined) {
+ if (entry.na.trim() === '') problems.push(`${entry.id}: marked n/a with no reason to show`)
+
+ continue
+ }
+
+ if (entry.args === undefined) {
+ problems.push(`${entry.id}: it is neither runnable nor marked n/a`)
+
+ continue
+ }
+
+ const bare = entry.args(emptyFields())
+
+ // With no field needed, an empty page must already run; with one, an empty field may be refused, but the sample must run.
+ if (bare === null && entry.input === undefined) problems.push(`${entry.id}: it names no input field, yet cannot run on an empty page`)
+
+ const sampled = entry.args(SAMPLE_FIELDS)
+
+ if (!isArgv(sampled)) problems.push(`${entry.id}: no input is accepted, so its button can never run`)
+ }
+
+ return entries.length
+}
+
+function checkLab(entries: readonly LabEntry[], state: State, problems: string[]): number {
+ for (const entry of entries) {
+ const args = typeof entry.args === 'function' ? entry.args(state) : entry.args
+
+ if (args === undefined && entry.types === undefined) problems.push(`${entry.id}: no command and no command to type`)
+ else if (args === null) {
+ if ((entry.why ?? '').trim() === '') problems.push(`${entry.id}: it cannot run now and says nothing about why`)
+ } else if (args !== undefined) checkArgs(entry.id, args, problems)
+ }
+
+ return entries.length
+}
+
+function checkUnique(registries: Registries, problems: string[]): void {
+ const seen = new Set<string>()
+
+ for (const id of [...registries.secure, ...registries.secureText, ...registries.perf, ...registries.dev, ...registries.lab].map(entry => entry.id)) {
+ if (seen.has(id)) problems.push(`${id}: used by two entries (ids are palette keywords)`)
+ seen.add(id)
+ }
+}
+
+/**
+ * One result per boot area, in boot order. Every area has its page checked (it exists, has a key, and has an Ask row); the areas that
+ * own a command registry have each command checked too. `problems` names what is wrong, so the boot log can say what failed.
+ */
+export function selfCheck(registries: Registries = REGISTRIES, views: readonly { id: string; key: string }[] = VIEWS, ask: Record<string, unknown> = VIEW_ASK): CheckResult[] {
+ const state = newState(undefined)
+ const shared: string[] = []
+
+ checkUnique(registries, shared)
+
+ return BOOT_MODULES.map(({ name }): CheckResult => {
+ const problems: string[] = []
+ const view = AREA_VIEW[name]
+ let checked = 1
+
+ if (view === undefined) problems.push(`${name}: no page is named for this area`)
+ else {
+ if (!views.some(entry => entry.id === view)) problems.push(`${name}: its page "${view}" does not exist`)
+ if (!views.some(entry => entry.id === view && entry.key !== '')) problems.push(`${name}: its page has no key`)
+ if (ask[view] === undefined) problems.push(`${name}: its page has no Ask Claude row`)
+ }
+
+ if (name === 'Security') checked += checkSecure(registries.secure, registries.secureText, [], problems)
+ if (name === 'Performance') checked += checkSecure([], [], registries.perf, problems)
+ if (name === 'Dev Tools') checked += checkDev(registries.dev, problems)
+ if (name === 'MetaHarness') checked += checkLab(registries.lab, state, problems)
+ // Ids are palette keywords shared by all four registries, so a duplicate fails each area that owns one of them.
+ if (['Security', 'Performance', 'Dev Tools', 'MetaHarness'].includes(name)) problems.push(...shared)
+
+ return { area: name, ok: problems.length === 0, checked, problems }
+ })
+}
+
+let held: CheckResult[] | null = null
+
+/** The real registries' results, computed once: the boot log reads these every frame. */
+export function selfCheckResults(): CheckResult[] {
+ held ??= selfCheck()
+
+ return held
+}
diff --git a/plugins/ruflo-console/hooks/views/devtools.ts b/plugins/ruflo-console/hooks/views/devtools.ts
index 00f88815ce..2c715b0880 100644
--- a/plugins/ruflo-console/hooks/views/devtools.ts
+++ b/plugins/ruflo-console/hooks/views/devtools.ts
@@ -5,6 +5,7 @@ import { DEV, DEV_GROUPS, devSpec, type DevCost, type DevEntry, type DevGroup }
import { slot } from './attention'
import { ago, button, clip, col, row, section, text, THEME, type Ctx } from './common'
import { spinAt } from '../spinner'
+import { sendResultRow } from './secure'
/** Result lines in view at once; j/k scroll the rest. */
const RESULT_ROWS = 14
@@ -122,6 +123,8 @@ function resultRows(ctx: Ctx): RenderElement[] {
)
}
+ rows.push(sendResultRow(ctx, 'dt-send'))
+
return slot(ctx, rows)
}
diff --git a/plugins/ruflo-console/hooks/views/frames.ts b/plugins/ruflo-console/hooks/views/frames.ts
index d400e8d2ba..d43e7c724d 100644
--- a/plugins/ruflo-console/hooks/views/frames.ts
+++ b/plugins/ruflo-console/hooks/views/frames.ts
@@ -6,6 +6,7 @@
import type { AuditTrend, HarnessScore, Intelligence } from '../data/cli'
import { recentByAgent } from '../data/events'
import { agentLabels } from '../data/parse'
+import { getBootChecks } from '../boot-checks'
import type { Snapshot } from '../data/snapshot'
import type { Channels, Peers, Roster } from '../data/cli'
import { pipelinePicture, radarPicture, samplesPicture, trendPicture, gaugePicture, type Stage } from '../gfx/charts'
@@ -124,7 +125,7 @@ export function picturesOf(state: State, columns: number, nowMs: number, t: numb
// The BBS boot screen owns the pane for its first seconds; nothing else is drawn under it.
if (isBooting(state, nowMs)) {
- pictures.set('boot', bootPicture(state.cwd.split('/').filter(Boolean).at(-1) ?? '', Math.min(width, 90), nowMs - state.pane.bootAtMs, state.probes.size, PROBES.length, state.pane.rows))
+ pictures.set('boot', bootPicture(state.cwd.split('/').filter(Boolean).at(-1) ?? '', Math.min(width, 90), nowMs - state.pane.bootAtMs, state.probes.size, PROBES.length, state.pane.rows, getBootChecks()))
return pictures
}
diff --git a/plugins/ruflo-console/hooks/views/mh-lab.ts b/plugins/ruflo-console/hooks/views/mh-lab.ts
index 2d112dbb73..0595f57d1e 100644
--- a/plugins/ruflo-console/hooks/views/mh-lab.ts
+++ b/plugins/ruflo-console/hooks/views/mh-lab.ts
@@ -2,6 +2,7 @@ import type { RenderElement } from 'claude-code'
import { LAB, LAB_GROUPS, labSpec, PROMOTE_COMMAND, type LabCost, type LabEntry } from '../mh-lab'
import { slot } from './attention'
+import { sendResultRow } from './secure'
import { ago, button, clip, row, rule, section, text, THEME, type Ctx } from './common'
/** Result lines in view at once; j/k scroll the rest. */
@@ -72,6 +73,8 @@ function resultRows(ctx: Ctx): RenderElement[] {
)
}
+ rows.push(sendResultRow(ctx, 'lab-send'))
+
return slot(ctx, rows)
}
diff --git a/plugins/ruflo-console/hooks/views/secure.ts b/plugins/ruflo-console/hooks/views/secure.ts
index 7cd3ee2b19..18f97f25bd 100644
--- a/plugins/ruflo-console/hooks/views/secure.ts
+++ b/plugins/ruflo-console/hooks/views/secure.ts
@@ -18,23 +18,42 @@ const TAG: Record<SecCost, { text: string; color: () => string }> = {
export const COST_KEY = ' $0 local read, runs at once · wr writes a file · net reaches the network: each of these asks, its cost on the confirm row'
/** One dotted-leader row: the cost tag, the name, what it does, and its ▸ run button (with the field's text, if it takes one). */
-export function entryRow(ctx: Ctx, entry: { id: string; name: string; about: string; cost: SecCost }, textOf?: () => string): RenderElement {
+export function entryRow(ctx: Ctx, entry: { id: string; name: string; about: string; cost: SecCost }, textOf?: () => string, isReady?: () => boolean): RenderElement {
const lead = Math.max(14, Math.min(19, ctx.columns - 40))
const tag = TAG[entry.cost]
+ // A row that takes the field's text cannot run on an empty or refused field: its button dims and the row says what to do first.
+ const waiting = isReady !== undefined && !isReady()
return row(
ctx,
[
ctx.kit.Text({ bold: true, color: tag.color(), children: ` ${tag.text}` }),
ctx.kit.Text({ bold: true, color: THEME.head, children: ` ${entry.name} `.padEnd(lead, '.') }),
- ctx.kit.Text({ color: THEME.info, wrap: 'truncate-end', children: clip(` ${entry.about}`, Math.max(4, ctx.columns - lead - 18)) }),
- // The run is the row's one action, so it is a primary button: it is the first thing the eye finds.
- ctx.kit.Button({ key: `run-${entry.id}`, label: ' ▶ run ', variant: 'primary' as const, onPress: () => void ctx.act.run(entry.id, textOf?.() ?? '') }),
+ ctx.kit.Text({ color: THEME.info, dimColor: waiting, wrap: 'truncate-end', children: clip(` ${entry.about}`, Math.max(4, ctx.columns - lead - 34)) }),
+ // The run is the row's one action, so it is a primary button: it is the first thing the eye finds. Waiting on text, it is plain.
+ ctx.kit.Button({ key: `run-${entry.id}`, label: ' ▶ run ', ...(waiting ? { plain: true, dimColor: true } : { variant: 'primary' as const }), onPress: () => void ctx.act.run(entry.id, textOf?.() ?? '') }),
+ ...(waiting ? [ctx.kit.Text({ bold: true, color: THEME.warn, children: ' ← type text above first' })] : []),
],
`row-${entry.id}`,
)
}
+/**
+ * Under a result: hands it to the main Claude session. The page's text, this result included, goes as quoted data with secrets
+ * removed (the ADR 411 bridge: it asks first and says it starts a billed turn), and the question asks what to do about it, so a run
+ * leads somewhere: a fix, a follow-up command, a setting to change.
+ */
+export function sendResultRow(ctx: Ctx, key: string): RenderElement {
+ return row(
+ ctx,
+ [
+ button(ctx, key, '✦ send result to Claude', () => ctx.act.ask.ask('Explain this result, then tell me what to fix, run or change next, with the exact ruflo command or setting.'), { primary: true }),
+ text(ctx, ' quoted as data, secrets removed; asks first', { dimColor: true }),
+ ],
+ `${key}-row`,
+ )
+}
+
/** A verb the CLI does not have, said as such rather than invented. */
export const naRow = (ctx: Ctx, name: string, why: string): RenderElement => text(ctx, ` n/a ${name.padEnd(14, '.')} ${why}`, { dimColor: true })
@@ -76,6 +95,8 @@ export function resultRows(ctx: Ctx, isMine: (id: string) => boolean): RenderEle
)
}
+ rows.push(sendResultRow(ctx, 'result-send'))
+
return slot(ctx, rows)
}
@@ -137,7 +158,7 @@ function pasteRows(ctx: Ctx): RenderElement[] {
rows.push(text(ctx, ' this surface has no text field: /ruflo run aid-check <text> checks text headless', { dimColor: true }))
}
- for (const entry of SECURE_TEXT) rows.push(entryRow(ctx, entry, () => memo.draft))
+ for (const entry of SECURE_TEXT) rows.push(entryRow(ctx, entry, () => memo.draft, () => entry.argv(memo.draft) !== null))
rows.push(text(ctx, ' ▸ run takes the text in the field; policy-eval takes an action type (deploy, tool:Bash) and asks first', { dimColor: true }))
return rows
diff --git a/plugins/ruflo-console/tests/diagrams.spec.ts b/plugins/ruflo-console/tests/diagrams.spec.ts
index 1707053116..2295a13ce1 100644
--- a/plugins/ruflo-console/tests/diagrams.spec.ts
+++ b/plugins/ruflo-console/tests/diagrams.spec.ts
@@ -191,6 +191,30 @@ describe('BBS boot screen', () => {
expect(bootPicture('demo', 80, 5_400, 10, 10).rows).toBe(BOOT_ROWS)
})
+ it('reports the self-check: [ OK ] only for an area whose check passed, [FAIL] and its problem for one that did not, READY counting what was verified', () => {
+ const rows = BOOT_ROWS + 1 + BOOT_MODULES.length + 1
+ const passing = BOOT_MODULES.map(entry => ({ area: entry.name, ok: true, problems: [] as string[] }))
+ const withFailure = passing.map(result => (result.area === 'Security' ? { ...result, ok: false, problems: ['aid-check: an empty field must be refused'] } : result))
+ const good = text(bootPicture('demo', 80, 5_400, 10, 10, rows, passing), 80)
+ const bad = text(bootPicture('demo', 80, 5_400, 10, 10, rows, withFailure), 80)
+
+ expect(good).toContain('[ OK ] Security')
+ expect(good).toContain(`${BOOT_MODULES.length} of ${BOOT_MODULES.length} areas verified`)
+ expect(good).toContain('[ OK ] READY')
+ expect(good).not.toContain('[FAIL]')
+
+ expect(bad).toContain('[FAIL] Security')
+ expect(bad).toContain('aid-check: an empty field must be refused')
+ expect(bad).toContain('[ OK ] Missions')
+ expect(bad).toContain(`${BOOT_MODULES.length - 1} of ${BOOT_MODULES.length} areas verified · 1 failed`)
+ expect(bad).toContain('[FAIL] READY')
+
+ // An area still starting shows [ .. ] whatever its verdict: the result appears when the next area begins.
+ const securityAt = 1_500 + 120 * BOOT_MODULES.findIndex(entry => entry.name === 'Security')
+
+ expect(text(bootPicture('demo', 80, securityAt + 10, 10, 10, rows, withFailure), 80)).toContain('[ .. ] Security')
+ })
+
it('plays at least 5.4 s, longer while the first read is out, never past 8 s; only with the bbs look and boot on', () => {
const state = newState({})
diff --git a/plugins/ruflo-console/tests/self-check.spec.ts b/plugins/ruflo-console/tests/self-check.spec.ts
new file mode 100644
index 0000000000..b2c535c328
--- /dev/null
+++ b/plugins/ruflo-console/tests/self-check.spec.ts
@@ -0,0 +1,109 @@
+/**
+ * The self-check: every area the boot log names has its page and its commands checked, the real registries pass, and a broken
+ * entry fails (a pass that cannot fail would prove nothing). Run with
+ * npx vitest run plugins/ruflo-console/tests/self-check.spec.ts
+ */
+import { describe, expect, it } from 'vitest'
+
+import { BOOT_MODULES } from '../hooks/gfx/boot'
+import { AREA_VIEW, REGISTRIES, selfCheck, selfCheckResults, type Registries } from '../hooks/self-check'
+import { VIEWS } from '../hooks/state'
+
+const failing = (results: ReturnType<typeof selfCheck>) => results.filter(result => !result.ok)
+const area = (results: ReturnType<typeof selfCheck>, name: string) => results.find(result => result.area === name)
+
+describe('self-check: the real console', () => {
+ it('passes for every area, and says nothing is wrong', () => {
+ expect(failing(selfCheck()).map(result => `${result.area}: ${result.problems.join('; ')}`)).toEqual([])
+ })
+
+ it('checks every area the boot log names, in boot order, and names a page for each, so no [ OK ] goes unchecked', () => {
+ expect(selfCheck().map(result => result.area)).toEqual(BOOT_MODULES.map(entry => entry.name))
+ expect(Object.keys(AREA_VIEW).sort()).toEqual(BOOT_MODULES.map(entry => entry.name).sort())
+ for (const view of Object.values(AREA_VIEW)) expect(VIEWS.some(entry => entry.id === view)).toBe(true)
+ })
+
+ it('looks at the commands of the four areas that own a registry, not only their pages', () => {
+ const results = selfCheck()
+
+ expect(area(results, 'Security')?.checked).toBeGreaterThan(10)
+ expect(area(results, 'Performance')?.checked).toBe(REGISTRIES.perf.length + 1)
+ expect(area(results, 'Dev Tools')?.checked).toBe(REGISTRIES.dev.length + 1)
+ expect(area(results, 'MetaHarness')?.checked).toBe(REGISTRIES.lab.length + 1)
+ expect(area(results, 'Missions')?.checked).toBe(1)
+ })
+
+ it('is computed once for the boot log', () => {
+ expect(selfCheckResults()).toBe(selfCheckResults())
+ })
+})
+
+describe('self-check: it fails on what is broken', () => {
+ const broken = (change: (registries: Registries) => Registries) => selfCheck(change(REGISTRIES))
+
+ it('a text verb that builds a command from an empty field', () => {
+ const results = broken(r => ({ ...r, secureText: [{ ...r.secureText[0], id: 'aid-bad', argv: () => ['security', 'defend'] }, ...r.secureText.slice(1)] }))
+
+ expect(area(results, 'Security')?.problems.join(' ')).toContain('aid-bad: an empty field must be refused')
+ })
+
+ it('a text verb that lets text starting with - through, where it could be read as a flag', () => {
+ const results = broken(r => ({ ...r, secureText: [{ ...r.secureText[0], id: 'aid-flag', argv: text => ['security', text] }, ...r.secureText.slice(1)] }))
+
+ expect(area(results, 'Security')?.problems.join(' ')).toContain('aid-flag: text starting with - must be refused')
+ })
+
+ it('a text verb that refuses every input, so its button could never run', () => {
+ const results = broken(r => ({ ...r, secureText: [{ ...r.secureText[0], id: 'aid-never', argv: () => null }, ...r.secureText.slice(1)] }))
+
+ expect(area(results, 'Security')?.problems.join(' ')).toContain('aid-never: no sample input')
+ })
+
+ it('a command with an empty part, and one with no reader', () => {
+ const results = broken(r => ({ ...r, perf: [{ ...r.perf[0], id: 'perf-empty', args: ['performance', ''] }, { ...r.perf[1], id: 'perf-noread', read: undefined as never }, ...r.perf.slice(2)] }))
+ const problems = area(results, 'Performance')?.problems.join(' ') ?? ''
+
+ expect(problems).toContain('perf-empty: its command is empty or has an empty')
+ expect(problems).toContain('perf-noread: nothing reads its output')
+ })
+
+ it('a Dev Tools row that no input can run, one with no input field that cannot run empty, and an n/a with no reason', () => {
+ const dev = REGISTRIES.dev.find(entry => entry.args !== undefined) as (typeof REGISTRIES.dev)[number]
+ const results = broken(r => ({
+ ...r,
+ dev: [{ ...dev, id: 'dt-never', args: () => null }, { ...dev, id: 'dt-silent', input: undefined, args: fields => (fields.task === '' ? null : ['git', 'status']) }, { ...dev, id: 'dt-na', na: ' ', args: undefined }, ...r.dev],
+ }))
+ const problems = area(results, 'Dev Tools')?.problems.join(' ') ?? ''
+
+ expect(problems).toContain('dt-never: no input is accepted')
+ expect(problems).toContain('dt-silent: it names no input field, yet cannot run on an empty page')
+ expect(problems).toContain('dt-na: marked n/a with no reason')
+ })
+
+ it('a lab verb that cannot run and gives no reason, and one with nothing to run or type', () => {
+ const lab = REGISTRIES.lab[0]
+ const results = broken(r => ({ ...r, lab: [{ ...lab, id: 'mh-mute', args: () => null, why: undefined }, { ...lab, id: 'mh-empty', args: undefined, types: undefined }, ...r.lab] }))
+ const problems = area(results, 'MetaHarness')?.problems.join(' ') ?? ''
+
+ expect(problems).toContain('mh-mute: it cannot run now and says nothing about why')
+ expect(problems).toContain('mh-empty: no command and no command to type')
+ })
+
+ it('two entries sharing an id (a palette keyword), which fails each registry-owning area', () => {
+ const results = broken(r => ({ ...r, perf: [{ ...r.perf[0], id: r.secure[0].id }, ...r.perf.slice(1)] }))
+
+ expect(area(results, 'Security')?.problems.join(' ')).toContain(`${REGISTRIES.secure[0].id}: used by two entries`)
+ expect(area(results, 'Performance')?.ok).toBe(false)
+ expect(area(results, 'Missions')?.ok).toBe(true)
+ })
+
+ it('a page that is missing, has no key, or has no Ask row', () => {
+ const noPage = selfCheck(REGISTRIES, VIEWS.filter(view => view.id !== 'missions'))
+ const noKey = selfCheck(REGISTRIES, VIEWS.map(view => (view.id === 'swarm' ? { ...view, key: '' } : view)))
+ const noAsk = selfCheck(REGISTRIES, VIEWS, {})
+
+ expect(area(noPage, 'Missions')?.problems.join(' ')).toContain('its page "missions" does not exist')
+ expect(area(noKey, 'Swarm')?.problems.join(' ')).toContain('its page has no key')
+ expect(failing(noAsk)).toHaveLength(BOOT_MODULES.length)
+ })
+})
diff --git a/v3/docs/adr/ADR-426-console-self-check-boot-report-and-visible-runs.md b/v3/docs/adr/ADR-426-console-self-check-boot-report-and-visible-runs.md
new file mode 100644
index 0000000000..604a3070bf
--- /dev/null
+++ b/v3/docs/adr/ADR-426-console-self-check-boot-report-and-visible-runs.md
@@ -0,0 +1,58 @@
+# ADR 426: A self-check that the boot log reports, run buttons that say what they need, and results that go back to Claude
+
+Status: Accepted (ships in ruflo-console 0.26.0)
+
+Date: 2026 10 03
+
+Decision owner: Ruflo maintainers
+
+Scope: `plugins/ruflo-console`: `hooks/self-check.ts` (new, pure), `hooks/boot-checks.ts` (new, a leaf), `hooks/gfx/boot.ts`, `hooks/views/frames.ts`, `hooks/register.ts`, `hooks/views/secure.ts` (`entryRow`, `sendResultRow`), `hooks/views/devtools.ts`, `hooks/views/mh-lab.ts`, `tests/self-check.spec.ts` (new), `tests/diagrams.spec.ts`.
+
+Extends: ADR 421 (the boot screen), ADR 411 (the Claude UI bridge), ADR 413 (the regression system), ADR 420 (the tool-coverage audit).
+
+## 1. Context
+
+Three things were wrong, found by use rather than by a test.
+
+- **The boot log claimed what it had not checked.** Each area printed `[ OK ]` on a timer, one every 120 ms, whether or not anything in it worked. The sign and the modem are decoration; a status line is not, and a green that is not earned teaches people to ignore green.
+- **A run button could only fail.** The Security rows that take the field's text (`aid-check`, `aid-plan`, and the rest) refused with `nothing to do: type "aid-check <text>"; text may not start with -` when pressed on an empty field, and nothing on the row said it was waiting for text. The page's folds (this branch) had also hidden the field, which made it worse, but the row itself never told the person what it needed.
+- **A run led nowhere.** A result sat in the pane. The only way to act on it was to read it, work out the next command, and type it. ADR 411's bridge already sends a page to the main Claude session as quoted data, but it was only in the footer, not at the result.
+
+## 2. Decision
+
+### 2.1 A self-check, pure and spawn-free
+`hooks/self-check.ts` checks every area the boot log names. For each: its page exists, has a key, and has an Ask row (ADR 411). For the four areas that own a command registry (Security, Performance, Dev Tools, MetaHarness) it also checks every command, reading the same registries the buttons read:
+
+- a command's argv is non-empty, with no empty or control-character part, and something reads its output;
+- a text-taking verb **refuses an empty field**, **refuses text starting with `-`** (it could be read as a flag), and **builds its command from at least one sample** (free text, or an action type for `policy-eval`), with the text reaching the command, so its button can run;
+- a Dev Tools row is runnable or has a reason it is n/a; one that names no input field runs on an empty page; one with a field has an input that runs;
+- a lab verb that cannot run now says why;
+- no two entries share an id (the id is a palette keyword).
+
+It runs no process. That each command is built right is proved here; that the CLI answers is the Doctor's job and stays a button that asks first (the console runs nothing on open, ADR 407).
+
+### 2.2 The boot log reports it
+`bootPicture` takes the results. An area shows `[ OK ]` only if its check passed, and `[FAIL]` with its first problem if not; READY says `N of M areas verified` and `[FAIL] READY` when any failed. `register.ts` runs the check once at load and puts the results in `hooks/boot-checks.ts`, a leaf that `frames.ts` reads. The leaf exists because the self-check reaches the pages (through the Ask table) and the pages reach the drawing code, so frames importing the check would be a cycle. If the check itself throws, the log draws as before and the console starts. With no results (a caller that passes none) the log draws as it always did, which is the only way the older boot tests still hold.
+
+### 2.3 A run button says what it needs
+A row that takes the field's text dims its button and says `← type text above first` while the field would be refused. A runnable row's button is a primary `▶ run`. Where a field lives in a section, the section is open by default, so the field is in reach.
+
+### 2.4 A result goes back to Claude
+Under each result block (Security, Performance, Dev Tools, the MetaHarness lab) a `✦ send result to Claude` button calls the ADR 411 bridge: the page's text, the result included, as quoted data with secrets removed, after the confirm that says it starts a billed turn, with a question that asks what to fix, run or change next.
+
+## 3. Alternatives considered
+
+- **Run every command at startup.** Rejected: the four registries hold 149 entries, each a `ruflo` cold start, on every open, and some write or touch the network. The self-check proves the commands are built correctly and takes about a third of a millisecond (measured over 20 runs); a live run is the Doctor's, on a button.
+- **Keep the timer and add a separate "checks" screen.** Rejected: the boot log is where the console already says what is online, and two reports could disagree.
+- **Have `frames.ts` import the self-check.** Rejected: an import cycle through the pages. The leaf is four lines.
+- **Make the refused button say more.** The refusal text is the runner's and also serves the headless `/ruflo run aid-check <text>`, where it is right. The row now says it before the press.
+
+## 4. What the check does not prove
+
+It does not run the CLI, so a command that is well-formed but names a verb the installed ruflo no longer has passes. ADR 420's audit against the CLI's own source and the live smoke (`scripts/e2e-smoke.sh`) cover that. It does not draw the views, so a section that hides a field is not caught here; the kit tests (which need the `claude-code/testing` host package) do. A sample that is too narrow can fail a verb whose rule it does not meet, which is how `policy-eval` first failed against free text: the check now passes a verb that any documented sample builds, and still fails one that none does.
+
+## 5. Tests
+
+- `tests/self-check.spec.ts` (12): the real registries pass; every boot area is checked, in boot order, and every area names a real page, so no `[ OK ]` goes unchecked; the four registry areas have their commands counted; and a broken entry fails each way: a text verb that builds a command from an empty field, one that lets `-` through, one that refuses every input, an empty argv part, a command with no reader, a Dev Tools row no input can run, one with no input field that cannot run empty, an n/a with no reason, a lab verb that cannot run and does not say why, one with nothing to run or type, a duplicate id, and a page that is missing, has no key, or has no Ask row. A check that cannot fail would prove nothing, so these are the point.
+- `tests/diagrams.spec.ts`: with results the log shows `[ OK ]` for a passed area and `[FAIL]` with its problem for a failed one, READY counts what was verified and fails when any did, and an area still starting shows `[ .. ]`.
+- The console suite passes 365 tests. 22 files cannot load the `claude-code/testing` host package here, each failing only on that import; they run in CI (ADR 413). The row text, the dimmed button and the send button are in those, so they are not yet exercised.