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): wire the Workflows page (ADR-464): view, nav, menu, live refresh, keys, slot seams

ruvdab6c087cb33
diff --git a/plugins/ruflo-console/hooks/ask-claude.ts b/plugins/ruflo-console/hooks/ask-claude.ts
index c12d85aed8..7a2e312d5b 100644
--- a/plugins/ruflo-console/hooks/ask-claude.ts
+++ b/plugins/ruflo-console/hooks/ask-claude.ts
@@ -23,6 +23,7 @@ export const VIEW_ASK: Record<ViewId, ViewAsk> = {
missions: { default: 'Review this mission: is the plan sound, and what should I do next?' },
overview: { default: 'Summarise the state of this ruflo project and what needs attention.', slash: 'ruflo-core:ruflo-status' },
swarm: { default: 'Is this swarm healthy and well shaped for its work? What would you change?', slash: 'ruflo-swarm:swarm' },
+ workflows: { default: 'Read these workflow runs and the ruflo swarm: what is stuck, failing or costing the most tokens, and what should I do about it?', slash: 'ruflo-workflows:workflow' },
hive: { default: 'Read the hive: quorum, votes and workers. What should the queen decide next?', slash: 'ruflo-swarm:swarm' },
claims: { default: 'Which claims look stuck or unbalanced, and which should be released, handed off or stolen?' },
federation: { default: 'Is this federation set up safely? Which peers should I trust, and what is missing?', slash: 'ruflo-federation:federation' },
diff --git a/plugins/ruflo-console/hooks/bindings.ts b/plugins/ruflo-console/hooks/bindings.ts
index 9d3b15f26b..b42e0a96fa 100644
--- a/plugins/ruflo-console/hooks/bindings.ts
+++ b/plugins/ruflo-console/hooks/bindings.ts
@@ -12,6 +12,7 @@ import { navActions } from './nav-state'
import { roomActions } from './room'
import { roomPages } from './views/room'
import { watchActions } from './watch'
+import { workflowsActions } from './wf-actions'
import { missionActions } from './mission-control'
import { catalogActions } from './plugin-catalog'
import { saveAllowed } from './remember'
@@ -63,6 +64,10 @@ export function actionsOf(state: State, host: Host, runner: Runner, steps: Steps
/** j/k: what moves depends on the view in front. */
function select(by: number): void {
const view = state.view
+
+ // The Workflows page keeps its own cursor (run, phase, agent): /ruflo next and prev move it as j and k do.
+ if (view === 'workflows') return actions.workflows.key(by > 0 ? 'j' : 'k')
+
const key = view === 'claims' ? 'claim' : view === 'swarm' || view === 'timeline' || view === 'agent' ? 'agent' : 'item'
state.select[key] += by
@@ -380,6 +385,7 @@ export function actionsOf(state: State, host: Host, runner: Runner, steps: Steps
host.invalidate()
},
},
+ workflows: workflowsActions(state, host, runner),
devtools: devtoolsActions(state, host, runner.runById, why => runner.ask(null, why)),
}
diff --git a/plugins/ruflo-console/hooks/commands.ts b/plugins/ruflo-console/hooks/commands.ts
index 96ac80963b..e77b5df495 100644
--- a/plugins/ruflo-console/hooks/commands.ts
+++ b/plugins/ruflo-console/hooks/commands.ts
@@ -129,6 +129,7 @@ export const HELP = [
'Pane keys (while it holds the keyboard: /ruflo opens it with the keys, or click it; ctrl+x tab reaches the band, not the pane)',
' 0 main menu · 1-9 views · g timeline · q approvals · e events · m plugin catalog · w x.ruv.io · i terminal · p palette · x actions for the selection',
' terminal: the field takes the keys; /codex /claude /swarm /ruflo switch harness, /new starts over · sessions remember the conversation per project; the first message asks, then Enter sends · Tab to s stop, o new, z clear',
+ ' workflows (no key; nav SWARM, menu, or /ruflo workflows): j/k move · b/l phases or agents column · u/i switch run · d inspect · /ruflo next|prev = j/k',
' j/k select · d drill in · b back · r refresh · h help · f event filter · y/n confirm',
' Esc: a pane /ruflo opened closes; one that opened by itself (panel=auto) only hands the keys back. ✕ or /ruflo close closes either',
' (? and Enter cannot be pane hotkeys in this Claude Code build: use h, and d to drill in)',
diff --git a/plugins/ruflo-console/hooks/controller.ts b/plugins/ruflo-console/hooks/controller.ts
index 0b30af4a44..eb79396eb2 100644
--- a/plugins/ruflo-console/hooks/controller.ts
+++ b/plugins/ruflo-console/hooks/controller.ts
@@ -30,6 +30,7 @@ import { BOOT_MIN_MS, CLI_PREFIXES, isBooting, NAV_KEY, NAV_STYLES, PANE_ID, pus
import type { Actions } from './views/common'
import { picturesOf } from './views/frames'
import { pulseDue } from './pulse'
+import { refreshWorkflows } from './wf-live'
const ACTIVITY_BUCKET_MS = 5_000
const PANE_WATCH_MS = 1_000
@@ -328,6 +329,7 @@ export function createController(state: State, host: Host): Controller {
lastIdleMs = now
void refresh().then(() => {
void probe()
+ void refreshWorkflows(state, host)
advance(state, host)
})
}
diff --git a/plugins/ruflo-console/hooks/data/wf-clean.ts b/plugins/ruflo-console/hooks/data/wf-clean.ts
new file mode 100644
index 0000000000..a54dce502b
--- /dev/null
+++ b/plugins/ruflo-console/hooks/data/wf-clean.ts
@@ -0,0 +1,33 @@
+/**
+ * The last wash a run gets before the page, a notice or a slot sees it (ADR-464). The parsers already drop control
+ * characters from file text; this adds the credential mask to every free-text field (labels, phase titles, models,
+ * the last tool, a result preview), so a token a prompt or a result carried can reach no cell, log line or notice.
+ * Ids, paths and numbers are left alone: a session id is 36 characters of `[0-9a-f-]` and would read as a key to the mask.
+ */
+import { maskSecrets, type WfAgent, type WfPhase, type WfRun } from './workflows'
+
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/g
+
+/** Free text for a cell or a notice: control characters (an ANSI escape drives a terminal) become spaces, credentials are masked. */
+export const cleanText = (value: string): string => maskSecrets(value.replace(CONTROL, ' '))
+
+const opt = (value: string | undefined): string | undefined => (value === undefined ? undefined : cleanText(value))
+
+function cleanAgent(agent: WfAgent): WfAgent {
+ const model = opt(agent.model)
+ const preview = opt(agent.resultPreview)
+ const tool = opt(agent.lastTool)
+
+ const ruflo = agent.ruflo === undefined ? undefined : { ...agent.ruflo, ...(agent.ruflo.name !== undefined && { name: cleanText(agent.ruflo.name) }), type: cleanText(agent.ruflo.type) }
+
+ return { ...agent, ...(ruflo !== undefined && { ruflo }), label: cleanText(agent.label), phase: cleanText(agent.phase), ...(model !== undefined && { model }), ...(preview !== undefined && { resultPreview: preview }), ...(tool !== undefined && { lastTool: tool }) }
+}
+
+function cleanPhase(phase: WfPhase): WfPhase {
+ const detail = opt(phase.detail)
+
+ return { ...phase, title: cleanText(phase.title), ...(detail !== undefined && { detail }), agents: phase.agents.map(cleanAgent) }
+}
+
+export const cleanRun = (run: WfRun): WfRun => ({ ...run, name: cleanText(run.name), phases: run.phases.map(cleanPhase) })
diff --git a/plugins/ruflo-console/hooks/dispatch.ts b/plugins/ruflo-console/hooks/dispatch.ts
index cf808da69a..2959bed431 100644
--- a/plugins/ruflo-console/hooks/dispatch.ts
+++ b/plugins/ruflo-console/hooks/dispatch.ts
@@ -8,6 +8,7 @@ import { CATALOG_PATH, commandsText, FALLBACK, parseCatalog, type Catalog } from
import type { Controller } from './controller'
import { plain } from './data/parse'
import { loadEvolve } from './evolve'
+import { refreshWorkflows } from './wf-live'
import { labAnswer } from './mh-lab'
import { skillsAnswer } from './skills-lab'
import { VIEWS, type State } from './state'
@@ -65,6 +66,7 @@ async function dumpOf(control: Controller, state: State, view: State['view']): P
await Promise.race([control.probe(true), new Promise(resolve => setTimeout(resolve, DUMP_WAIT_MS))])
// Self-Evolution draws from its own file read, which opening the view starts: a dump waits for it too.
if (view === 'evolve') await loadEvolve(state, control.host)
+ if (view === 'workflows') await refreshWorkflows(state, control.host, true)
return viewText({ state, nowMs: Date.now(), columns: 100, act: control.actions }, view)
} finally {
diff --git a/plugins/ruflo-console/hooks/gfx/boot.ts b/plugins/ruflo-console/hooks/gfx/boot.ts
index 1a54ab995d..c7c0353ea4 100644
--- a/plugins/ruflo-console/hooks/gfx/boot.ts
+++ b/plugins/ruflo-console/hooks/gfx/boot.ts
@@ -33,6 +33,7 @@ export const BOOT_MODULES: readonly { name: string; note: string }[] = [
{ name: 'Missions', note: 'goal → SPARC plan → tasks' },
{ name: 'Overview', note: 'subsystems, health, Optimizer' },
{ name: 'Swarm', note: 'topology, agents, tasks' },
+ { name: 'Workflows', note: 'Claude Code runs and the swarm' },
{ name: 'Hive-Mind', note: 'queen, workers, votes, quorum' },
{ name: 'Claims', note: 'one owner per resource' },
{ name: 'Approvals', note: 'votes and asks in one place' },
diff --git a/plugins/ruflo-console/hooks/help-docs.ts b/plugins/ruflo-console/hooks/help-docs.ts
index 179de655be..cf04a21ccd 100644
--- a/plugins/ruflo-console/hooks/help-docs.ts
+++ b/plugins/ruflo-console/hooks/help-docs.ts
@@ -44,6 +44,7 @@ export const VIEW_TOPIC: Partial<Record<ViewId, string>> = {
missions: 'mission',
overview: 'setup',
swarm: 'swarm',
+ workflows: 'swarm',
hive: 'hive',
claims: 'claims',
approvals: 'approvals',
diff --git a/plugins/ruflo-console/hooks/nav-state.ts b/plugins/ruflo-console/hooks/nav-state.ts
index 38780fdff8..1d2dcae2e9 100644
--- a/plugins/ruflo-console/hooks/nav-state.ts
+++ b/plugins/ruflo-console/hooks/nav-state.ts
@@ -8,7 +8,7 @@ import { VIEWS, type State, type ViewId } from './state'
/** The nav's groups, the main menu's own, each in rows short enough to spell their names: every view but the menu is in exactly one. */
export const NAV_GROUPS: readonly { title: string; icon: string; rows: readonly (readonly ViewId[])[] }[] = [
- { title: 'SWARM', icon: '🐝', rows: [['missions', 'overview', 'swarm', 'hive', 'claims', 'approvals']] },
+ { title: 'SWARM', icon: '🐝', rows: [['missions', 'overview', 'swarm', 'workflows'], ['hive', 'claims', 'approvals']] },
{ title: 'MIND', icon: '🧠', rows: [['learning', 'neural', 'metaharness', 'evolve', 'memory', 'vector']] },
{ title: 'SAFETY', icon: '🛡️', rows: [['secure', 'cost', 'perf', 'timeline', 'events', 'room']] },
{ title: 'NETWORK', icon: '🌐', rows: [['federation', 'xruv', 'sandbox', 'skills', 'market']] },
diff --git a/plugins/ruflo-console/hooks/self-check.ts b/plugins/ruflo-console/hooks/self-check.ts
index 1f7b0a249e..7c3696b795 100644
--- a/plugins/ruflo-console/hooks/self-check.ts
+++ b/plugins/ruflo-console/hooks/self-check.ts
@@ -19,14 +19,14 @@ export type CheckResult = { area: string; ok: boolean; checked: number; problems
/** 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',
+ Missions: 'missions', Overview: 'overview', Swarm: 'swarm', Workflows: 'workflows', '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', Sandbox: 'sandbox', 'Cost & Budget': 'cost', Timeline: 'timeline', Events: 'events', 'The Room': 'room', Performance: 'perf', 'AI Terminal': 'terminal', Settings: 'settings',
}
/** Pages with no hotkey on purpose (every letter is taken): reached from the menu, the nav, the palette or by name. */
-const NAMED_ONLY: ReadonlySet<string> = new Set(['sandbox', 'room'])
+const NAMED_ONLY: ReadonlySet<string> = new Set(['sandbox', 'room', 'workflows'])
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 }
diff --git a/plugins/ruflo-console/hooks/state.ts b/plugins/ruflo-console/hooks/state.ts
index 6e0e52d04d..be93c78573 100644
--- a/plugins/ruflo-console/hooks/state.ts
+++ b/plugins/ruflo-console/hooks/state.ts
@@ -13,6 +13,7 @@ import { emptyVector, type VectorState } from './data/vector'
import type { Snapshot } from './data/snapshot'
import type { RufloRoute, RufloSnapshot } from '../types'
import type { Notice } from './notices'
+import { emptyWf, type WfState } from './wf-state'
export const PLUGIN_NAME = 'ruflo-console'
export const PANE_ID = 'ruflo-console'
@@ -22,7 +23,7 @@ export type NavStyle = 'auto' | 'icons' | 'brief' | 'full'
export const NAV_STYLES: readonly NavStyle[] = ['auto', 'icons', 'brief', 'full']
export const NAV_KEY = 'nav-style'
-export type ViewId = 'menu' | 'overview' | 'swarm' | 'hive' | 'claims' | 'federation' | 'plugins' | 'learning' | 'metaharness' | 'memory' | 'cost' | 'timeline' | 'approvals' | 'events' | 'room' | 'missions' | 'xruv' | 'terminal' | 'skills' | 'agent' | 'secure' | 'perf' | 'automate' | 'neural' | 'vector' | 'evolve' | 'devtools' | 'sandbox' | 'market' | 'settings'
+export type ViewId = 'menu' | 'overview' | 'swarm' | 'workflows' | 'hive' | 'claims' | 'federation' | 'plugins' | 'learning' | 'metaharness' | 'memory' | 'cost' | 'timeline' | 'approvals' | 'events' | 'room' | 'missions' | 'xruv' | 'terminal' | 'skills' | 'agent' | 'secure' | 'perf' | 'automate' | 'neural' | 'vector' | 'evolve' | 'devtools' | 'sandbox' | 'market' | 'settings'
/**
* The views in tab order, each with its hotkey and the inline height it asks for. Digits are the first nine; the three
@@ -42,6 +43,7 @@ export const VIEWS: readonly { id: ViewId; key: string; label: string; short: st
{ id: 'swarm', key: '3', label: 'Swarm', short: 'Swm', icon: '🐝', blurb: 'the swarm as ruflo wrote it: topology, agents at work, and the hive-mind votes', rows: 30 },
{ id: 'hive', key: 'b', label: 'Hive-Mind', short: 'Hiv', icon: '👑', blurb: 'the queen, her workers and their votes: quorum, fault tolerance, proposals and broadcasts', rows: 40 },
{ id: 'claims', key: '4', label: 'Claims', short: 'Clm', icon: '📌', blurb: 'who holds which task: claim, release, hand off or steal, each after a y/n confirm', rows: 30 },
+ { id: 'workflows', key: '', label: 'Workflows', short: 'Wfl', icon: '🔀', blurb: 'Claude Code workflow runs and the ruflo swarm side by side: phases, agents, tokens, and what each is doing', rows: 34 },
{ id: 'federation', key: '5', label: 'Federation', short: 'Fed', icon: '🌐', blurb: 'this node, its peers, keys and channels, placed by how far each is trusted', rows: 26 },
{ id: 'plugins', key: '6', label: 'Plugins', short: 'Plg', icon: '🧩', blurb: 'ruflo plugins: installed, enabled, in the marketplace clone, and loaded as mods', rows: 30 },
{ id: 'learning', key: '7', label: 'Learning', short: 'Lrn', icon: '🧠', blurb: 'router picks and outcomes, and the RETRIEVE → JUDGE → DISTILL → CONSOLIDATE pipeline', rows: 30 },
@@ -304,6 +306,8 @@ export type State = {
devtools: { fields: DevFields; /** Whether tmux is on this machine, from a probe when the Sandbox page opens. */ tmux: 'unknown' | 'present' | 'missing' }
timers: Map<string, Timer>
stats: { renders: number[]; refreshes: number[]; frames: number[] }
+ /** The Workflows page: the last read of Claude Code's run folders, the cursor, the inspector tab (wf-state.ts). */
+ wf: WfState
/** Claude's control of the console (ADR-444): paused by the person, the call counts, and the log the dashboard shows. */
control: { paused: boolean; calls: number; turnCalls: number; /** Model-driven actions this session, by class (ADR-450 T8 budget). */ used: Record<string, number>; log: ControlEntry[]; /** Until when Claude counts as driving (a tool call extends it): the console does not spend a second Claude turn on guidance meanwhile. */ drivingUntilMs: number; /** True while one of Claude's tool calls is running: a person's "always allow" answer must not let Claude's call skip the level and confirm checks (ADR-444). */ viaModel: boolean }
}
@@ -379,6 +383,7 @@ export function newState(raw: PluginOptions | undefined): State {
devtools: { fields: emptyFields(), tmux: 'unknown' },
timers: new Map(),
stats: { renders: [], refreshes: [], frames: [] },
+ wf: emptyWf(),
control: { paused: false, calls: 0, turnCalls: 0, used: {}, log: [], drivingUntilMs: 0, viaModel: false },
}
}
diff --git a/plugins/ruflo-console/hooks/view-open.ts b/plugins/ruflo-console/hooks/view-open.ts
index e35ee4f726..65f28bdfd3 100644
--- a/plugins/ruflo-console/hooks/view-open.ts
+++ b/plugins/ruflo-console/hooks/view-open.ts
@@ -3,6 +3,7 @@
* closed or hidden console reads nothing; anything that reaches the network or writes waits for a click.
*/
import { loadEvolve } from './evolve'
+import { refreshWorkflows } from './wf-live'
import type { Host } from './host'
import { loadCatalog } from './plugin-catalog'
import { probeTmux } from './sandbox'
@@ -19,6 +20,9 @@ export function openLoaders(state: State, host: Host, view: State['view']): void
// Self-Evolution reads ruflo's own flywheel files (local, no CLI run); its checks wait for a click.
if (view === 'evolve') void loadEvolve(state, host)
+ // Workflows reads Claude Code's run folders (local, read-only) when opened, and again on each refresh while it stays open.
+ if (view === 'workflows') void refreshWorkflows(state, host, true)
+
// The Sandbox page asks whether tmux is here (local, $0): without it the tmux rows say n/a.
if (view === 'sandbox') void probeTmux(state, host)
diff --git a/plugins/ruflo-console/hooks/views/common.ts b/plugins/ruflo-console/hooks/views/common.ts
index 98300c571c..00aa334da0 100644
--- a/plugins/ruflo-console/hooks/views/common.ts
+++ b/plugins/ruflo-console/hooks/views/common.ts
@@ -32,6 +32,7 @@ import type { UpdatesMode } from '../updates'
import { chip, COST_CHIP } from '../menu-colors'
import { accentOfView } from '../nav-state'
import type { VectorActions } from '../vector'
+import type { WorkflowsActions } from '../wf-actions'
export type Kit = Pick<Elements['terminal'], 'Box' | 'Text' | 'Button'> & { Raster?: Elements['terminal']['Raster']; Input?: Elements['terminal']['Input'] }
@@ -120,6 +121,8 @@ export type Actions = {
checkUpdates: () => void
/** Opens or closes a collapsible section (`<view>/<id>`). */
toggle: (key: string) => void
+ /** The Workflows page: cursor keys, the inspector's tab, the confirm-gated ruflo agent verbs, and naming a transcript's path. */
+ workflows: WorkflowsActions
/** Settings: the level, a plugin, an option or ruflo config change (each asks first), AI preferences, and ▸ ask claude/codex. */
settings: SettingsActions
}
diff --git a/plugins/ruflo-console/hooks/views/menu.ts b/plugins/ruflo-console/hooks/views/menu.ts
index 186cc4d9be..729d7b2172 100644
--- a/plugins/ruflo-console/hooks/views/menu.ts
+++ b/plugins/ruflo-console/hooks/views/menu.ts
@@ -24,8 +24,9 @@ export const GROUPS: readonly { title: string; sections: readonly { name: string
{
title: 'SWARM',
sections: [
- { name: 'start here', items: [{ label: 'Missions', go: 'missions' }, { label: 'Overview', go: 'overview' }, { label: 'Swarm Topology', go: 'swarm' }] },
+ { name: 'start here', items: [{ label: 'Missions', go: 'missions' }, { label: 'Overview', go: 'overview' }] },
{ name: 'coordinate', items: [{ label: 'Hive-Mind', go: 'hive' }, { label: 'Claims Board', go: 'claims' }, { label: 'Approvals', go: 'approvals' }] },
+ { name: 'observe', items: [{ label: 'Swarm Topology', go: 'swarm' }, { label: 'Workflows', go: 'workflows' }] },
],
},
{
diff --git a/plugins/ruflo-console/hooks/views/pane.ts b/plugins/ruflo-console/hooks/views/pane.ts
index 82eb0864df..b9ef475c90 100644
--- a/plugins/ruflo-console/hooks/views/pane.ts
+++ b/plugins/ruflo-console/hooks/views/pane.ts
@@ -48,6 +48,7 @@ import { pluginsView } from './plugins'
import { secureResult, secureView } from './secure'
import { skillsView } from './skills'
import { swarmView } from './swarm'
+import { workflowsPage } from './wf-page'
import { terminalView } from './terminal'
import { vectorResult, vectorView } from './vector'
import { xruvView } from './xruv'
@@ -66,6 +67,7 @@ const BODIES: Record<ViewId, (ctx: Ctx) => RenderElement> = {
menu: menuView,
overview: overviewView,
swarm: swarmView,
+ workflows: workflowsPage,
hive: hiveView,
claims: claimsView,
federation: federationView,
diff --git a/plugins/ruflo-console/hooks/views/wf-page.ts b/plugins/ruflo-console/hooks/views/wf-page.ts
new file mode 100644
index 0000000000..35c2096501
--- /dev/null
+++ b/plugins/ruflo-console/hooks/views/wf-page.ts
@@ -0,0 +1,91 @@
+import type { RenderElement } from 'claude-code'
+
+import { plain } from '../data/parse'
+import { cleanText } from '../data/wf-clean'
+import { pick } from '../data/workflows-nav'
+import { workflowsModelOf } from '../wf-live'
+import { ago, button, clip, col, row, rule, text, THEME, type Ctx } from './common'
+import './wf-register'
+import { DETAIL_TAB, slotsFor, type SlotEnv } from './wf-slots'
+import { workflowsView } from './workflows'
+
+/** A slot's own drawing or handler may throw: that costs one line naming the slot, never the page. */
+function guarded<T>(id: string, ctx: Ctx, draw: () => T, fallback: (line: RenderElement) => T): T {
+ try {
+ return draw()
+ } catch (error) {
+ return fallback(text(ctx, `slot ${id} failed: ${cleanText(plain(error instanceof Error ? error.message : String(error), 60))}`, { color: THEME.bad }))
+ }
+}
+
+const press = (run: () => void): (() => void) => () => {
+ try {
+ run()
+ } catch {
+ // A slot's handler that throws changes nothing; the page stays as it was.
+ }
+}
+
+/** The movement and run-switch buttons: j k move, b and l pick the column (h is Help's), u and i switch run (a hotkey is one letter or digit, so not [ and ]), d inspects. */
+function moves(ctx: Ctx, isInspecting: boolean): RenderElement {
+ const act = ctx.act.workflows
+
+ return row(ctx, [
+ button(ctx, 'wf-prev', 'prev', () => act.key('k'), { hotkey: 'k' }),
+ button(ctx, 'wf-next', 'next', () => act.key('j'), { hotkey: 'j' }),
+ button(ctx, 'wf-col-phases', '◂ phases', () => act.key('h'), { hotkey: 'b' }),
+ button(ctx, 'wf-col-agents', 'agents ▸', () => act.key('l'), { hotkey: 'l' }),
+ button(ctx, 'wf-run-prev', '◂ run', () => act.key('['), { hotkey: 'u' }),
+ button(ctx, 'wf-run-next', 'run ▸', () => act.key(']'), { hotkey: 'i' }),
+ button(ctx, 'wf-inspect', isInspecting ? 'Close inspector' : 'Inspect', () => act.key('enter'), { hotkey: 'd' }),
+ ], 'wf-moves')
+}
+
+/**
+ * The Workflows page as the person meets it (ADR-464): the run board (views/workflows.ts), the buttons that move its cursor,
+ * the buttons of any registered key and action slots, the inspector's tabs, then the board slots. Everything a slot draws or does is
+ * guarded; the page reads the folders only while it is open (wf-live.ts) and says so, with how old the read is.
+ */
+export function workflowsPage(ctx: Ctx): RenderElement {
+ const { state, nowMs } = ctx
+ const wf = state.wf
+ const act = ctx.act.workflows
+ const model = workflowsModelOf(state, nowMs)
+ const here = model === null ? null : pick(wf.ui, model.runs)
+ const env: SlotEnv | null = here === null || model === null ? null : { ctx, runs: model.runs, run: here.run, phase: here.phase, agent: here.agent, ui: here.ui, nowMs }
+ const tabs = env === null || !env.ui.isInspecting ? [] : slotsFor('tab').filter(slot => guarded(slot.id, ctx, () => slot.when?.(env) ?? true, () => false))
+ const slotTab = tabs.find(slot => slot.id === wf.tab)
+ const ui = slotTab === undefined ? wf.ui : { ...wf.ui, isInspecting: false }
+ const rows: RenderElement[] = [workflowsView(ctx, model, ui, { ask: spec => act.ask(spec), show: act.show })]
+
+ if (env !== null && env.run !== null && ctx.columns >= 44) {
+ rows.push(moves(ctx, env.ui.isInspecting))
+
+ const extras = [
+ ...slotsFor('key').map(slot => button(ctx, `wf-key-${slot.id}`, slot.label, press(() => slot.run(env)), { hotkey: slot.key })),
+ ...slotsFor('action').map(slot => button(ctx, `wf-act-${slot.id}`, slot.label, press(() => act.ask(slot.spec(env), slot.why)), slot.hotkey === undefined ? {} : { hotkey: slot.hotkey })),
+ ]
+
+ if (extras.length > 0) rows.push(row(ctx, extras, 'wf-extras'))
+
+ // The console reads workflow runs; it has no verb that stops or messages one, so this says where that is done instead of a dead button.
+ if (env.run.kind === 'workflow') rows.push(text(ctx, 'Stop and message belong to Claude Code (its Workflows panel, TaskStop): this page only reads the run.', { dimColor: true }))
+ }
+
+ if (env !== null && tabs.length > 0) {
+ rows.push(row(ctx, [text(ctx, 'tabs'), button(ctx, 'wf-tab-detail', `${slotTab === undefined ? '●' : '○'} detail`, () => act.tab(DETAIL_TAB)), ...tabs.map(slot => button(ctx, `wf-tab-${slot.id}`, `${slot.id === slotTab?.id ? '●' : '○'} ${slot.label}`, () => act.tab(slot.id)))], 'wf-tabs'))
+ if (slotTab !== undefined) rows.push(...guarded(slotTab.id, ctx, () => slotTab.render(env), line => [line]))
+ }
+
+ if (env !== null) {
+ for (const slot of slotsFor('board')) {
+ rows.push(rule(ctx, slot.title))
+ rows.push(...guarded(slot.id, ctx, () => slot.render(env), line => [line]))
+ }
+ }
+
+ if (wf.error !== null) rows.push(text(ctx, `the last read failed (${clip(wf.error, 80)}): showing the read before it`, { color: THEME.warn }))
+ rows.push(text(ctx, wf.readAtMs === 0 ? 'read when this page opens, then on each refresh while it stays open' : `read ${ago(wf.readAtMs, nowMs)} · re-read on each refresh while this page is open, never while it is closed`, { dimColor: true }))
+
+ return col(ctx, rows, 'workflows-page')
+}
diff --git a/plugins/ruflo-console/hooks/views/wf-register.ts b/plugins/ruflo-console/hooks/views/wf-register.ts
new file mode 100644
index 0000000000..9d177e5227
--- /dev/null
+++ b/plugins/ruflo-console/hooks/views/wf-register.ts
@@ -0,0 +1,9 @@
+/**
+ * The one file the merge owner edits to switch a Workflows slot on (ADR-464): each feature that registers slots
+ * (views/wf-slots.ts) is imported here for its side effect, one line apiece, e.g.
+ *
+ * import '../wf-drill'
+ *
+ * Nothing is imported yet: the page draws exactly the board until a feature module is added below.
+ */
+export {}
diff --git a/plugins/ruflo-console/hooks/views/wf-slots.ts b/plugins/ruflo-console/hooks/views/wf-slots.ts
new file mode 100644
index 0000000000..665772b4b3
--- /dev/null
+++ b/plugins/ruflo-console/hooks/views/wf-slots.ts
@@ -0,0 +1,91 @@
+/**
+ * The seams of the Workflows page (ADR-464). A feature that adds to the page registers a slot from its own module and edits
+ * no shared file: the page (views/wf-page.ts) draws whatever is registered, and the band's notice pass (wf-live.ts) asks the
+ * notice slots. Five kinds:
+ *
+ * board extra sections under the run board render(env) -> rows
+ * tab extra tabs in the inspector, beside `detail` render(env) -> rows, shown while the tab is picked
+ * key extra key handlers: a hotkey button run(env), no change to the run
+ * action extra actions: a confirm-gated ruflo verb spec(env) -> the ActionSpec the confirm card shows, or null (then `why` is said)
+ * notice extra notices raised after a read between(prev, next, nowMs) -> drafts (their text is masked here, not by the slot)
+ *
+ * Registering is pure and cheap: a slot that is malformed, takes a hotkey the page or another slot owns, or repeats an id is
+ * refused with a reason (never thrown), so one feature's mistake cannot take the page down. A slot's render or handler that throws
+ * is caught where it is called and drawn as one line naming the slot. A module reaches the registry by being imported from
+ * views/wf-register.ts, the one file the merge owner edits (one import line per feature).
+ */
+import type { RenderElement } from 'claude-code'
+
+import type { ActionSpec } from '../actions'
+import type { WfAgent, WfPhase, WfRun } from '../data/workflows'
+import type { WfUi } from '../data/workflows-nav'
+import type { NoticeDraft } from '../notices'
+import type { Ctx } from './common'
+
+/** What a slot is handed: the frame's context, the page's model and where the cursor is. `run`, `phase` and `agent` are null where the list is empty. */
+export type SlotEnv = { ctx: Ctx; runs: readonly WfRun[]; run: WfRun | null; phase: WfPhase | null; agent: WfAgent | null; ui: WfUi; nowMs: number }
+
+export type BoardSlot = { kind: 'board'; id: string; title: string; /** Lower draws first; ties keep registration order. */ order?: number; render: (env: SlotEnv) => RenderElement[] }
+export type TabSlot = { kind: 'tab'; id: string; label: string; /** False hides the tab for this cursor (a tab about worktrees for an agent without one). */ when?: (env: SlotEnv) => boolean; render: (env: SlotEnv) => RenderElement[] }
+export type KeySlot = { kind: 'key'; id: string; /** One lowercase letter or digit the page does not own. */ key: string; label: string; run: (env: SlotEnv) => void }
+export type ActionSlot = { kind: 'action'; id: string; label: string; hotkey?: string; /** Said on the confirm row when `spec` answers null. */ why: string; spec: (env: SlotEnv) => ActionSpec | null }
+export type NoticeSlot = { kind: 'notice'; id: string; between: (prev: readonly WfRun[] | null, next: readonly WfRun[], nowMs: number) => NoticeDraft[] }
+
+export type Slot = BoardSlot | TabSlot | KeySlot | ActionSlot | NoticeSlot
+export type SlotKind = Slot['kind']
+export type SlotOf<K extends SlotKind> = Extract<Slot, { kind: K }>
+
+/** Keys the page owns: the footer (p x r h), the confirm row (y n), the page's own (j k l b d o) and the run switch (u i). */
+export const RESERVED_KEYS: readonly string[] = ['p', 'x', 'r', 'h', 'y', 'n', 'j', 'k', 'l', 'b', 'd', 'o', 'u', 'i']
+
+/** The tab every inspector has; a slot may not take its id. */
+export const DETAIL_TAB = 'detail'
+
+const ID = /^[a-z][a-z0-9-]{1,31}$/
+const MAX_PER_KIND = 12
+
+const registry: Slot[] = []
+
+export type Registered = { ok: true } | { ok: false; why: string }
+
+const refuse = (why: string): Registered => ({ ok: false, why })
+
+const hotkeyOf = (slot: Slot): string | undefined => (slot.kind === 'key' ? slot.key : slot.kind === 'action' ? slot.hotkey : undefined)
+
+/** Adds a slot, or says why not. The first registration of an id wins: a second module cannot replace another's slot. */
+export function registerSlot(slot: Slot): Registered {
+ if (typeof slot !== 'object' || slot === null) return refuse('a slot is an object')
+ if (!ID.test(slot.id)) return refuse(`id "${String(slot.id).slice(0, 24)}" is not a lowercase word of 2 to 32 letters, digits and dashes`)
+ if (registry.some(held => held.kind === slot.kind && held.id === slot.id)) return refuse(`${slot.kind} slot "${slot.id}" is already registered`)
+ if (registry.filter(held => held.kind === slot.kind).length >= MAX_PER_KIND) return refuse(`at most ${MAX_PER_KIND} ${slot.kind} slots`)
+
+ const own = slot.kind === 'board' ? slot.render : slot.kind === 'tab' ? slot.render : slot.kind === 'key' ? slot.run : slot.kind === 'action' ? slot.spec : slot.kind === 'notice' ? slot.between : null
+
+ if (typeof own !== 'function') return refuse(`${String((slot as { kind?: unknown }).kind).slice(0, 12)} slot "${slot.id}" has no function to call`)
+ if ((slot.kind === 'board' || slot.kind === 'tab') && (typeof (slot.kind === 'board' ? slot.title : slot.label) !== 'string' || (slot.kind === 'board' ? slot.title : slot.label).trim() === '')) return refuse(`slot "${slot.id}" needs a title`)
+ if (slot.kind === 'tab' && slot.id === DETAIL_TAB) return refuse(`"${DETAIL_TAB}" is the inspector's own tab`)
+ if ((slot.kind === 'key' || slot.kind === 'action') && (typeof slot.label !== 'string' || slot.label.trim() === '')) return refuse(`slot "${slot.id}" needs a label`)
+ if (slot.kind === 'action' && (typeof slot.why !== 'string' || slot.why.trim() === '')) return refuse(`action slot "${slot.id}" needs a why for the confirm row`)
+
+ const key = hotkeyOf(slot)
+
+ if (key !== undefined) {
+ if (!/^[a-z0-9]$/.test(key)) return refuse(`hotkey "${String(key).slice(0, 4)}" is not one lowercase letter or digit`)
+ if (RESERVED_KEYS.includes(key)) return refuse(`hotkey "${key}" belongs to the page`)
+ if (registry.some(held => hotkeyOf(held) === key)) return refuse(`hotkey "${key}" is taken by slot "${registry.find(held => hotkeyOf(held) === key)?.id}"`)
+ }
+
+ registry.push(slot)
+
+ return { ok: true }
+}
+
+/** The slots of one kind, in registration order (boards by `order`, then registration). */
+export function slotsFor<K extends SlotKind>(kind: K): readonly SlotOf<K>[] {
+ const list = registry.filter((slot): slot is SlotOf<K> => slot.kind === kind)
+
+ return kind === 'board' ? ([...list].sort((a, b) => ((a as BoardSlot).order ?? 100) - ((b as BoardSlot).order ?? 100)) as SlotOf<K>[]) : list
+}
+
+/** For tests: empties the registry. Nothing in the console calls it. */
+export const resetSlots = (): void => void (registry.length = 0)
diff --git a/plugins/ruflo-console/hooks/views/workflows.ts b/plugins/ruflo-console/hooks/views/workflows.ts
index 7ea82b06c9..e9387adb69 100644
--- a/plugins/ruflo-console/hooks/views/workflows.ts
+++ b/plugins/ruflo-console/hooks/views/workflows.ts
@@ -90,7 +90,7 @@ function inspect(ctx: Ctx, run: WfRun, agent: WfAgent, hooks: WorkflowsHooks): R
rows.push(kv(ctx, 'model / tokens', 'n/a (ruflo records neither per agent)'))
rows.push(
row(ctx, [
- button(ctx, 'wf-stop', 'Stop agent', () => { const spec = stopAgent(a); if (spec !== null) hooks.ask(spec) }, { hotkey: 'x' }),
+ button(ctx, 'wf-stop', 'Stop agent', () => { const spec = stopAgent(a); if (spec !== null) hooks.ask(spec) }),
button(ctx, 'wf-spawn', `Spawn another ${a.type}`, () => { const spec = spawnAgent(a.type, ctx.nowMs); if (spec !== null) hooks.ask(spec) }),
]),
)
diff --git a/plugins/ruflo-console/hooks/wf-actions.ts b/plugins/ruflo-console/hooks/wf-actions.ts
new file mode 100644
index 0000000000..c8d74c061c
--- /dev/null
+++ b/plugins/ruflo-console/hooks/wf-actions.ts
@@ -0,0 +1,60 @@
+/**
+ * What the Workflows page's buttons call (ADR-464). Keys move the cursor through the pure reducer in data/workflows-nav;
+ * the one write the page has, stopping or spawning a ruflo agent, goes through the runner's confirm card as a fixed argv.
+ * Nothing here can stop or message a running Claude Code workflow: the console has no verb for it, so the page says so.
+ */
+import type { ActionSpec } from './actions'
+import { walk, type WfKey, type WfUi } from './data/workflows-nav'
+import type { Host } from './host'
+import type { Runner } from './runner'
+import type { State } from './state'
+import { workflowsModelOf } from './wf-live'
+import { DETAIL_TAB, slotsFor } from './views/wf-slots'
+
+export type WorkflowsActions = {
+ /** j k h l [ ] Enter Escape, as the page's reducer reads them. */
+ key: (key: WfKey) => void
+ /** Goes to the inspector tab `id` (`detail` or a registered slot tab); an unknown id falls back to `detail`. */
+ tab: (id: string) => void
+ /** Merges a change into the cursor (for a slot's key handler), then redraws. */
+ setUi: (patch: Partial<WfUi>) => void
+ /** Asks to run a spec (the confirm card shows its exact command); a null spec says `why`. */
+ ask: (spec: ActionSpec | null, why?: string) => void
+ /** Names a transcript's path on the footer outcome row, after checking it is inside the config directory's projects folder. */
+ show: (path: string) => void
+}
+
+/** True for a path under `<configDir>/projects/` with no `..` part: the only place a run's files live. */
+export function isRunPath(path: string, configDir: string | null): boolean {
+ if (configDir === null || path.includes('\0') || path.split('/').includes('..')) return false
+
+ return path.startsWith(`${configDir.replace(/\/+$/, '')}/projects/`)
+}
+
+export function workflowsActions(state: State, host: Host, runner: Runner): WorkflowsActions {
+ return {
+ key: key => {
+ const model = workflowsModelOf(state, Date.now())
+
+ state.wf.ui = walk(state.wf.ui, model?.runs ?? [], key)
+ // Closing the inspector, or moving to another agent, goes back to the page's own tab.
+ if (key === 'escape' || key === 'enter' || key === '[' || key === ']') state.wf.tab = DETAIL_TAB
+ host.invalidate()
+ },
+ tab: id => {
+ state.wf.tab = id === DETAIL_TAB || slotsFor('tab').some(slot => slot.id === id) ? id : DETAIL_TAB
+ host.invalidate()
+ },
+ setUi: patch => {
+ state.wf.ui = { ...state.wf.ui, ...patch }
+ host.invalidate()
+ },
+ ask: (spec, why = 'that cannot run here') => runner.ask(spec, why),
+ show: path => {
+ const ok = isRunPath(path, state.configDir)
+
+ state.outcome = { label: 'transcript', ok, verified: 'n/a', detail: ok ? path : 'that path is outside Claude Code\'s projects folder, so it is not shown', atMs: Date.now() }
+ host.invalidate()
+ },
+ }
+}
diff --git a/plugins/ruflo-console/hooks/wf-live.ts b/plugins/ruflo-console/hooks/wf-live.ts
new file mode 100644
index 0000000000..6b3a67e47c
--- /dev/null
+++ b/plugins/ruflo-console/hooks/wf-live.ts
@@ -0,0 +1,87 @@
+/**
+ * The Workflows page's refresh (ADR-464), kept out of the controller: it reads Claude Code's run folders through the host's
+ * read-only `fs` only while the page is the one in front, once per refresh tick (the controller's own cadence, the pane's
+ * `refreshSeconds`), and never while the pane is closed or hidden. A read still running is joined, not stacked. A failed
+ * read keeps the runs already on screen and says why. After a read the notice slots are asked what changed (views/wf-slots.ts),
+ * and the page itself announces a run that finished or failed, from the change between two reads only: the first read announces nothing.
+ */
+import { cleanRun, cleanText } from './data/wf-clean'
+import { readWorkflowRuns, type WorkflowFs } from './data/workflows-read'
+import { allRuns, startOn } from './data/workflows-nav'
+import type { WfRun } from './data/workflows'
+import { plain } from './data/parse'
+import type { Host } from './host'
+import { addNotice, type NoticeDraft } from './notices'
+import type { State } from './state'
+import { slotsFor } from './views/wf-slots'
+import type { WorkflowsModel } from './views/workflows'
+
+/** The notices one read raises: a workflow run that ended since the last read (finished, or failed), seen against each run's earlier state. */
+export function runNotices(prev: ReadonlyMap<string, string> | null, next: readonly WfRun[]): NoticeDraft[] {
+ if (prev === null) return []
+
+ const out: NoticeDraft[] = []
+
+ for (const run of next) {
+ const before = prev.get(run.id)
+
+ if (before === undefined || before === run.state) continue
+ if (run.state === 'completed' || run.state === 'finished') out.push({ level: 'ok', text: `workflow ${run.name} finished: ${run.done}/${run.total} agents`, key: `wf-${run.id}-done`, go: 'workflows' })
+ else if (run.state === 'failed') out.push({ level: 'bad', text: `workflow ${run.name} failed: ${run.failed} of ${run.total} agents`, key: `wf-${run.id}-failed`, go: 'workflows' })
+ }
+
+ return out
+}
+
+/** The page's model for this frame: the read runs with the ruflo swarm folded in; null before the first read finishes. */
+export function workflowsModelOf(state: State, nowMs: number): WorkflowsModel | null {
+ const read = state.wf.read
+
+ if (read === null) return null
+
+ return { runs: allRuns(read.runs, state.snapshot?.swarm ?? null, state.snapshot?.agents ?? [], nowMs), root: read.root, capBytes: read.capBytes, skipped: read.skipped, more: read.more }
+}
+
+/**
+ * Reads the runs now if the page is in front and the pane is shown (or there is no pane, as in a dump). `force` skips the
+ * pane check for the open of the page itself. Resolves when the read is done or was not needed.
+ */
+export async function refreshWorkflows(state: State, host: Host, force = false, nowMs: number = Date.now()): Promise<void> {
+ if (state.view !== 'workflows' || state.wf.isReading) return
+ if (!force && state.isInteractive && !(state.pane.isOpen && state.pane.isShown)) return
+
+ const wf = state.wf
+
+ wf.isReading = true
+
+ try {
+ const result = await readWorkflowRuns(host.fs as WorkflowFs, state.cache, { configDir: state.configDir, cwd: state.cwd, nowMs })
+ const runs = result.runs.map(cleanRun)
+ const first = wf.read === null
+ const prev = wf.seen
+ const before = wf.read?.runs ?? null
+
+ wf.read = { runs, root: result.root, capBytes: result.capBytes, skipped: result.skipped.length, more: result.more }
+ wf.readAtMs = nowMs
+ wf.error = null
+ wf.seen = new Map(runs.map(run => [run.id, run.state]))
+
+ // The cursor starts on the phase the first run is in; later reads leave it where the person put it.
+ if (first) wf.ui = startOn(wf.ui, allRuns(runs, state.snapshot?.swarm ?? null, state.snapshot?.agents ?? [], nowMs)[0] ?? null)
+
+ for (const draft of runNotices(prev, runs)) addNotice(state, draft, nowMs)
+
+ for (const slot of slotsFor('notice')) {
+ try {
+ for (const draft of slot.between(before, runs, nowMs)) addNotice(state, { ...draft, text: cleanText(draft.text), key: `${slot.id}:${plain(draft.key, 40)}` }, nowMs)
+ } catch {
+ // A slot that throws raises nothing; the page still reads.
+ }
+ }
+ } catch (error) {
+ wf.error = cleanText(plain(error instanceof Error ? error.message : String(error), 100)) || 'the read was refused'
+ } finally {
+ wf.isReading = false
+ host.invalidate()
+ }
+}
diff --git a/plugins/ruflo-console/hooks/wf-state.ts b/plugins/ruflo-console/hooks/wf-state.ts
new file mode 100644
index 0000000000..4d1c782b30
--- /dev/null
+++ b/plugins/ruflo-console/hooks/wf-state.ts
@@ -0,0 +1,26 @@
+/**
+ * What the Workflows page keeps in `State` (ADR-464). A leaf module with type imports only, so state.ts can build the
+ * empty value without a cycle: the reading itself is in ./wf-live, the keys in ./wf-actions.
+ */
+import type { WfRun } from './data/workflows'
+import { newWfUi, type WfUi } from './data/workflows-nav'
+
+/** The folder reader's answer with the runs already cleaned (control characters stripped, credentials masked) and the unread transcripts counted. */
+export type WfRead = { runs: WfRun[]; root: string | null; capBytes: number; skipped: number; more: number }
+
+export type WfState = {
+ /** The last read, or null before the first one finishes. */
+ read: WfRead | null
+ readAtMs: number
+ /** Why the last read failed, in plain words; null when it did not. A failed read keeps the previous runs on screen. */
+ error: string | null
+ isReading: boolean
+ /** Where the cursor is (run, phase, agent, column, whether the inspector is open). */
+ ui: WfUi
+ /** The inspector's tab: `detail` is the page's own, any other is a registered slot tab (views/wf-slots.ts). */
+ tab: string
+ /** Each run's state as of the last read, by run id: what a notice is decided against. Null until the first read. */
+ seen: Map<string, string> | null
+}
+
+export const emptyWf = (): WfState => ({ read: null, readAtMs: 0, error: null, isReading: false, ui: newWfUi(), tab: 'detail', seen: null })
diff --git a/plugins/ruflo-console/tests/boot-cyber.spec.ts b/plugins/ruflo-console/tests/boot-cyber.spec.ts
index 7597b5a896..0094c9d1bd 100644
--- a/plugins/ruflo-console/tests/boot-cyber.spec.ts
+++ b/plugins/ruflo-console/tests/boot-cyber.spec.ts
@@ -59,7 +59,7 @@ describe('the cyberpunk log', () => {
expect(text).toContain('RUV.NET // RUVECTOR CONSTELLATION')
expect(text).toContain('rUv · ruflo v0.26.0 · abc123')
expect(text).toContain('ruvector')
- expect(text).toMatch(/\[WARN\] READY · 28 of 28 areas verified · \d+ stars? dark/)
+ expect(text).toMatch(/\[WARN\] READY · 29 of 29 areas verified · \d+ stars? dark/)
expect(text).not.toContain('ALL STARS ALIGNED')
})
@@ -76,7 +76,7 @@ describe('the cyberpunk log', () => {
const failed = textOf(bootPicture('p', 90, 6000, 10, 10, rowsFor, failing, bootFacts(lit, '1', '')))
expect(failed).not.toContain('ALL STARS ALIGNED')
- expect(failed).toMatch(/\[FAIL\] READY · 27 of 28 areas verified · 1 failed/)
+ expect(failed).toMatch(/\[FAIL\] READY · 28 of 29 areas verified · 1 failed/)
})
it('shows the easter egg only in its window, and it decodes to rUv', () => {
@@ -97,7 +97,7 @@ describe('the cyberpunk log', () => {
it('falls back to the plain log in a narrow or short pane', () => {
const facts = bootFacts(withPlugins([]), '1', '')
- expect(textOf(bootPicture('p', 44, 6000, 10, 10, rowsFor, allOk, facts))).toContain('[ OK ] READY 28 of 28 areas verified')
+ expect(textOf(bootPicture('p', 44, 6000, 10, 10, rowsFor, allOk, facts))).toContain('[ OK ] READY 29 of 29 areas verified')
expect(textOf(bootPicture('p', 90, 6000, 10, 10, BOOT_ROWS + 6, allOk, facts))).not.toContain('RUV.NET')
})
})
diff --git a/plugins/ruflo-console/tests/nav.spec.ts b/plugins/ruflo-console/tests/nav.spec.ts
index 75464b67d9..e027e62712 100644
--- a/plugins/ruflo-console/tests/nav.spec.ts
+++ b/plugins/ruflo-console/tests/nav.spec.ts
@@ -12,7 +12,7 @@ describe('main nav hotkeys', () => {
expect(keys.every(key => /^[0-9a-z]$/.test(key))).toBe(true)
expect(new Set(keys).size).toBe(keys.length)
- expect(VIEWS.filter(view => view.key === '').map(view => view.id)).toEqual(['room', 'sandbox'])
+ expect(VIEWS.filter(view => view.key === '').map(view => view.id)).toEqual(['workflows', 'room', 'sandbox'])
})
it('none takes a key the footer, the confirm row, scrolling or the menu prompt owns', () => {
diff --git a/plugins/ruflo-console/tests/views.test.ts b/plugins/ruflo-console/tests/views.test.ts
index 512b57dcb1..d4a85e8def 100644
--- a/plugins/ruflo-console/tests/views.test.ts
+++ b/plugins/ruflo-console/tests/views.test.ts
@@ -180,11 +180,10 @@ describe('views', () => {
mock.clock(on)
await $.session.start(SESSION)
- const folded = await drawn($, 'learning')
- expect(folded.rasters).toEqual(['title', 'curve'])
- const { text, rasters } = await drawn($, 'learning', 110, ['learn-pipeline'])
+ // The pipeline section is open by default since ADR-455 (its stages are a picture of their own); the old test clicked it open.
+ const { text, rasters } = await drawn($, 'learning', 110)
- expect(rasters).toEqual(['title', 'curve', 'pipeline', 'patterns'])
+ expect(rasters).toEqual(['title', 'route', 'curve', 'pipeline-stages', 'patterns'])
expect(text).toContain('tester 60% · keyword match')
expect(text).toMatch(/\d+\/9 succeeded \(\d+% success rate, N=9\)/)
expect(text).toContain('consolidate: EWC consolidations')
diff --git a/plugins/ruflo-console/tests/wf-wire.spec.ts b/plugins/ruflo-console/tests/wf-wire.spec.ts
new file mode 100644
index 0000000000..f77575e083
--- /dev/null
+++ b/plugins/ruflo-console/tests/wf-wire.spec.ts
@@ -0,0 +1,393 @@
+/**
+ * The Workflows page's wiring (ADR-464): the view is reachable (view table, nav, menu, ask, commands), refreshed only while it is open,
+ * washed of credentials and control characters, its keys never take a global key, and the slot registry other features plug into holds
+ * its rules. Pure and fast: an in-memory disk, a recording kit, no engine. Run with
+ * npx vitest run plugins/ruflo-console/tests/wf-wire.spec.ts --testTimeout=30000
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import type { ActionSpec } from '../hooks/actions'
+import { VIEW_ASK } from '../hooks/ask-claude'
+import { parseRuflo } from '../hooks/commands'
+import { cleanRun, cleanText } from '../hooks/data/wf-clean'
+import { buildRun } from '../hooks/data/workflows'
+import type { WorkflowFs } from '../hooks/data/workflows-read'
+import type { Host } from '../hooks/host'
+import { NAV_GROUPS } from '../hooks/nav-state'
+import { newState, rowsOf, VIEWS, viewOf, type State } from '../hooks/state'
+import { isRunPath, workflowsActions } from '../hooks/wf-actions'
+import { refreshWorkflows, runNotices, workflowsModelOf } from '../hooks/wf-live'
+import { GROUPS } from '../hooks/views/menu'
+import type { Actions, Ctx, Kit } from '../hooks/views/common'
+import { workflowsPage } from '../hooks/views/wf-page'
+import { DETAIL_TAB, registerSlot, resetSlots, slotsFor, type Slot } from '../hooks/views/wf-slots'
+import { journal, meta, record, result, started, T0, transcript } from './fixtures/workflows'
+
+const NOW = T0 + 10_000
+const CONFIG = '/home/u/.claude'
+const ROOT = `${CONFIG}/projects/-work-proj`
+const SESSION = '11111111-2222-3333-4444-555555555555'
+const RUN = `${ROOT}/${SESSION}/subagents/workflows/wf_live`
+
+type El = { kind: string; props: Record<string, unknown> }
+
+const kit = { Box: (props: Record<string, unknown>): El => ({ kind: 'Box', props }), Text: (props: Record<string, unknown>): El => ({ kind: 'Text', props }), Button: (props: Record<string, unknown>): El => ({ kind: 'Button', props }) } as unknown as Kit
+
+const flat = (node: unknown, out: El[] = []): El[] => {
+ if (Array.isArray(node)) node.forEach(child => flat(child, out))
+ else if (typeof node === 'object' && node !== null) {
+ out.push(node as El)
+ flat((node as El).props?.children, out)
+ }
+
+ return out
+}
+
+const words = (tree: unknown): string => flat(tree).filter(el => el.kind === 'Text' && typeof el.props.children === 'string').map(el => el.props.children as string).join('\n')
+const buttons = (tree: unknown): El[] => flat(tree).filter(el => el.kind === 'Button')
+const buttonOf = (tree: unknown, key: string): El | undefined => buttons(tree).find(el => el.props.key === key)
+
+function memoryFs(files: Record<string, string>): WorkflowFs {
+ const under = (dir: string) => [...new Set(Object.keys(files).filter(path => path.startsWith(`${dir}/`)).map(path => path.slice(dir.length + 1).split('/')[0] as string))]
+
+ return {
+ read: async path => files[path] ?? Promise.reject(new Error('ENOENT')),
+ stat: async path => (files[path] !== undefined ? { mtimeMs: T0, size: files[path].length, kind: 'file' } : Promise.reject(new Error('ENOENT'))),
+ list: async dir => {
+ const names = under(dir)
+
+ return names.length === 0 ? Promise.reject(new Error('ENOENT')) : names.map(name => ({ name, mtimeMs: T0, size: files[`${dir}/${name}`]?.length }))
+ },
+ }
+}
+
+const live = (label = 'build:x'): Record<string, string> => ({
+ [`${RUN}/journal.jsonl`]: journal(started('a1', label, 'Build')),
+ [`${RUN}/agent-a1.meta.json`]: meta(label, 'Build'),
+ [`${RUN}/agent-a1.jsonl`]: transcript([{ at: 5, id: 'm1', input: 1, write: 1, read: 1, output: 1 }]),
+})
+
+function worldOf(files: Record<string, string>): { state: State; host: Host; fs: { files: Record<string, string> }; invalidated: () => number } {
+ const state = newState({})
+ const box = { files }
+ let drawn = 0
+ const fs: WorkflowFs = { read: path => memoryFs(box.files).read(path), stat: path => memoryFs(box.files).stat(path), list: dir => memoryFs(box.files).list(dir) }
+ const host = { fs, invalidate: () => void (drawn += 1) } as unknown as Host
+
+ state.view = 'workflows'
+ state.configDir = CONFIG
+ state.cwd = '/work/proj'
+ state.isInteractive = false
+
+ return { state, host, fs: box, invalidated: () => drawn }
+}
+
+const asked: { spec: ActionSpec | null; why: string }[] = []
+
+function pageOf(state: State, host: Host, columns = 100): { tree: unknown; ctx: Ctx } {
+ const runner = { ask: (spec: ActionSpec | null, why: string) => void asked.push({ spec, why }) }
+ const act = { workflows: workflowsActions(state, host, runner as never) } as unknown as Actions
+ const ctx: Ctx = { kit, state, nowMs: NOW, columns, pictures: new Map(), act }
+
+ return { tree: workflowsPage(ctx), ctx }
+}
+
+beforeEach(() => {
+ resetSlots()
+ asked.length = 0
+})
+afterEach(() => resetSlots())
+
+describe('the page is reachable', () => {
+ it('is a view with no key (every letter is a tab or reserved), found by id, label and /ruflo', () => {
+ const view = VIEWS.find(entry => entry.id === 'workflows')
+
+ expect(view).toMatchObject({ key: '', label: 'Workflows' })
+ expect(viewOf('workflows')).toBe('workflows')
+ expect(parseRuflo('workflows')).toEqual({ kind: 'open', view: 'workflows' })
+ expect(rowsOf('workflows')).toBeGreaterThan(20)
+ })
+
+ it('sits in the SWARM nav group and the menu\'s SWARM > observe section, next to Swarm Topology', () => {
+ expect(NAV_GROUPS.find(group => group.title === 'SWARM')?.rows.flat()).toContain('workflows')
+
+ const observe = GROUPS.find(group => group.title === 'SWARM')?.sections.find(section => section.name === 'observe')
+
+ expect(observe?.items.map(item => item.go)).toEqual(['swarm', 'workflows'])
+ })
+
+ it('has an Ask Claude entry', () => {
+ expect(VIEW_ASK.workflows.default).toMatch(/workflow/i)
+ })
+})
+
+describe('the refresh', () => {
+ it('reads only while the page is in front: another view, or a closed pane, reads nothing', async () => {
+ const world = worldOf(live())
+ const opened: string[] = []
+ const host = { ...world.host, fs: { ...(world.host.fs as WorkflowFs), read: async (path: string) => (opened.push(path), (world.host.fs as WorkflowFs).read(path)) } } as unknown as Host
+
+ world.state.view = 'overview'
+ await refreshWorkflows(world.state, host, true, NOW)
+ expect(world.state.wf.read).toBeNull()
+ expect(opened).toEqual([])
+
+ world.state.view = 'workflows'
+ world.state.isInteractive = true
+ world.state.pane.isOpen = true
+ world.state.pane.isShown = false
+ await refreshWorkflows(world.state, host, false, NOW)
+ expect(world.state.wf.read).toBeNull()
+
+ world.state.pane.isShown = true
+ await refreshWorkflows(world.state, host, false, NOW)
+ expect(world.state.wf.read?.runs).toHaveLength(1)
+ expect(opened.length).toBeGreaterThan(0)
+ })
+
+ it('joins a read already running instead of stacking another', async () => {
+ const world = worldOf(live())
+ let lists = 0
+ const inner = world.host.fs as WorkflowFs
+ const host = { ...world.host, fs: { ...inner, list: async (dir: string) => (lists += 1, inner.list(dir)) } } as unknown as Host
+
+ await Promise.all([refreshWorkflows(world.state, host, true, NOW), refreshWorkflows(world.state, host, true, NOW)])
+
+ const once = lists
+
+ await refreshWorkflows(world.state, host, true, NOW)
+ expect(lists).toBe(once * 2)
+ })
+
+ it('a reader that throws leaves the previous read and an error line, and clears when the next read works', async () => {
+ const world = worldOf(live())
+
+ await refreshWorkflows(world.state, world.host, true, NOW)
+
+ const before = world.state.wf.read
+ const throwing = { ...world.host, fs: undefined } as unknown as Host
+
+ await refreshWorkflows(world.state, throwing, true, NOW + 1)
+ expect(world.state.wf.read).toBe(before)
+ expect(world.state.wf.error).not.toBeNull()
+ expect(words(pageOf(world.state, world.host).tree)).toMatch(/last read failed/)
+
+ await refreshWorkflows(world.state, world.host, true, NOW + 2)
+ expect(world.state.wf.error).toBeNull()
+ })
+
+ it('washes credentials and control characters from labels before anything draws them', async () => {
+ const token = 'sk-abcdefghijklmnopqrstuvwxyz012345'
+ const world = worldOf(live(`deploy ${token} \u001b[31mred`))
+
+ await refreshWorkflows(world.state, world.host, true, NOW)
+
+ const text = words(pageOf(world.state, world.host).tree)
+ const agent = world.state.wf.read?.runs[0]?.phases[0]?.agents[0]
+
+ expect(agent?.label).not.toContain('sk-')
+ expect(text).not.toContain(token)
+ expect(text).not.toMatch(/\u001b/)
+ expect(cleanText('Bearer abcdefgh12345678 x\u0007y')).toBe('‹masked› x y')
+ })
+
+ it('announces a run that finished or failed since the last read; the first read announces nothing', async () => {
+ const world = worldOf(live())
+
+ await refreshWorkflows(world.state, world.host, true, NOW)
+ expect(world.state.notices).toEqual([])
+
+ world.fs.files = { ...world.fs.files, [`${ROOT}/${SESSION}/workflows/wf_live.json`]: record({ status: 'completed' }) }
+ // A file found missing is not looked for again for 10 s (data/files.ts): the record shows up at the next read after that.
+ world.state.cache.clear()
+ await refreshWorkflows(world.state, world.host, true, NOW + 1)
+ expect(world.state.notices.map(notice => notice.text)).toEqual([expect.stringMatching(/workflow .* finished: \d+\/\d+ agents/)])
+ expect(world.state.notices[0]?.go).toBe('workflows')
+ })
+
+ it('runNotices reads state changes only (running to failed raises one, no change raises none)', () => {
+ const run = (state: string) => ({ id: 'wf_a', name: 'demo', state, done: 1, failed: 1, total: 2 }) as never
+
+ expect(runNotices(null, [run('failed')])).toEqual([])
+ expect(runNotices(new Map([['wf_a', 'failed']]), [run('failed')])).toEqual([])
+ expect(runNotices(new Map([['wf_a', 'running']]), [run('failed')])).toMatchObject([{ level: 'bad', key: 'wf-wf_a-failed' }])
+ expect(runNotices(new Map(), [run('failed')])).toEqual([])
+ })
+
+ it('a notice slot is asked after a read, its text is masked, its throw is contained', async () => {
+ const world = worldOf(live())
+
+ expect(registerSlot({ kind: 'notice', id: 'loud', between: () => [{ level: 'warn', text: 'token Bearer abcdefgh12345678 seen', key: 'k1' }] })).toEqual({ ok: true })
+ expect(registerSlot({ kind: 'notice', id: 'broken', between: () => { throw new Error('nope') } })).toEqual({ ok: true })
+ await refreshWorkflows(world.state, world.host, true, NOW)
+ expect(world.state.notices).toHaveLength(1)
+ expect(world.state.notices[0]?.text).toBe('token ‹masked› seen')
+ expect(world.state.notices[0]?.key).toBe('loud:k1')
+ })
+
+ it('the page model folds the ruflo swarm in after the workflow runs', async () => {
+ const world = worldOf(live())
+
+ expect(workflowsModelOf(world.state, NOW)).toBeNull()
+ await refreshWorkflows(world.state, world.host, true, NOW)
+ expect(workflowsModelOf(world.state, NOW)?.runs.map(run => run.kind)).toEqual(['workflow'])
+ })
+})
+
+describe('the keys', () => {
+ it('move the cursor through the pure reducer, and /ruflo next|prev is the same j|k', async () => {
+ const files = { ...live(), [`${RUN}/agent-a2.meta.json`]: meta('b', 'Build'), [`${RUN}/journal.jsonl`]: journal(started('a1', 'one', 'Build'), started('a2', 'two', 'Build')), [`${RUN}/agent-a2.jsonl`]: transcript([{ at: 6, id: 'm2', input: 1, write: 1, read: 1, output: 1 }]) }
+ const world = worldOf(files)
+
+ await refreshWorkflows(world.state, world.host, true, NOW)
+
+ const act = workflowsActions(world.state, world.host, { ask: () => undefined } as never)
+
+ act.key('l')
+ expect(world.state.wf.ui.column).toBe('agents')
+ act.key('j')
+ expect(world.state.wf.ui.agent).toBe(1)
+ act.key('k')
+ expect(world.state.wf.ui.agent).toBe(0)
+ act.key('enter')
+ expect(world.state.wf.ui.isInspecting).toBe(true)
+ act.key('escape')
+ expect(world.state.wf.ui.isInspecting).toBe(false)
+ })
+
+ it('every button the page draws avoids the footer, confirm and menu keys, and no two share a hotkey or a key', async () => {
+ const world = worldOf(live())
+
+ await refreshWorkflows(world.state, world.host, true, NOW)
+
+ const { tree } = pageOf(world.state, world.host)
+ const hotkeys = buttons(tree).map(el => el.props.hotkey).filter((key): key is string => typeof key === 'string')
+
+ expect(hotkeys.sort()).toEqual(['b', 'd', 'i', 'j', 'k', 'l', 'u'].sort())
+ for (const key of ['p', 'x', 'r', 'h', 'y', 'n']) expect(hotkeys, `hotkey ${key}`).not.toContain(key)
+ expect(new Set(buttons(tree).map(el => el.props.key)).size).toBe(buttons(tree).length)
+ // Pressing a button moves the cursor.
+ buttonOf(tree, 'wf-col-agents')?.props.onPress?.call(undefined)
+ expect(world.state.wf.ui.column).toBe('agents')
+ })
+
+ it('opens a transcript path only inside the config directory\'s projects folder', () => {
+ expect(isRunPath(`${ROOT}/${SESSION}/subagents/workflows/wf_live/agent-a1.jsonl`, CONFIG)).toBe(true)
+ expect(isRunPath(`${CONFIG}/projects/../secrets.json`, CONFIG)).toBe(false)
+ expect(isRunPath('/etc/passwd', CONFIG)).toBe(false)
+ expect(isRunPath(`${CONFIG}/projects/x`, null)).toBe(false)
+ expect(isRunPath(`${CONFIG}/projects/x\0y`, CONFIG)).toBe(false)
+
+ const world = worldOf({})
+
+ workflowsActions(world.state, world.host, {} as never).show('/etc/passwd')
+ expect(world.state.outcome).toMatchObject({ ok: false })
+ expect(world.state.outcome?.detail).not.toContain('/etc/passwd')
+ })
+})
+
+describe('the page', () => {
+ it('says there is nothing to show before a read, and when a project has no runs', async () => {
+ const world = worldOf({})
+
+ expect(words(pageOf(world.state, world.host).tree)).toMatch(/reading workflow runs/)
+ await refreshWorkflows(world.state, world.host, true, NOW)
+ expect(words(pageOf(world.state, world.host).tree)).toMatch(/No workflow runs for this project/)
+ })
+
+ it('says the console cannot stop or message a workflow, with no button for it', async () => {
+ const world = worldOf(live())
+
+ await refreshWorkflows(world.state, world.host, true, NOW)
+
+ const { tree } = pageOf(world.state, world.host)
+
+ expect(words(tree)).toMatch(/Stop and message belong to Claude Code/)
+ expect(buttons(tree).some(el => /stop|message/i.test(String(el.props.label)))).toBe(false)
+ })
+
+ it('draws at 40 and 150 columns, with nothing undefined or NaN', async () => {
+ const world = worldOf(live())
+
+ await refreshWorkflows(world.state, world.host, true, NOW)
+ for (const columns of [40, 80, 150]) expect(words(pageOf(world.state, world.host, columns).tree), `${columns}`).not.toMatch(/undefined|NaN|\[object/)
+ })
+
+ it('draws a board slot, a key slot, an action slot and an inspector tab, and a slot that throws costs one line', async () => {
+ const world = worldOf(live())
+ const spec: ActionSpec = { label: 'do a thing', args: ['agent', 'list'], expect: 'a list' }
+ const slots: Slot[] = [
+ { kind: 'board', id: 'extra', title: 'Extra', render: env => [env.ctx.kit.Text({ children: `extra for ${env.run?.name}` })] },
+ { kind: 'board', id: 'bad', title: 'Bad', render: () => { throw new Error('exploded') } },
+ { kind: 'key', id: 'mark', key: 'm', label: 'Mark', run: env => env.ctx.act.workflows.setUi({ run: 0 }) },
+ { kind: 'action', id: 'act', label: 'Do', hotkey: 'a', why: 'nothing to do', spec: () => spec },
+ { kind: 'tab', id: 'cost', label: 'Cost', render: env => [env.ctx.kit.Text({ children: 'tab body' })] },
+ ]
+
+ for (const slot of slots) expect(registerSlot(slot)).toEqual({ ok: true })
+ await refreshWorkflows(world.state, world.host, true, NOW)
+
+ const first = pageOf(world.state, world.host)
+
+ expect(words(first.tree)).toMatch(/extra for/)
+ expect(words(first.tree)).toMatch(/slot bad failed: exploded/)
+ expect(buttonOf(first.tree, 'wf-key-mark')?.props.hotkey).toBe('m')
+ buttonOf(first.tree, 'wf-act-act')?.props.onPress?.call(undefined)
+ expect(asked).toEqual([{ spec, why: 'nothing to do' }])
+ // The tab shows only while the inspector is open.
+ expect(buttonOf(first.tree, 'wf-tab-cost')).toBeUndefined()
+
+ world.state.wf.ui = { ...world.state.wf.ui, column: 'agents', isInspecting: true }
+
+ const open = pageOf(world.state, world.host)
+
+ expect(buttonOf(open.tree, 'wf-tab-cost')).toBeDefined()
+ buttonOf(open.tree, 'wf-tab-cost')?.props.onPress?.call(undefined)
+ expect(words(pageOf(world.state, world.host).tree)).toMatch(/tab body/)
+ expect(world.state.wf.tab).toBe('cost')
+ workflowsActions(world.state, world.host, {} as never).tab('nope')
+ expect(world.state.wf.tab).toBe(DETAIL_TAB)
+ })
+})
+
+describe('the slot registry', () => {
+ const board = (id: string, order?: number): Slot => ({ kind: 'board', id, title: id, ...(order !== undefined && { order }), render: () => [] })
+
+ it('refuses a malformed id, a repeated id, a function-less slot and the inspector\'s own tab, saying why', () => {
+ expect(registerSlot(board('Bad Id'))).toMatchObject({ ok: false })
+ expect(registerSlot(board('one'))).toEqual({ ok: true })
+ expect(registerSlot(board('one'))).toMatchObject({ ok: false, why: expect.stringContaining('already registered') })
+ expect(registerSlot({ kind: 'board', id: 'nofn', title: 'x' } as never)).toMatchObject({ ok: false })
+ expect(registerSlot({ kind: 'tab', id: 'detail', label: 'x', render: () => [] })).toMatchObject({ ok: false })
+ expect(registerSlot(null as never)).toMatchObject({ ok: false })
+ expect(registerSlot({ kind: 'board', id: 'notitle', title: ' ', render: () => [] })).toMatchObject({ ok: false })
+ expect(registerSlot({ kind: 'action', id: 'nowhy', label: 'x', why: '', spec: () => null })).toMatchObject({ ok: false })
+ })
+
+ it('refuses a hotkey the page owns, a malformed one, and one another slot holds', () => {
+ for (const key of ['p', 'x', 'r', 'h', 'y', 'n', 'j', 'k', 'l', 'b', 'd', 'o', 'u', 'i']) expect(registerSlot({ kind: 'key', id: `k-${key.charCodeAt(0)}`, key, label: 'x', run: () => undefined }), key).toMatchObject({ ok: false })
+
+ expect(registerSlot({ kind: 'key', id: 'upper', key: 'M', label: 'x', run: () => undefined })).toMatchObject({ ok: false })
+ expect(registerSlot({ kind: 'key', id: 'long', key: 'mm', label: 'x', run: () => undefined })).toMatchObject({ ok: false })
+ expect(registerSlot({ kind: 'key', id: 'first', key: 'm', label: 'x', run: () => undefined })).toEqual({ ok: true })
+ expect(registerSlot({ kind: 'action', id: 'second', label: 'x', hotkey: 'm', why: 'w', spec: () => null })).toMatchObject({ ok: false, why: expect.stringContaining('taken by slot "first"') })
+ })
+
+ it('keeps at most twelve slots of a kind, boards ordered by `order` then registration', () => {
+ for (let i = 0; i < 12; i += 1) expect(registerSlot(board(`b-${i}`, i === 5 ? 1 : undefined))).toEqual({ ok: true })
+
+ expect(registerSlot(board('b-last'))).toMatchObject({ ok: false })
+ expect(slotsFor('board').map(slot => slot.id).slice(0, 3)).toEqual(['b-5', 'b-0', 'b-1'])
+ expect(slotsFor('tab')).toEqual([])
+ })
+
+ it('cleanRun leaves ids and numbers alone and washes every free-text field', () => {
+ const run = buildRun({ id: 'wf_x', dir: '/d', journal: journal(started('a1', 'label sk-abcdefghijklmnopqrstuvwxyz012345', 'Phase'), result('a1', 'ok Bearer abcdefgh12345678')), agents: new Map(), record: null, script: null, nowMs: NOW })
+ const cleaned = cleanRun(run)
+
+ expect(JSON.stringify(cleaned)).not.toMatch(/sk-abcdef|abcdefgh12345678/)
+ expect(cleaned.id).toBe('wf_x')
+ expect(cleaned.total).toBe(run.total)
+ })
+})
+
diff --git a/v3/docs/adr/ADR-464-workflows-page-wiring-and-slots.md b/v3/docs/adr/ADR-464-workflows-page-wiring-and-slots.md
new file mode 100644
index 0000000000..e9486c4755
--- /dev/null
+++ b/v3/docs/adr/ADR-464-workflows-page-wiring-and-slots.md
@@ -0,0 +1,76 @@
+# ADR 464: Workflows page wiring and its slot seams
+
+Status: Accepted
+
+Date: 2026-10-05
+
+Builds on: ADR-458 (the page itself), ADR-444 (Claude controls the console), ADR-453 (confirm-gated verbs)
+
+Reserved and untouched: ADR-459 (drill) to ADR-463
+
+## 1. Context
+
+ADR-458 shipped the Workflows page's data, key reducer and drawing, but nothing reached it: no view id, no menu entry,
+no state, no refresh. Five features (on `feat/mind-all`) also want to add to that page, and a shared file edited by six
+writers is where merges go wrong.
+
+## 2. Decision
+
+**Wire it.** `workflows` is a view in `VIEWS` (after Claims; label Workflows, 34 rows) with **no hotkey**: every digit and
+letter is a tab key or a reserved one (footer `p x r h`, confirm `y n`, scroll `j k`, menu `o`), as for Room and Sandbox.
+It is in the nav's SWARM group, the menu's SWARM > observe section beside Swarm Topology, the boot log, the ask table
+(`ruflo-workflows:workflow`), the help guide for Swarm, and `/ruflo workflows` (and `/ruflo dump workflows`, which reads first).
+
+**State.** `state.wf` (`wf-state.ts`, a leaf module): the last read (runs already washed), when, the last error, the
+cursor, the inspector tab, and each run's state as of the last read.
+
+**Refresh, outside the controller.** `wf-live.ts: refreshWorkflows` reads Claude Code's run folders through the host's read-only `fs`
+only while `state.view === 'workflows'` and the pane is open and shown (or there is no pane, as in a dump). It runs when the page opens
+(`view-open.ts`) and on the controller's existing refresh tick (one call in `controller.ts`, 495 lines). One read at a time; a failed
+read keeps the runs on screen with a warning line. Bounds are ADR-458's (6 runs, 60 agents, 3 MB per transcript, cap printed on the page).
+
+**Washing.** `data/wf-clean.ts` strips control characters and masks credential-shaped text in every free-text field (labels, phase titles,
+models, last tool, result preview, ruflo agent names) once per read, before the page, a notice or a slot sees it. Ids and paths are not
+masked (a session id is 36 characters of `[0-9a-f-]` and would read as a key). A transcript path is shown only if it is under
+`<configDir>/projects/` with no `..` part.
+
+**Keys.** A pane hotkey is one lowercase letter or digit (the engine refuses `[ ] ? Enter`; found when the matrix mounted the page), and
+`h` is Help's. So: `j k` move, `b` / `l` focus the phases / agents column, `u` / `i` switch run, `d` inspects or closes the inspector.
+Each is also a button, so Enter on a focused button and the mouse work; Esc stays the pane's. `/ruflo next|prev` moves the cursor as `j k`.
+View-local keys shadow tab keys while the page is open, as Claims' do. ADR-458's stop-agent hotkey `x` (the footer's Actions) was removed.
+
+**Notices.** A workflow run that changed to finished or failed between two reads raises one band notice (deduped by the notice ring).
+Reads happen only while the page is open, so this is not a background watcher; it says what changed while the person looked.
+
+**What the console cannot do.** It cannot stop or message a running Claude Code workflow. Where those buttons would be, the page says so
+and where to do it (Claude Code's Workflows panel, TaskStop). The only writes are ADR-458's: stop and spawn a ruflo agent behind the confirm card.
+
+**Seams.** `views/wf-slots.ts` is a registry; features call `registerSlot` from their own module and edit no shared file. Kinds:
+`board` (a section under the run board), `tab` (an inspector tab), `key` (a hotkey button), `action` (a confirm-gated ruflo verb), `notice`
+(drafts after a read). Registration is pure and refuses, with a reason and no throw: a bad or repeated id, a missing function or title, a
+hotkey that is not one lowercase letter or digit, a hotkey the page owns (`p x r h y n j k l b d o u i`) or another slot holds, and a
+13th slot of a kind. A slot that throws is caught where it is called and costs one line. `views/wf-register.ts` is the only file the
+merge owner edits: one `import '../wf-<feature>'` line per feature.
+
+## 3. Consequences
+
+- The page is reachable and live, and costs nothing while it is closed.
+- Six writers can extend it without touching `state.ts`, `controller.ts`, `pane.ts`, `bindings.ts` or the page itself.
+- A slot's own drawing is not washed by the page: a slot that draws file text must call `cleanText` (exported from `data/wf-clean.ts`).
+ Notice text from a slot is washed by the registry's caller.
+- The run record of a finished run appears up to 10 s late (the reader's missing-file recheck), so a finish notice can lag by that and a tick.
+- Keyless: it is not in the tab bar unless open; the nav, the menu and the name reach it.
+
+## 4. Test and benchmark plan
+
+`tests/wf-wire.spec.ts` (22 tests, vitest, no engine): reachability, refresh gating (other view, closed pane), join of a concurrent read,
+error path, washing, notices (first read silent, finish raises one, slot notices masked, throwing slot contained), keys and hotkeys, path
+validation, page drawing at 40/80/150 columns, every slot kind, and the registry's refusals. Mutation-checked: removing a reserved key, the
+slot cap, the `..` check, the view gate, the first-read guard, the mask and the cannot-stop line each fail a test. The engine matrix
+(`tests/matrix.test.ts`) mounts the page at 80 and 150 columns. Benchmark: `scripts/bench-swarmui.mjs` (ADR-458) already covers the read and
+the draw at 1k and 10k agents; the wiring adds one `Map` build per read.
+
+## 5. Rollback
+
+Remove the `workflows` row from `VIEWS` and the type, the five registrations (nav row, menu section, boot module, area row, ask entry), the
+`wf` field, the one call in `controller.ts` and the `pane.ts` body. The data modules and ADR-458's view stay; nothing is persisted.