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(console): learning pipeline diagram with stale stages and router candidates picture (ADR-455)

ruv54cacbd3c757
diff --git a/plugins/ruflo-console/hooks/data/pipeline.ts b/plugins/ruflo-console/hooks/data/pipeline.ts
new file mode 100644
index 0000000000..5e8e22310e
--- /dev/null
+++ b/plugins/ruflo-console/hooks/data/pipeline.ts
@@ -0,0 +1,99 @@
+/**
+ * The learning pipeline and the router's last route as data (ADR-455). Pure: nothing here reads a file or draws; the view
+ * hands in what the Learning page already reads. Staleness is a clock rule on a source's own timestamp, never a guess.
+ */
+
+/** A stage is stale when the file behind it has had nothing new for this long (the same day the Router block already flags). */
+export const STALE_AFTER_MS = 24 * 3_600_000
+
+export type StageState = 'live' | 'stale' | 'absent'
+
+export type PipeStage = { name: string; count: number | null; /** When the source last gained something; null where nothing timestamps it. */ atMs: number | null; state: StageState; ageMs: number | null }
+
+/**
+ * `absent`: nothing measures the stage (no count). `stale`: it has a timestamp older than STALE_AFTER_MS. Otherwise `live`,
+ * which includes a count with no timestamp (CONSOLIDATE): an unknown age is never read as old.
+ */
+export function stageStateOf(count: number | null, atMs: number | null, nowMs: number): { state: StageState; ageMs: number | null } {
+ if (count === null) return { state: 'absent', ageMs: null }
+ if (atMs === null || !Number.isFinite(atMs)) return { state: 'live', ageMs: null }
+
+ const ageMs = Math.max(0, nowMs - atMs)
+
+ return { state: ageMs > STALE_AFTER_MS ? 'stale' : 'live', ageMs }
+}
+
+/** The stages with their state; `atMs` maps a stage name to its source's last-change time where one exists. */
+export function pipeStagesOf(stages: readonly { name: string; count: number | null }[], atMs: Readonly<Record<string, number | null | undefined>>, nowMs: number): PipeStage[] {
+ return stages.map(stage => {
+ const at = atMs[stage.name] ?? null
+
+ return { name: stage.name, count: stage.count, atMs: at, ...stageStateOf(stage.count, at, nowMs) }
+ })
+}
+
+/** A short age: 40s, 12m, 3h, 8d. */
+export function ageWords(ageMs: number): string {
+ const s = Math.round(ageMs / 1000)
+
+ return s < 60 ? `${s}s` : s < 3600 ? `${Math.floor(s / 60)}m` : s < 86_400 ? `${Math.floor(s / 3600)}h` : `${Math.floor(s / 86_400)}d`
+}
+
+/** What a stage's note line says under its count. */
+export function stageNote(stage: PipeStage): string {
+ if (stage.state === 'absent') return 'no data'
+ if (stage.ageMs === null) return 'age n/a'
+
+ return stage.state === 'stale' ? `stale ${ageWords(stage.ageMs)}` : `${ageWords(stage.ageMs)} ago`
+}
+
+export type RouteOwner = 'mods' | 'classic' | 'unseated'
+export type RouteCandidate = { agent: string; /** 0..1, or null where the router printed none. */ confidence: number | null }
+export type RouteSource = 'mods' | 'router-query' | 'none'
+
+export type RouteModel = { owner: RouteOwner; source: RouteSource; candidates: RouteCandidate[]; /** Whether a keyword matched (the in-process pick only). */ matched: boolean | null; reason: string | null; asked: string | null }
+
+/** Who routes in this project: the classic hook-handler, the mod, or nobody known (ruflo-mods not seated). */
+export const routeOwnerOf = (seated: boolean, classicOwnsRoute: boolean): RouteOwner => (!seated ? 'unseated' : classicOwnsRoute ? 'classic' : 'mods')
+
+const clamp01 = (value: number): number => (Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0)
+const percent = (text: string | undefined): number | null => (text === undefined ? null : clamp01(Number(text) / 100))
+
+/**
+ * The router's answer as the Learning Lab prints it (`nn-route`, from `hooks route --format json`): `→ agent · 87% · method`,
+ * then one ` or agent · 12%` line per runner-up. Anything that does not start that way yields no candidates.
+ */
+export function candidatesFromLines(lines: readonly string[]): RouteCandidate[] {
+ const first = /^→ (\S+)(?: · (\d{1,3})%)?/.exec(lines[0] ?? '')
+
+ if (first === null) return []
+
+ const out: RouteCandidate[] = [{ agent: first[1] as string, confidence: percent(first[2]) }]
+
+ for (const line of lines.slice(1)) {
+ const alt = /^\s+or (\S+)(?: · (\d{1,3})%)?/.exec(line)
+
+ if (alt !== null) out.push({ agent: alt[1] as string, confidence: percent(alt[2]) })
+ }
+
+ return out
+}
+
+/**
+ * The last route. A route the person asked for in the Lab (`nn-route`) carries the runner-ups, so it wins when there is one;
+ * otherwise the mod's last in-process pick, which stores only the winner. Neither: an honest empty model.
+ */
+export function routeModelOf(input: {
+ seated: boolean
+ classicOwnsRoute: boolean
+ route: { agent: string; confidence: number; matched: boolean; reason: string } | null
+ lab: { id: string; label: string; lines: readonly string[] } | null
+}): RouteModel {
+ const owner = routeOwnerOf(input.seated, input.classicOwnsRoute)
+ const asked = input.lab?.id === 'nn-route' ? candidatesFromLines(input.lab.lines) : []
+
+ if (input.lab !== null && asked.length > 0) return { owner, source: 'router-query', candidates: asked, matched: null, reason: null, asked: input.lab.label }
+ if (input.route !== null) return { owner, source: 'mods', candidates: [{ agent: input.route.agent, confidence: clamp01(input.route.confidence) }], matched: input.route.matched, reason: input.route.reason, asked: null }
+
+ return { owner, source: 'none', candidates: [], matched: null, reason: null, asked: null }
+}
diff --git a/plugins/ruflo-console/hooks/gfx/pipeline.ts b/plugins/ruflo-console/hooks/gfx/pipeline.ts
new file mode 100644
index 0000000000..e78f063a25
--- /dev/null
+++ b/plugins/ruflo-console/hooks/gfx/pipeline.ts
@@ -0,0 +1,84 @@
+/**
+ * Two pictures for the Learning page (ADR-455): the learning pipeline as four stages, and the router's last route. Pure
+ * functions of the models in data/pipeline.ts and a size; each returns a grid of exactly the size asked for. A stale stage
+ * is drawn dim, an absent one dim with n/a: no colour here means a number the console did not read.
+ */
+import { stageNote, type PipeStage, type RouteModel, type RouteOwner } from '../data/pipeline'
+import { COLOR, Grid, ramp } from './raster'
+
+export const PIPELINE_ROWS = 5
+
+const compact = (count: number): string => (count >= 10_000 ? `${(count / 1000).toFixed(1)}k` : String(count))
+
+/** RETRIEVE → JUDGE → DISTILL → CONSOLIDATE: a box per stage with its count and how old its source is; stale and absent stages dim. */
+export function pipelineDiagram(stages: readonly PipeStage[], columns: number): Grid {
+ const grid = new Grid(columns, PIPELINE_ROWS)
+ const n = Math.max(1, stages.length)
+ const gap = columns >= 41 ? 3 : 1
+ const box = Math.max(4, Math.floor((columns - (n - 1) * gap) / n))
+ const inner = box - 2
+ const cell = (text: string): string => text.slice(0, inner).padEnd(inner)
+
+ stages.forEach((stage, i) => {
+ const x0 = i * (box + gap)
+ const lit = stage.state === 'live'
+ const edge = lit ? COLOR.line : COLOR.dim
+ const count = stage.count === null ? 'n/a' : compact(stage.count)
+
+ grid.text(x0, 0, `╭${'─'.repeat(inner)}╮`, edge)
+ grid.text(x0, 1, `│${cell(stage.name)}│`, lit ? COLOR.accent : COLOR.dim)
+ grid.text(x0, 2, `│${count.padStart(inner).slice(-inner)}│`, lit ? ramp(0.7) : COLOR.dim)
+ grid.text(x0, 3, `│${cell(stageNote(stage))}│`, stage.state === 'stale' ? COLOR.warn : COLOR.dim)
+ grid.text(x0, 4, `╰${'─'.repeat(inner)}╯`, edge)
+
+ // The arrow into a stage is as dim as the stage: learning does not flow into something that is not measured.
+ if (i > 0) grid.text(x0 - gap, 2, gap === 3 ? '──▶' : '▶', lit ? COLOR.line : COLOR.dim)
+ })
+
+ return grid
+}
+
+const OWNER_WORDS: Record<RouteOwner, { text: string; color: number }> = {
+ mods: { text: 'ruflo-mods routes in-process', color: COLOR.ok },
+ classic: { text: 'the classic hook-handler routes; ruflo-mods stands down', color: COLOR.info },
+ unseated: { text: 'ruflo-mods not seated: no in-process route', color: COLOR.dim },
+}
+
+/** Rows the route picture needs: the owner line, one per candidate (at most five), and the source line. */
+export const routeRows = (model: RouteModel): number => 2 + Math.max(1, Math.min(5, model.candidates.length))
+
+/** The last route: who owns routing, then each candidate with a confidence bar, the pick first and brightest. */
+export function routePicture(model: RouteModel, columns: number): Grid {
+ const rows = routeRows(model)
+ const grid = new Grid(columns, rows)
+ const owner = OWNER_WORDS[model.owner]
+ const shown = model.candidates.slice(0, 5)
+ const bar = Math.max(6, Math.min(24, columns - 34))
+
+ grid.text(0, 0, `â—† ${owner.text}`, owner.color)
+
+ if (shown.length === 0) grid.text(2, 1, 'no route recorded yet', COLOR.dim)
+
+ shown.forEach((candidate, i) => {
+ const y = 1 + i
+ const filled = candidate.confidence === null ? 0 : Math.round(candidate.confidence * bar)
+ const color = i === 0 ? COLOR.accent : COLOR.info
+
+ grid.text(0, y, i === 0 ? 'â–¸' : ' ', COLOR.accent)
+ grid.text(2, y, candidate.agent.slice(0, 18).padEnd(18), i === 0 ? 0xd0d0d0 : COLOR.dim)
+ grid.text(21, y, 'â–ˆ'.repeat(filled), color)
+ grid.text(21 + filled, y, 'â–‘'.repeat(bar - filled), COLOR.line)
+ grid.text(22 + bar, y, candidate.confidence === null ? 'n/a' : `${Math.round(candidate.confidence * 100)}%`, i === 0 ? COLOR.accent : COLOR.dim)
+ })
+
+ const source =
+ model.source === 'router-query'
+ ? `from your route query ${model.asked ?? ''} · a prior, not a calibrated probability`
+ : model.source === 'mods'
+ ? `${model.matched === true ? 'keyword match' : 'no match, default'} · only the winner is stored; runners-up need a route query`
+ : 'run a route query in the Learning Lab to see candidates'
+
+ grid.text(0, rows - 1, source.slice(0, columns), COLOR.dim)
+
+ return grid
+}
diff --git a/plugins/ruflo-console/hooks/views/learning.ts b/plugins/ruflo-console/hooks/views/learning.ts
index 4b3fb7f3c9..3e17c4006d 100644
--- a/plugins/ruflo-console/hooks/views/learning.ts
+++ b/plugins/ruflo-console/hooks/views/learning.ts
@@ -3,11 +3,23 @@ import type { RenderElement } from 'claude-code'
import type { Intelligence } from '../data/cli'
import { ago, col, count, kv, live, pct, picture, row, section, sourceLine, starts, text, THEME, type Ctx } from './common'
import { stagesOf } from './frames'
+import { CARD_COLUMNS, hasCards } from './card'
+import { pipeStagesOf, routeModelOf, stageNote } from '../data/pipeline'
+import { pipelineDiagram, routePicture } from '../gfx/pipeline'
+import type { Grid } from '../gfx/raster'
import { settingsOf } from '../settings'
import { resultRows } from './automate'
import { pulseRows } from './learning-pulse'
import { neuralActionRows } from './neural'
+/** A picture drawn here from the real state (the registry in frames.ts is not touched): the grid when the terminal has Raster, else its words. */
+function drawn(ctx: Ctx, key: string, grid: Grid, fallback: string): RenderElement {
+ return ctx.kit.Raster === undefined ? text(ctx, fallback, { dimColor: true }) : ctx.kit.Raster(grid.toRaster(key))
+}
+
+/** The width a picture is drawn to: a page in cards is narrower by the border and padding, as in frames.ts. */
+const pictureWidth = (ctx: Ctx): number => Math.max(20, Math.min(200, hasCards(ctx.columns) ? ctx.columns - CARD_COLUMNS : ctx.columns))
+
/** The two switches that decide whether ruflo learns at all, folded away: each is a confirm-gated `ruflo config set`. */
function configRows(ctx: Ctx): RenderElement[] {
const core = settingsOf(ctx.state).core
@@ -69,6 +81,10 @@ export function learningView(ctx: Ctx): RenderElement {
const classicOwnsRoute = owned !== undefined && !owned.includes('route')
const lastOutcomeMs = outcomes?.points[outcomes.points.length - 1]?.atMs
const staleOutcomes = lastOutcomeMs !== undefined && nowMs - lastOutcomeMs > 24 * 3_600_000
+ const routeModel = routeModelOf({ seated: state.ruflo.snapshot !== null, classicOwnsRoute, route, lab: state.lab.result })
+ const routeFallback = `route: ${routeModel.owner} owns routing · ${routeModel.candidates.map(c => `${c.agent} ${c.confidence === null ? 'n/a' : pct(c.confidence)}`).join(' · ') || 'no route recorded'}`
+ // Each stage's age is its source's own timestamp; CONSOLIDATE's counter has none, so its age is n/a and it is never dimmed for age.
+ const pipeStages = pipeStagesOf(stagesOf(state), { RETRIEVE: neural?.lastAdaptationMs, JUDGE: lastOutcomeMs, DISTILL: neural?.lastAdaptationMs }, nowMs)
const routerRows: RenderElement[] = [
kv(
ctx,
@@ -89,6 +105,7 @@ export function learningView(ctx: Ctx): RenderElement {
: `${outcomes.successes}/${outcomes.total} succeeded (${pct(outcomes.successes / outcomes.total)} success rate, N=${outcomes.total}) · last ${ago(lastOutcomeMs, nowMs)}${staleOutcomes ? ' · nothing recorded since' : ''}`,
outcomes !== null && outcomes.total > 0 ? (staleOutcomes ? THEME.warn : THEME.info) : undefined,
),
+ drawn(ctx, 'route', routePicture(routeModel, pictureWidth(ctx)), routeFallback),
picture(ctx, 'curve', `running success rate over ${outcomes?.total ?? 0} outcomes`),
text(ctx, 'running success rate of routed tasks, oldest left (router accuracy over N outcomes); new outcomes draw in', { dimColor: true }),
kv(
@@ -100,8 +117,9 @@ export function learningView(ctx: Ctx): RenderElement {
),
]
const pipelineRows: RenderElement[] = [
- picture(ctx, 'pipeline', stagesOf(state).map(stage => `${stage.name} ${stage.count ?? 'n/a'}`).join(' → ')),
- ...stagesOf(state).map(stage => text(ctx, ` ${stage.name.toLowerCase()}: ${stage.source}`, { dimColor: true })),
+ drawn(ctx, 'pipeline-stages', pipelineDiagram(pipeStages, pictureWidth(ctx)), pipeStages.map(stage => `${stage.name} ${stage.count ?? 'n/a'} (${stageNote(stage)})`).join(' → ')),
+ ...stagesOf(state).map((stage, i) => text(ctx, ` ${stage.name.toLowerCase()}: ${stage.source} · ${stageNote(pipeStages[i] as (typeof pipeStages)[number])}`, { dimColor: true })),
+ text(ctx, ` a stage dims when its source has gained nothing for 24h; CONSOLIDATE has no timestamp, so its age is n/a`, { dimColor: true }),
picture(ctx, 'patterns', `patterns since load: ${state.history.patterns.map(sample => sample.value).join(' ') || 'n/a'}`),
]
const sonaRows: RenderElement[] = [
@@ -121,7 +139,7 @@ export function learningView(ctx: Ctx): RenderElement {
]
const rows: RenderElement[] = [
...section(ctx, 'learn-router', 'Router', 'ruflo-mods · routing-outcomes.json', routerRows, true),
- ...section(ctx, 'learn-pipeline', 'Pipeline', 'RETRIEVE → JUDGE → DISTILL → CONSOLIDATE', pipelineRows, false),
+ ...section(ctx, 'learn-pipeline', 'Pipeline', 'RETRIEVE → JUDGE → DISTILL → CONSOLIDATE', pipelineRows, true),
...section(ctx, 'learn-sona', 'SONA · ReasoningBank', 'neural/stats.json', sonaRows, false),
]
diff --git a/plugins/ruflo-console/tests/pipeline.spec.ts b/plugins/ruflo-console/tests/pipeline.spec.ts
new file mode 100644
index 0000000000..1e70407402
--- /dev/null
+++ b/plugins/ruflo-console/tests/pipeline.spec.ts
@@ -0,0 +1,156 @@
+/** The learning pipeline diagram and the router picture (ADR-455): staleness is a clock rule, nothing is drawn that was not read. */
+import { describe, expect, it } from 'vitest'
+
+import { candidatesFromLines, pipeStagesOf, routeModelOf, routeOwnerOf, stageNote, stageStateOf, STALE_AFTER_MS } from '../hooks/data/pipeline'
+import { pipelineDiagram, routePicture, routeRows } from '../hooks/gfx/pipeline'
+import { COLOR, type Grid } from '../hooks/gfx/raster'
+import { newState } from '../hooks/state'
+import type { Ctx } from '../hooks/views/common'
+import { learningView } from '../hooks/views/learning'
+
+const NOW = 100 * 86_400_000
+const HOUR = 3_600_000
+const rowText = (grid: Grid, y: number): string => Array.from({ length: grid.columns }, (_, x) => String.fromCodePoint(grid.glyph(x, y))).join('')
+const fg = (grid: Grid, x: number, y: number): number => grid.cells[(y * grid.columns + x) * 3 + 1] as number
+
+describe('stage staleness', () => {
+ it('is absent without a count, live without a timestamp, stale only past 24h', () => {
+ expect(stageStateOf(null, NOW, NOW).state).toBe('absent')
+ expect(stageStateOf(5, null, NOW)).toEqual({ state: 'live', ageMs: null })
+ expect(stageStateOf(5, NOW - STALE_AFTER_MS, NOW).state).toBe('live')
+ expect(stageStateOf(5, NOW - STALE_AFTER_MS - 1, NOW).state).toBe('stale')
+ expect(stageStateOf(0, NOW - HOUR, NOW).state).toBe('live')
+ expect(stageStateOf(5, NOW + HOUR, NOW)).toEqual({ state: 'live', ageMs: 0 })
+ })
+
+ it('words each state', () => {
+ const [a, b, c, d] = pipeStagesOf(
+ [{ name: 'A', count: 3 }, { name: 'B', count: 3 }, { name: 'C', count: 3 }, { name: 'D', count: null }],
+ { A: NOW - 3 * HOUR, B: NOW - 8 * 86_400_000 },
+ NOW,
+ )
+
+ expect([a, b, c, d].map(stage => stageNote(stage!))).toEqual(['3h ago', 'stale 8d', 'age n/a', 'no data'])
+ })
+})
+
+describe('the pipeline diagram', () => {
+ const stages = pipeStagesOf([{ name: 'RETRIEVE', count: 32_253 }, { name: 'JUDGE', count: 9 }, { name: 'DISTILL', count: 7 }, { name: 'CONSOLIDATE', count: null }], { RETRIEVE: NOW - HOUR, JUDGE: NOW - 9 * 86_400_000, DISTILL: NOW - HOUR }, NOW)
+
+ it('draws four stages with the real counts, in order', () => {
+ const grid = pipelineDiagram(stages, 80)
+
+ expect(rowText(grid, 1)).toMatch(/RETRIEVE.*JUDGE.*DISTILL.*CONSOLIDA/)
+ expect(rowText(grid, 2)).toMatch(/32\.3k.*9.*7.*n\/a/)
+ expect(rowText(grid, 3)).toContain('stale 9d')
+ expect(rowText(grid, 2)).toContain('──▶')
+ })
+
+ it('dims a stale stage and an absent one, and leaves a live one lit', () => {
+ const grid = pipelineDiagram(stages, 80)
+ const at = (name: string) => rowText(grid, 1).indexOf(name)
+
+ expect(fg(grid, at('RETRIEVE'), 1)).toBe(COLOR.accent)
+ expect(fg(grid, at('JUDGE'), 1)).toBe(COLOR.dim)
+ expect(fg(grid, at('CONSOLIDA'), 1)).toBe(COLOR.dim)
+ expect(fg(grid, at('JUDGE') - 1, 0)).toBe(COLOR.dim)
+ })
+
+ it('keeps its size on a narrow pane', () => {
+ const grid = pipelineDiagram(stages, 24)
+
+ expect(grid.columns).toBe(24)
+ expect(rowText(grid, 0).trimEnd().length).toBeLessThanOrEqual(24)
+ })
+})
+
+describe('the route model', () => {
+ const route = { agent: 'coder', confidence: 0.72, matched: true, reason: 'keyword' }
+
+ it('names who owns routing', () => {
+ expect(routeOwnerOf(false, false)).toBe('unseated')
+ expect(routeOwnerOf(true, true)).toBe('classic')
+ expect(routeOwnerOf(true, false)).toBe('mods')
+ })
+
+ it('reads the pick and the runners-up from a Lab route result', () => {
+ expect(candidatesFromLines(['→ coder · 87% · semantic · pattern x', ' or reviewer · 9%', ' or tester', 'because'])).toEqual([
+ { agent: 'coder', confidence: 0.87 },
+ { agent: 'reviewer', confidence: 0.09 },
+ { agent: 'tester', confidence: null },
+ ])
+ expect(candidatesFromLines(['no json here'])).toEqual([])
+ expect(candidatesFromLines(['→ x · 900%'])[0]?.confidence).toBe(1)
+ })
+
+ it('prefers a route query with candidates, else the mod pick, else says none', () => {
+ const lab = { id: 'nn-route', label: 'which agent for "fix"', lines: ['→ coder · 80%', ' or tester · 10%'] }
+
+ expect(routeModelOf({ seated: true, classicOwnsRoute: false, route, lab })).toMatchObject({ source: 'router-query', candidates: [{ agent: 'coder' }, { agent: 'tester' }] })
+ expect(routeModelOf({ seated: true, classicOwnsRoute: false, route, lab: { ...lab, id: 'nn-status' } })).toMatchObject({ source: 'mods', candidates: [{ agent: 'coder', confidence: 0.72 }], matched: true })
+ expect(routeModelOf({ seated: true, classicOwnsRoute: true, route: null, lab: null })).toMatchObject({ source: 'none', owner: 'classic', candidates: [] })
+ })
+})
+
+describe('the route picture', () => {
+ it('draws each candidate with a bar and its percentage, the pick first', () => {
+ const model = routeModelOf({ seated: true, classicOwnsRoute: false, route: null, lab: { id: 'nn-route', label: 'q', lines: ['→ coder · 80%', ' or tester · 10%'] } })
+ const grid = routePicture(model, 90)
+
+ expect(grid.rows).toBe(routeRows(model))
+ expect(rowText(grid, 0)).toContain('ruflo-mods routes in-process')
+ expect(rowText(grid, 1)).toMatch(/â–¸ coder\s+â–ˆ+â–‘*\s+80%/)
+ expect(rowText(grid, 2)).toMatch(/tester\s+â–ˆ+â–‘+\s+10%/)
+ })
+
+ it('says the classic hook owns routing and that nothing is recorded, without inventing a pick', () => {
+ const grid = routePicture(routeModelOf({ seated: true, classicOwnsRoute: true, route: null, lab: null }), 90)
+
+ expect(rowText(grid, 0)).toContain('classic hook-handler routes')
+ expect(rowText(grid, 1)).toContain('no route recorded yet')
+ expect(rowText(grid, 1)).not.toContain('â–ˆ')
+ })
+})
+
+describe('the Learning page', () => {
+ type El = { kind: string; props: Record<string, unknown> }
+ const make = (kind: string) => (props: Record<string, unknown>): El => ({ kind, props })
+ const act = new Proxy({}, { get: () => () => undefined }) as unknown as Ctx['act']
+ const flat = (node: unknown): El[] => {
+ if (Array.isArray(node)) return node.flatMap(flat)
+ if (typeof node !== 'object' || node === null) return []
+ const el = node as El
+ const children = el.props.children
+
+ return [el, ...(Array.isArray(children) ? children.flatMap(flat) : flat(children))]
+ }
+
+ function page(kit: Record<string, unknown>) {
+ const state = newState({ boot: false })
+
+ state.snapshot = { outcomes: { total: 9, successes: 9, points: [{ ok: true, atMs: NOW - 9 * 86_400_000 }] }, router: null, neural: { trajectories: 12, patterns: 3, lastAdaptationMs: NOW - HOUR }, sona: null } as never
+ state.ruflo = { ...state.ruflo, snapshot: { owned: [] } as never, route: null } as never
+
+ return flat(learningView({ kit, state, act, columns: 130, nowMs: NOW, pictures: new Map() } as unknown as Ctx))
+ }
+
+ it('falls back to words where there is no Raster, still naming the stale stage and the owner', () => {
+ const text = page({ Box: make('Box'), Text: make('Text'), Button: make('Button'), Input: make('Input') })
+ .filter(el => el.kind === 'Text')
+ .map(el => String(el.props.children))
+ .join('\n')
+
+ expect(text).toContain('JUDGE 9 (stale 9d)')
+ expect(text).toContain('RETRIEVE 12 (1h ago)')
+ expect(text).toContain('classic owns routing')
+ })
+
+ it('draws both pictures as rasters where the terminal has one', () => {
+ const keys = page({ Box: make('Box'), Text: make('Text'), Button: make('Button'), Input: make('Input'), Raster: make('Raster') })
+ .filter(el => el.kind === 'Raster')
+ .map(el => el.props.key)
+
+ expect(keys).toContain('pipeline-stages')
+ expect(keys).toContain('route')
+ })
+})
diff --git a/v3/docs/adr/ADR-455-mind-pipeline-router.md b/v3/docs/adr/ADR-455-mind-pipeline-router.md
new file mode 100644
index 0000000000..2c6c1ff835
--- /dev/null
+++ b/v3/docs/adr/ADR-455-mind-pipeline-router.md
@@ -0,0 +1,38 @@
+# ADR 455: The learning pipeline diagram and the router picture
+
+Status: Accepted
+
+Date: 2026-10-05
+
+Builds on: ADR-404 (ruflo as a mod; who owns `route`), the Learning page's pipeline and Router blocks
+
+## 1. Context
+
+The Learning page printed the four pipeline stages as one line of text and the router's last pick as a sentence. Two things a person wants were not visible: which stage has stopped learning, and what the router considered besides its winner. The console already reads every number needed; this adds pictures, not probes.
+
+## 2. Decision
+
+**Pipeline diagram.** `gfx/pipeline.ts` draws RETRIEVE, JUDGE, DISTILL, CONSOLIDATE as four boxes with the counts `stagesOf` already returns (trajectories, routed outcomes, patterns learned, EWC consolidations) and a note line with the age of the source.
+
+**Staleness** (`data/pipeline.ts`, `STALE_AFTER_MS`): a stage is *stale* when its source has a timestamp and that timestamp is more than 24 h old (the threshold the Router block already uses for routed outcomes). Timestamps used: RETRIEVE and DISTILL, `neural/stats.json` `lastAdaptationMs`; JUDGE, the newest point of `routing-outcomes.json`. CONSOLIDATE's counter comes from a fresh `hooks_intelligence_stats` process and has no timestamp, so its age is "n/a" and it is never dimmed for age (an unknown age is not read as old). A stage with no count is *absent*: dim, "n/a". A stale or absent stage is drawn dim, and so is the arrow into it; a stale note is amber so the reason stays readable.
+
+**Router picture.** Candidates with confidence bars, the pick first, under one line saying who owns routing: the mod, the classic hook-handler (`classicOwnsRoute`, reused unchanged from the view), or ruflo-mods not seated. Two real sources, in priority order:
+1. the person's last Lab `nn-route` result (from `hooks route --format json`), which carries runner-ups; parsed from its printed lines (`→ agent · N%`, ` or agent · N%`);
+2. ruflo-mods' in-process `lastRoute`, which stores only the winner, so one bar and a line saying runner-ups need a route query.
+With neither, the picture says no route is recorded. No candidate is ever invented.
+
+The view draws both pictures itself from live state (`drawn()` in `views/learning.ts`) instead of through the `picturesOf` registry in `views/frames.ts`, which this change does not touch. Where the terminal has no `Raster`, the same facts print as text.
+
+## 3. Consequences
+
+- Reading the route lines couples the picture to the Lab's line format (`neural.ts` `routeRead`); a format change yields no candidates and the mod pick or the empty state is shown, never a wrong bar. The coupling is covered by a test.
+- Nothing new is read, spent or written. The page still has no mutation here.
+- `frames.ts` still builds the older `pipeline` picture, now unused by Learning; the integrator can drop it.
+
+## 4. Test and benchmark plan
+
+`tests/pipeline.spec.ts`: staleness boundaries (exactly 24 h is live, past it stale, absent, unknown age, future timestamp), notes, diagram text and dimming by cell colour, narrow width, owner words, route-line parsing (clamps, missing percent, non-route text), source priority, bars and the empty state, and the page both with and without `Raster`. Pure functions, no I/O; each drawing is a 5-row grid, so cost is negligible and no benchmark is needed.
+
+## 5. Rollback
+
+Remove `gfx/pipeline.ts`, `data/pipeline.ts` and the spec, and restore `views/learning.ts` (the `picture(ctx, 'pipeline', ...)` call and the sentence-only route). No state, command or file format depends on them.