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,mods): session workspace on the Room: attention queue, session browser, preview (ADR-486)

rc53bed71e3d7
diff --git a/plugins/ruflo-console/.claude-plugin/plugin.json b/plugins/ruflo-console/.claude-plugin/plugin.json
index 5c7a0a8002..0507614a74 100644
--- a/plugins/ruflo-console/.claude-plugin/plugin.json
+++ b/plugins/ruflo-console/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-console",
"description": "ruflo's cockpit inside Claude Code and the one /ruflo command for every ruflo mod (function hooks, early access). Views: overview with health alerts, swarm topology graph, claims flow with TTL rings, federation map, plugin health matrix, learning curve and pipeline, MetaHarness radar and audit trend, memory, cost gauge, agent timeline, approvals queue, event stream, a main menu, an x.ruv.io federation board, an AI terminal (codex, claude or both in remembered sessions, streamed), Skills (npx skills), a Hive-Mind view, a MetaHarness lab, agent drill-down; a command palette for confirm-gated actions through the ruflo CLI; a band above the prompt. Reads ruflo's files and the CLI's local JSON; anything not measured reads n/a. The one network call it makes by itself is a daily read of the published plugin.json at github.com/ruvnet/ruflo to offer an update (Settings → Updates: ask, auto, or off); it installs only through Claude Code's own claude plugin update, and never a new major version without asking.",
- "version": "0.40.8",
+ "version": "0.41.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -104,6 +104,18 @@
"description": "Keep the Events and Timeline history on disk in this project (.claude-flow/console/: events.jsonl, lanes.jsonl, events-prefs.json, exports/) so a restart does not empty the pages. Text is masked before it is written (credentials, home-directory user names, control characters); nothing leaves the machine and no model reads it. Off writes nothing; the pages still work for the session.",
"default": true
},
+ "sessionWorkspace": {
+ "type": "boolean",
+ "title": "Session workspace",
+ "description": "The Room lists the sessions on this machine (Claude Code, Codex, ruflo missions and workers), started in Ruflo or not, with a Needs you queue (approvals, questions, failures, finished work) and a preview of the one you pick. Local and read-only: it reads session files, makes no model call, starts nothing and wakes no agent. Nothing it reads is written anywhere except which finished sessions you have looked at.",
+ "default": true
+ },
+ "sessionPreview": {
+ "type": "boolean",
+ "title": "Session preview",
+ "description": "Show the latest response, current tool, edited files and test result of the selected session. Off draws none of a session's response, tool, files or test output; the list (with session titles) and the queue still work. Transcript text never goes to a model and is never saved.",
+ "default": true
+ },
"wfBudgetRunUsd": {
"type": "number",
"title": "Workflow budget per run (USD)",
diff --git a/plugins/ruflo-console/CHANGELOG.md b/plugins/ruflo-console/CHANGELOG.md
index 8b6b1d329d..15d0567530 100644
--- a/plugins/ruflo-console/CHANGELOG.md
+++ b/plugins/ruflo-console/CHANGELOG.md
@@ -2,6 +2,10 @@
Newest first. One `## <version> — <date>` heading per version, then `feat:`, `fix:`, `breaking:` and `chore:` bullets (ADR-478). Built from git history; older versions: `git log -- plugins/ruflo-console`.
+## 0.41.0 — 2026-10-09
+- feat: session workspace on the Room (ADR-486): a Needs you queue (approvals, questions, failures, finished work) across Claude Code, Codex and Ruflo sessions, a session browser grouped by repository and worktree, and a preview of the selected session (latest response, current tool, edited files, test result, cost labelled reported, estimated or unavailable). Local and read-only: no model call, no process, no wake. Sessions with an ambiguous identity go to an unassigned bucket and raise nothing. A finished session clears only after its preview was drawn. The Overview shows the four counts. Options: sessionWorkspace, sessionPreview (both on).
+- feat: ruflo-mods can show those four counts: the console keeps them (counts only) in .claude-flow/console/attention.json in a ruflo project.
+
## 0.40.8 — 2026-10-09
- fix: an ADR scope glob with many stars no longer freezes the console: the matcher is a bounded two-pointer scan instead of a regex (a 16-star glob against a short path took 38 s; it now takes microseconds, at the real input caps under 10 ms for 9,600 pairs); results are identical on legitimate globs (ADR-480)
- fix: an ADR title over 120 characters is refused with the count on every path (the page field, the `adr-propose` palette entry, `/ruflo run`, `console_run`) instead of being cut into the file name, and a draft whose title was shortened from a mission's objective says so on the confirm card (ADR-481)
diff --git a/plugins/ruflo-console/README.md b/plugins/ruflo-console/README.md
index eb591b7df6..222e04b6c8 100644
--- a/plugins/ruflo-console/README.md
+++ b/plugins/ruflo-console/README.md
@@ -54,6 +54,7 @@ Settings → Interface and updates → **Toasts** sets what the ruflo plugins ma
Open it with `/ruflo room` (menu: Safety → The Room).
- **Waiting for a yes**: the one confirm that is pending, with the seconds left to answer it.
+- **Needs you, Sessions, Preview** (ADR-486): approvals, questions, failures and finished work across Claude Code, Codex and Ruflo sessions, including ones started outside Ruflo; the sessions grouped by repository and worktree; and a preview of the one you pick (latest response, current tool, edited files, test result, cost labelled reported, estimated or unavailable). Local and read-only: no model call, no process, nothing woken. A finished session leaves the queue only after its preview was drawn; a session whose identity is ambiguous goes to an *unassigned* bucket and raises nothing. Transcript text is never saved, never sent to a model and never included in a text answer. Options `sessionWorkspace` and `sessionPreview` (both on).
- **The feed**: events, Claude's console actions and what you said, newest first. Filter by who, search, pause, page back. **⛔ blocked** shows only what was refused or failed: Claude's actions the control log marked denied or error, and events that say denied. Press a line to open it; an event that came from a page of its own (swarm, claims, learning, plugins, missions) offers a jump button to that page.
- **Mods**: one line per plugin mod that has written `.claude-flow/<name>-mod/status.json`. Press a line for its detail: what it guards (the file's own `summary`), guard, calls, blocked, the *class* of its last refusal (`secret`, `destructive`, `path`, `network`, `policy`, `other`; the refused text is never kept), `modVersion`, session start, last write, file age, and a stale marker when the last write was an earlier session.
diff --git a/plugins/ruflo-console/hooks/bindings.ts b/plugins/ruflo-console/hooks/bindings.ts
index 01d6a3aeac..c9a6e71482 100644
--- a/plugins/ruflo-console/hooks/bindings.ts
+++ b/plugins/ruflo-console/hooks/bindings.ts
@@ -45,6 +45,7 @@ import { UPDATES_KEY } from './updates'
import { setToastMode, toggleToastMute } from './toasts'
import { whatsnewActions } from './whatsnew'
import { adrActions } from './adr-actions'
+import { sessionActions } from './sessions'
import { vectorActions } from './vector'
import type { Actions } from './views/common'
import { openTasks, selection } from './views/select'
@@ -405,6 +406,7 @@ export function actionsOf(state: State, host: Host, runner: Runner, steps: Steps
watch: watchActions(state, () => host.invalidate(), (question, view) => actions.ask.ask(question, view)),
events: eventsActions(state, host, () => host.invalidate(), (spec, why = 'that cannot run here') => runner.ask(spec, why), question => actions.ask.ask(question, 'events')),
timeline: timelineActions(state, host, () => host.invalidate(), id => setView(id), (spec, why = 'that cannot run here') => runner.ask(spec, why), question => actions.ask.ask(question, 'timeline')),
+ sessions: sessionActions(state, host),
room: roomActions(state, () => host.invalidate(), (id, text) => runner.runById(id, text), () => roomPages(state)),
navigator: navActions(state, () => host.invalidate(), view => actions.view(view)),
catalog: catalogActions(state, host, runner, text => actions.term.load('claude', text)),
diff --git a/plugins/ruflo-console/hooks/data/harness-claude.ts b/plugins/ruflo-console/hooks/data/harness-claude.ts
new file mode 100644
index 0000000000..77c67cdbbc
--- /dev/null
+++ b/plugins/ruflo-console/hooks/data/harness-claude.ts
@@ -0,0 +1,246 @@
+/**
+ * The `claude` adapter (ADR-486): sessions Claude Code keeps as `<config dir>/projects/<folder>/<session id>.jsonl`. The format was read
+ * on this machine for the entry types used here (user and assistant lines with `message.content` blocks, `tool_use` and `tool_result`,
+ * `ai-title`, `cost-state`, `system/turn_duration`); a line of any other shape is ignored, never guessed at. The file name is the session id
+ * (every entry's own `sessionId` was checked to match it); an entry that names another id makes the row unassigned.
+ * Declared: discovery and preview. Claude Code writes no approval request into the transcript, so `approvals` is not claimed.
+ */
+import { repoOf, no, yes, type Capabilities, type HarnessAdapter, type Preview, type ScanEnv, type ScanResult, type SessionRow, type SessionStatus, type Signals } from './harness'
+import { isRecord, isTestCommand, scanRecords, shown, str, testLine, timeMs } from './harness-text'
+import { settle, type Candidate, type Memory } from './harness-track'
+import { under } from './files'
+
+export const CLAUDE_CAPS: Capabilities = {
+ discovery: yes('projects/<folder>/<session id>.jsonl'),
+ preview: yes('latest assistant text, last tool, edited files, test output'),
+ approvals: no('Claude Code does not write a pending permission request into the transcript'),
+ resume: no('opening a session is a model turn; not offered from browsing'),
+ fork: no('not in phase 1'),
+ messaging: no('not in phase 1'),
+ stop: no('not in phase 1'),
+}
+
+export type ClaudeSummary = {
+ cwd: string | null
+ branch: string | null
+ title: string | null
+ idMismatch: boolean
+ lastAtMs: number | null
+ pendingTool: string | null
+ preview: Preview
+ signals: Signals
+ costUsd: number | null
+ costPartial: boolean
+}
+
+const EDITS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit'])
+const FILES_MAX = 8
+const ACTIVE_MS = 90_000
+const FAIL_QUIET_MS = 30_000
+
+export function summarizeClaude(text: string, id: string): ClaudeSummary {
+ const out: ClaudeSummary = { cwd: null, branch: null, title: null, idMismatch: false, lastAtMs: null, pendingTool: null, preview: { latest: '', tool: null, files: [], test: null }, signals: { question: false, approval: false, failed: false, turnEndedAtMs: null }, costUsd: null, costPartial: false }
+ const open = new Map<string, { name: string; command: string }>()
+ let prompt: string | null = null
+ let lastErrorAtMs: number | null = null
+ let convAtMs = 0
+ let afterError = false
+
+ scanRecords(text, record => {
+ const at = timeMs(record.timestamp)
+ const type = str(record.type)
+
+ if (str(record.sessionId) !== undefined && record.sessionId !== id) out.idMismatch = true
+ if (record.isSidechain === true) return
+ if (at !== undefined) out.lastAtMs = Math.max(out.lastAtMs ?? 0, at)
+ if (str(record.cwd) !== undefined) out.cwd = shown(record.cwd, 400) || out.cwd
+ if (str(record.gitBranch) !== undefined) out.branch = shown(record.gitBranch, 60)
+
+ if ((type === 'assistant' || type === 'user') && at !== undefined) convAtMs = Math.max(convAtMs, at)
+
+ if (type === 'ai-title') out.title = shown(record.aiTitle, 80) || out.title
+ else if (type === 'last-prompt') prompt = shown(record.lastPrompt, 80) || prompt
+ else if (type === 'cost-state') {
+ out.costUsd = typeof record.totalCostUSD === 'number' && Number.isFinite(record.totalCostUSD) && record.totalCostUSD >= 0 ? record.totalCostUSD : out.costUsd
+ out.costPartial = record.hasUnknownModelCost === true
+ } else if (type === 'system' && record.subtype === 'turn_duration') {
+ if (at !== undefined) out.signals.turnEndedAtMs = at
+ } else if ((type === 'assistant' || type === 'user') && isRecord(record.message) && Array.isArray(record.message.content)) {
+ for (const block of record.message.content as unknown[]) {
+ if (!isRecord(block)) continue
+
+ if (block.type === 'text' && type === 'assistant') {
+ const line = shown(block.text, 600)
+
+ if (line !== '') out.preview.latest = line
+ afterError = false
+ } else if (block.type === 'tool_use' && type === 'assistant') {
+ const name = shown(block.name, 40)
+ const input = isRecord(block.input) ? block.input : {}
+ const command = typeof input.command === 'string' ? input.command.slice(0, 600) : ''
+
+ if (typeof block.id === 'string') open.set(block.id.slice(0, 100), { name, command })
+ out.preview.tool = name
+ if (name === 'AskUserQuestion') out.signals.question = true
+ if (EDITS.has(name)) {
+ const file = shown(input.file_path ?? input.notebook_path, 120)
+
+ if (file !== '' && !out.preview.files.includes(file)) out.preview.files = [...out.preview.files, file].slice(-FILES_MAX)
+ }
+
+ afterError = false
+ } else if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') {
+ const call = open.get(block.tool_use_id.slice(0, 100))
+ const failed = block.is_error === true
+
+ open.delete(block.tool_use_id.slice(0, 100))
+ if (call?.name === 'AskUserQuestion') out.signals.question = false
+ afterError = failed
+ lastErrorAtMs = failed ? (at ?? null) : lastErrorAtMs
+
+ if (call !== undefined && isTestCommand(call.command)) {
+ const body = typeof block.content === 'string' ? block.content : Array.isArray(block.content) ? block.content.map(part => (isRecord(part) && typeof part.text === 'string' ? part.text : '')).join('\n') : ''
+
+ out.preview.test = `${failed ? 'failed' : 'passed'}${testLine(body) === null ? '' : `: ${testLine(body)}`}`
+ }
+ }
+ }
+ }
+ })
+
+ out.signals.failed = afterError && lastErrorAtMs !== null && open.size === 0
+ out.pendingTool = open.size > 0 ? [...open.values()].map(call => call.name).pop() ?? null : null
+ out.title = out.title ?? prompt
+ if (out.pendingTool === null) out.signals.question = false
+ // A turn that ended and was followed by a message has not ended: only the last conversation line may be the end.
+ if (out.signals.turnEndedAtMs !== null && out.signals.turnEndedAtMs < convAtMs) out.signals.turnEndedAtMs = null
+
+ return out
+}
+
+const statusOf = (s: ClaudeSummary, mtimeMs: number, nowMs: number): SessionStatus => {
+ if (s.signals.failed && nowMs - mtimeMs >= FAIL_QUIET_MS) return 'failed'
+ if (nowMs - mtimeMs < ACTIVE_MS) return 'working'
+
+ return s.signals.turnEndedAtMs !== null && s.pendingTool === null ? 'done' : 'idle'
+}
+
+export function claudeRow(cand: Candidate, held: { value: ClaudeSummary | null; noPreview: string | null; stale: string | null }, home: string, nowMs: number): SessionRow {
+ const s = held.value
+ const where = s === null ? null : s.cwd
+ const split = where === null ? { repo: cand.folder, worktree: null } : repoOf(where)
+
+ return {
+ key: `claude:${home}:${cand.nativeId}`,
+ harness: 'claude',
+ home,
+ nativeId: cand.nativeId,
+ title: s?.title ?? `session ${cand.nativeId.slice(0, 8)}`,
+ status: s === null ? 'unknown' : statusOf(s, cand.mtimeMs, nowMs),
+ cwd: where,
+ folder: cand.folder,
+ repo: split.repo,
+ worktree: split.worktree,
+ branch: s?.branch ?? null,
+ mission: null,
+ updatedMs: cand.mtimeMs,
+ size: cand.size,
+ unassigned: s?.idMismatch === true ? 'an entry names a different session id than the file' : null,
+ stale: held.stale,
+ external: true,
+ cost: s === null || s.costUsd === null ? { label: 'unavailable', note: 'the transcript holds no cost entry' } : { label: 'reported', usd: s.costUsd, ...(s.costPartial && { note: 'some models unpriced' }) },
+ signals: s?.signals ?? { question: false, approval: false, failed: false, turnEndedAtMs: null },
+ preview: s === null ? null : s.preview,
+ context: [],
+ noPreview: held.noPreview,
+ }
+}
+
+const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+const FOLDER = /^[A-Za-z0-9._-]{1,200}$/
+const MAX_DIRS = 400
+const MAX_TRACKED = 60
+const RECENT_MS = 14 * 86_400_000
+const FAST_DIRS = 8
+
+export function claudeAdapter(): HarnessAdapter & { reset(): void } {
+ const memory: Memory<ClaudeSummary> = new Map()
+ const dirs = new Map<string, number>()
+ const known = new Map<string, Candidate>()
+ let last: SessionRow[] = []
+
+ const relist = async (fs: ScanEnv['fs'], root: string, folder: string): Promise<boolean> => {
+ try {
+ const list = await fs.list(under(root, folder))
+
+ const names = new Set(list.map(entry => under(under(root, folder), entry.name)))
+
+ for (const [path, cand] of known) if (cand.folder === folder && !names.has(path)) known.delete(path)
+
+ for (const entry of list.slice(0, 5000)) {
+ const id = /^(.*)\.jsonl$/.exec(entry.name)?.[1]
+
+ if (id === undefined || !ID.test(id) || (entry.kind !== undefined && entry.kind !== 'file')) continue
+
+ const path = under(under(root, folder), entry.name)
+
+ known.set(path, { path, nativeId: id, folder, size: entry.size ?? 0, mtimeMs: entry.mtimeMs ?? 0 })
+ }
+
+ return true
+ } catch {
+ return false
+ }
+ }
+
+ return {
+ id: 'claude',
+ label: 'Claude Code',
+ capabilities: CLAUDE_CAPS,
+ reset: () => {
+ memory.clear()
+ dirs.clear()
+ known.clear()
+ last = []
+ },
+ async scan(env: ScanEnv): Promise<ScanResult> {
+ if (env.claudeDir === null) return { state: 'not-detected', rows: [], note: 'no Claude Code config directory is known' }
+
+ const home = env.claudeDir.replace(/\/+$/, '')
+ const root = under(home, 'projects')
+ let entries: Awaited<ReturnType<ScanEnv['fs']['list']>>
+
+ try {
+ entries = await env.fs.list(root)
+ } catch {
+ return last.length === 0 ? { state: 'not-detected', rows: [], note: 'no projects folder' } : { state: 'failed', rows: last.map(row => ({ ...row, stale: row.stale ?? 'discovery failed; showing the last read' })), note: 'could not list the projects folder; rows are from the last read' }
+ }
+
+ const folders = entries.filter(entry => FOLDER.test(entry.name) && !entry.name.includes('..') && (entry.kind === undefined || entry.kind === 'dir' || entry.kind === 'directory')).slice(0, MAX_DIRS)
+ const recentFolders = new Set([...known.values()].sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, FAST_DIRS).map(cand => cand.folder))
+ let failedDirs = 0
+
+ for (const folder of folders) {
+ const seen = dirs.get(folder.name)
+
+ if (env.full || seen === undefined || seen !== (folder.mtimeMs ?? 0) || recentFolders.has(folder.name)) {
+ if (await relist(env.fs, root, folder.name)) dirs.set(folder.name, folder.mtimeMs ?? 0)
+ else failedDirs += 1
+ }
+ }
+
+ const names = new Set(folders.map(folder => folder.name))
+
+ for (const [path, cand] of known) if (!names.has(cand.folder)) known.delete(path)
+
+ const tracked = [...known.values()].filter(cand => env.nowMs - cand.mtimeMs < RECENT_MS || cand.mtimeMs === 0).sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, MAX_TRACKED)
+ const settled = await settle(env.fs, memory, tracked, (text, _whole, cand) => summarizeClaude(text, cand.nativeId))
+
+ for (const path of [...memory.keys()]) if (!known.has(path)) memory.delete(path)
+
+ last = settled.map(({ cand, held }) => claudeRow(cand, held, home, env.nowMs))
+
+ return { state: 'ok', rows: last, note: failedDirs > 0 ? `${failedDirs} project folder${failedDirs === 1 ? '' : 's'} could not be listed` : `${folders.length} project folders, ${known.size} sessions seen, ${last.length} tracked` }
+ },
+ }
+}
diff --git a/plugins/ruflo-console/hooks/data/harness-codex.ts b/plugins/ruflo-console/hooks/data/harness-codex.ts
new file mode 100644
index 0000000000..ffcc95750a
--- /dev/null
+++ b/plugins/ruflo-console/hooks/data/harness-codex.ts
@@ -0,0 +1,183 @@
+/**
+ * The `codex` adapter (ADR-486): rollouts Codex keeps as `<codex dir>/sessions/YYYY/MM/DD/rollout-<time>-<session id>.jsonl`, lines of
+ * `{timestamp, type, payload}`. Verified here: `session_meta` (id, cwd), `turn_context` (cwd), `event_msg` task_started / task_complete
+ * (last_agent_message) / turn_aborted (reason), and `response_item` function_call / custom_tool_call with their `_output` by call_id.
+ * Not seen in any rollout, so not claimed: an approval request, a cost, a question. Declared: discovery and preview.
+ */
+import { under } from './files'
+import { no, yes, repoOf, type Capabilities, type HarnessAdapter, type Preview, type ScanEnv, type ScanResult, type SessionRow, type SessionStatus, type Signals } from './harness'
+import { isRecord, scanRecords, shown, str, timeMs } from './harness-text'
+import { settle, type Candidate, type Memory } from './harness-track'
+
+export const CODEX_CAPS: Capabilities = {
+ discovery: yes('sessions/YYYY/MM/DD/rollout-*.jsonl'),
+ preview: yes('last agent message, last tool call'),
+ approvals: no('no approval request appears in the rollouts read'),
+ resume: no('opening a session is a model turn; not offered from browsing'),
+ fork: no('not in phase 1'),
+ messaging: no('not in phase 1'),
+ stop: no('not in phase 1'),
+}
+
+export type CodexSummary = { id: string | null; cwd: string | null; lastAtMs: number | null; open: boolean; pendingTool: string | null; preview: Preview; signals: Signals; title: string | null }
+
+export function summarizeCodex(text: string): CodexSummary {
+ const out: CodexSummary = { id: null, cwd: null, lastAtMs: null, open: false, pendingTool: null, preview: { latest: '', tool: null, files: [], test: null }, signals: { question: false, approval: false, failed: false, turnEndedAtMs: null }, title: null }
+ const calls = new Map<string, string>()
+
+ scanRecords(text, record => {
+ const at = timeMs(record.timestamp)
+ const payload = isRecord(record.payload) ? record.payload : {}
+ const type = str(record.type)
+ const kind = str(payload.type)
+
+ if (at !== undefined) out.lastAtMs = Math.max(out.lastAtMs ?? 0, at)
+
+ if (type === 'session_meta') {
+ out.id = str(payload.id)?.slice(0, 64) ?? out.id
+ out.cwd = shown(payload.cwd, 400) || out.cwd
+ } else if (type === 'turn_context') out.cwd = shown(payload.cwd, 400) || out.cwd
+ else if (type === 'event_msg' && kind === 'task_started') {
+ out.open = true
+ out.signals.turnEndedAtMs = null
+ out.signals.failed = false
+ } else if (type === 'event_msg' && kind === 'task_complete') {
+ out.open = false
+ out.signals.turnEndedAtMs = at ?? out.signals.turnEndedAtMs
+ out.signals.failed = false
+
+ const last = shown(payload.last_agent_message, 600)
+
+ if (last !== '') out.preview.latest = last
+ } else if (type === 'event_msg' && kind === 'turn_aborted') {
+ out.open = false
+ out.signals.failed = true
+ out.preview.latest = `turn aborted${str(payload.reason) === undefined ? '' : `: ${shown(payload.reason, 60)}`}`
+ } else if (type === 'response_item' && (kind === 'function_call' || kind === 'custom_tool_call') && typeof payload.call_id === 'string') {
+ calls.set(payload.call_id.slice(0, 100), shown(payload.name, 40))
+ out.preview.tool = shown(payload.name, 40)
+ } else if (type === 'response_item' && (kind === 'function_call_output' || kind === 'custom_tool_call_output') && typeof payload.call_id === 'string') calls.delete(payload.call_id.slice(0, 100))
+ })
+
+ out.pendingTool = calls.size > 0 ? [...calls.values()].pop() ?? null : null
+
+ return out
+}
+
+const idOfName = (name: string): string | undefined => /^rollout-.{1,40}?-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/.exec(name)?.[1]
+const ACTIVE_MS = 90_000
+const DAYS = 14
+const MAX_TRACKED = 60
+
+const statusOf = (s: CodexSummary, mtimeMs: number, nowMs: number): SessionStatus => {
+ if (s.signals.failed) return 'failed'
+ if (s.open && nowMs - mtimeMs < ACTIVE_MS * 4) return 'working'
+
+ return s.signals.turnEndedAtMs !== null ? 'done' : 'idle'
+}
+
+const pad = (n: number) => String(n).padStart(2, '0')
+const dayDirs = (nowMs: number, days: number): string[] => {
+ const out = new Set<string>()
+
+ for (let i = 0; i < days; i += 1) {
+ const d = new Date(nowMs - i * 86_400_000)
+
+ out.add(`${d.getUTCFullYear()}/${pad(d.getUTCMonth() + 1)}/${pad(d.getUTCDate())}`)
+ out.add(`${d.getFullYear()}/${pad(d.getMonth() + 1)}/${pad(d.getDate())}`)
+ }
+
+ return [...out]
+}
+
+export function codexRow(cand: Candidate, held: { value: CodexSummary | null; noPreview: string | null; stale: string | null }, home: string, nowMs: number): SessionRow {
+ const s = held.value
+ const where = s?.cwd ?? null
+ const split = where === null ? { repo: cand.folder, worktree: null } : repoOf(where)
+
+ return {
+ key: `codex:${home}:${cand.nativeId}`,
+ harness: 'codex',
+ home,
+ nativeId: cand.nativeId,
+ title: s === null ? `rollout ${cand.nativeId.slice(0, 8)}` : s.preview.latest !== '' ? s.preview.latest.slice(0, 80) : `rollout ${cand.nativeId.slice(0, 8)}`,
+ status: s === null ? 'unknown' : statusOf(s, cand.mtimeMs, nowMs),
+ cwd: where,
+ folder: cand.folder,
+ repo: split.repo,
+ worktree: split.worktree,
+ branch: null,
+ mission: null,
+ updatedMs: cand.mtimeMs,
+ size: cand.size,
+ unassigned: s?.id != null && s.id !== cand.nativeId ? 'session_meta names a different id than the file' : null,
+ stale: held.stale,
+ external: true,
+ cost: { label: 'unavailable', note: 'rollouts carry token counts, not dollars' },
+ signals: s?.signals ?? { question: false, approval: false, failed: false, turnEndedAtMs: null },
+ preview: s === null ? null : s.preview,
+ context: [],
+ noPreview: held.noPreview,
+ }
+}
+
+export function codexAdapter(): HarnessAdapter & { reset(): void } {
+ const memory: Memory<CodexSummary> = new Map()
+ const known = new Map<string, Candidate>()
+ let last: SessionRow[] = []
+ let detected = false
+
+ return {
+ id: 'codex',
+ label: 'Codex',
+ capabilities: CODEX_CAPS,
+ reset: () => {
+ memory.clear()
+ known.clear()
+ last = []
+ detected = false
+ },
+ async scan(env: ScanEnv): Promise<ScanResult> {
+ if (env.codexDir === null) return { state: 'not-detected', rows: [], note: 'no Codex directory is known' }
+
+ const home = env.codexDir.replace(/\/+$/, '')
+ const root = under(home, 'sessions')
+
+ try {
+ await env.fs.list(root)
+ detected = true
+ } catch {
+ return detected ? { state: 'failed', rows: last.map(row => ({ ...row, stale: row.stale ?? 'discovery failed; showing the last read' })), note: 'could not list the sessions folder; rows are from the last read' } : { state: 'not-detected', rows: [], note: 'not detected: no Codex sessions folder' }
+ }
+
+ for (const day of dayDirs(env.nowMs, env.full ? DAYS : 2)) {
+ try {
+ const dir = under(root, day)
+ const list = await env.fs.list(dir)
+ const names = new Set(list.map(entry => under(dir, entry.name)))
+
+ for (const [path, cand] of known) if (cand.folder === day && !names.has(path)) known.delete(path)
+
+ for (const entry of list.slice(0, 5000)) {
+ const id = idOfName(entry.name)
+
+ if (id === undefined || (entry.kind !== undefined && entry.kind !== 'file')) continue
+
+ known.set(under(dir, entry.name), { path: under(dir, entry.name), nativeId: id, folder: day, size: entry.size ?? 0, mtimeMs: entry.mtimeMs ?? 0 })
+ }
+ } catch {
+ // A day with no folder has no sessions.
+ }
+ }
+
+ const tracked = [...known.values()].sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, MAX_TRACKED)
+ const settled = await settle(env.fs, memory, tracked, text => summarizeCodex(text))
+
+ for (const path of [...memory.keys()]) if (!known.has(path)) memory.delete(path)
+
+ last = settled.map(({ cand, held }) => codexRow(cand, held, home, env.nowMs))
+
+ return { state: 'ok', rows: last, note: `${known.size} rollouts seen, ${last.length} tracked` }
+ },
+ }
+}
diff --git a/plugins/ruflo-console/hooks/data/harness-ruflo.ts b/plugins/ruflo-console/hooks/data/harness-ruflo.ts
new file mode 100644
index 0000000000..2ea14db44a
--- /dev/null
+++ b/plugins/ruflo-console/hooks/data/harness-ruflo.ts
@@ -0,0 +1,134 @@
+/**
+ * The `ruflo` worker adapter (ADR-486): what the console already knows without reading a transcript. A mission as the CLI observed it
+ * (`.claude-flow/missions/observation.json`, ADR-406) and the agents the swarm and hive stores list. Nothing is read from disk here;
+ * a state the observation does not record is not invented. `awaitingAuthorization` is the one state that means "waiting for a yes".
+ */
+import { no, yes, type Capabilities, type HarnessAdapter, type ScanEnv, type ScanResult, type SessionRow, type SessionStatus } from './harness'
+import type { Mission, MissionObservation } from './missions'
+import type { AgentRecord } from './parse'
+import { shown } from './harness-text'
+
+export const RUFLO_CAPS: Capabilities = {
+ discovery: yes('the mission observation and the agent stores the console already reads'),
+ preview: yes('state, task and evidence counts; there is no transcript to show'),
+ approvals: yes('a mission in awaitingAuthorization is waiting for a yes'),
+ resume: no('missions are driven from the Missions page'),
+ fork: no('not in phase 1'),
+ messaging: no('broadcast and guide stay on the Room and Missions pages, each asking first'),
+ stop: no('pause and cancel stay on the Missions page, each asking first'),
+}
+
+/** What the console's own mission ledger and claims add to an observed mission, by mission id; each is shown only when it holds something. */
+export type LedgerFacts = { adrs?: readonly string[]; tasks: readonly { id: string; dependsOn: readonly string[]; rufloTaskId?: string }[] }
+export type RufloInput = { cwd: string; missions: MissionObservation | null; agents: readonly AgentRecord[]; nowMs: number; ledger?: ReadonlyMap<string, LedgerFacts>; claimedIssues?: ReadonlySet<string> }
+
+function contextOf(mission: Mission, input: RufloInput): string[] {
+ const lines: string[] = []
+ const facts = input.ledger?.get(mission.id)
+ const active = mission.plan.tasks.find(task => task.status === 'running' || task.status === 'inProgress' || task.status === 'in_progress')
+
+ if (active !== undefined) lines.push(`task ${shown(active.id, 30)}: ${shown(active.title, 80)}${active.dependsOn.length === 0 ? '' : ` · after ${active.dependsOn.slice(0, 4).map(dep => shown(dep, 20)).join(', ')}`}`)
+ if (facts !== undefined) {
+ const claimed = facts.tasks.filter(task => input.claimedIssues?.has(task.id) === true || (task.rufloTaskId !== undefined && input.claimedIssues?.has(task.rufloTaskId) === true)).length
+
+ if (claimed > 0) lines.push(`claims: ${claimed} of this mission's tasks are claimed`)
+ if ((facts.adrs ?? []).length > 0) lines.push(`ADRs: ${(facts.adrs ?? []).slice(0, 4).map(adr => shown(adr, 50)).join(', ')}`)
+ }
+
+ if (mission.evidence.count > 0) lines.push(`verification: ${mission.evidence.verified} of ${mission.evidence.count} evidence verified`)
+
+ return lines
+}
+
+const MISSION_STATUS: Record<string, SessionStatus> = { running: 'working', verifying: 'working', queued: 'working', completed: 'done', failed: 'failed' }
+const AGENT_BAD = /^(?:failed|error|crashed|dead)$/i
+const AGENT_BUSY = /^(?:busy|working|running|active)$/i
+
+const costOf = (mission: Mission): SessionRow['cost'] => {
+ const budget = mission.budget
+
+ if (budget === null) return { label: 'unavailable', note: 'the mission records no budget' }
+ if (budget.settledMinor !== undefined) return budget.currency === 'USD' ? { label: 'reported', usd: budget.settledMinor / 100 } : { label: 'reported', note: `${budget.currency} ${budget.settledMinor} minor units` }
+ if (budget.estimatedMinor !== undefined) return budget.currency === 'USD' ? { label: 'estimated', usd: budget.estimatedMinor / 100 } : { label: 'estimated', note: `${budget.currency} ${budget.estimatedMinor} minor units` }
+
+ return { label: 'unavailable', note: 'the mission records no spend' }
+}
+
+export function rufloRows(input: RufloInput): SessionRow[] {
+ const home = 'ruflo'
+ const rows: SessionRow[] = []
+
+ for (const mission of input.missions?.missions ?? []) {
+ const tasks = mission.plan.tasks
+ const done = tasks.filter(task => task.status === 'completed' || task.status === 'done').length
+
+ rows.push({
+ key: `ruflo:${home}:mission-${mission.id}`,
+ harness: 'ruflo',
+ home,
+ nativeId: `mission-${mission.id}`,
+ title: shown(mission.objective, 80) || mission.id,
+ status: MISSION_STATUS[mission.state] ?? 'idle',
+ cwd: input.cwd,
+ folder: 'missions',
+ repo: input.cwd,
+ worktree: null,
+ branch: null,
+ mission: mission.id,
+ updatedMs: mission.updatedAtMs ?? input.missions?.observedAtMs ?? 0,
+ size: 0,
+ unassigned: null,
+ stale: null,
+ external: false,
+ cost: costOf(mission),
+ signals: { question: false, approval: mission.state === 'awaitingAuthorization', failed: mission.state === 'failed', turnEndedAtMs: mission.state === 'completed' ? (mission.updatedAtMs ?? null) : null },
+ context: contextOf(mission, input),
+ preview: { latest: `${mission.state}${mission.blockedReason === undefined ? '' : `: ${shown(mission.blockedReason, 120)}`} · ${done} of ${tasks.length} tasks · ${mission.evidence.verified} of ${mission.evidence.count} evidence verified`, tool: null, files: [], test: mission.evidence.count === 0 ? null : `${mission.evidence.verified} of ${mission.evidence.count} verified` },
+ noPreview: null,
+ })
+ }
+
+ for (const agent of input.agents.slice(0, 40)) {
+ const name = shown(agent.name ?? agent.id, 40)
+
+ rows.push({
+ key: `ruflo:${home}:agent-${agent.id}`,
+ harness: 'ruflo',
+ home,
+ nativeId: `agent-${agent.id}`,
+ title: `${name} (${shown(agent.type, 20)})`,
+ status: AGENT_BAD.test(agent.status) ? 'failed' : AGENT_BUSY.test(agent.status) ? 'working' : 'idle',
+ cwd: input.cwd,
+ folder: 'workers',
+ repo: input.cwd,
+ worktree: null,
+ branch: null,
+ mission: null,
+ updatedMs: agent.createdAtMs ?? 0,
+ size: 0,
+ unassigned: null,
+ stale: null,
+ external: false,
+ cost: { label: 'unavailable', note: 'the agent store records no spend' },
+ signals: { question: false, approval: false, failed: AGENT_BAD.test(agent.status), turnEndedAtMs: null },
+ context: [],
+ preview: { latest: `${shown(agent.status, 20)}${agent.taskCount === undefined ? '' : ` · ${agent.taskCount} tasks`}`, tool: null, files: [], test: null },
+ noPreview: null,
+ })
+ }
+
+ return rows
+}
+
+export function rufloAdapter(input: () => RufloInput): HarnessAdapter {
+ return {
+ id: 'ruflo',
+ label: 'Ruflo workers',
+ capabilities: RUFLO_CAPS,
+ async scan(_env: ScanEnv): Promise<ScanResult> {
+ const rows = rufloRows(input())
+
+ return { state: rows.length === 0 ? 'not-detected' : 'ok', rows, note: rows.length === 0 ? 'no missions or agents recorded' : `${rows.length} missions and workers` }
+ },
+ }
+}
diff --git a/plugins/ruflo-console/hooks/data/harness-text.ts b/plugins/ruflo-console/hooks/data/harness-text.ts
new file mode 100644
index 0000000000..5aed7bc9fc
--- /dev/null
+++ b/plugins/ruflo-console/hooks/data/harness-text.ts
@@ -0,0 +1,91 @@
+/**
+ * Bounded reading of a harness's JSONL (ADR-486). A session file is another process's output and may be huge, truncated, binary or hostile:
+ * a window is at most TAIL_BYTES from the end (where the host offers `readTail`) or the whole file when it is under READ_MAX; a line over
+ * LINE_CAP is skipped unparsed; at most MAX_LINES lines are looked at; nothing here uses a backtracking pattern on file text.
+ */
+import { READ_MAX } from './files'
+import type { SessionFs } from './harness'
+import { cleanText } from './wf-clean'
+import { plain } from './parse'
+
+export const TAIL_BYTES = 262_144
+export const LINE_CAP = 400_000
+export const MAX_LINES = 30_000
+
+export type Window = { text: string; whole: boolean } | { text: null; reason: 'missing' | 'refused' | 'not-regular' | 'too-large' }
+
+/** The text one session file can be summarised from, given its size from a stat that already ruled out links. Never reads what the host cannot bound. */
+export async function readWindow(fs: SessionFs, path: string, size: number): Promise<Window> {
+ try {
+ if (size <= READ_MAX) return { text: (await fs.read(path)).slice(0, READ_MAX), whole: true }
+ if (fs.readTail === undefined) return { text: null, reason: 'too-large' }
+
+ const tail = (await fs.readTail(path, TAIL_BYTES)).slice(-TAIL_BYTES * 2)
+ const cut = tail.indexOf('\n')
+
+ // The first line of a window starts somewhere inside a line: it is dropped, never parsed.
+ return { text: cut < 0 ? '' : tail.slice(cut + 1), whole: false }
+ } catch {
+ return { text: null, reason: 'refused' }
+ }
+}
+
+export type ScanStats = { lines: number; skipped: number; bad: number }
+
+/** Calls `on` with each JSON object line, in order. Skips over-long and non-object lines; stops at MAX_LINES. */
+export function scanRecords(text: string, on: (record: Record<string, unknown>) => void): ScanStats {
+ const stats: ScanStats = { lines: 0, skipped: 0, bad: 0 }
+ let at = 0
+
+ while (at < text.length && stats.lines < MAX_LINES) {
+ let end = text.indexOf('\n', at)
+
+ if (end < 0) end = text.length
+
+ stats.lines += 1
+
+ if (end - at > LINE_CAP) stats.skipped += 1
+ else if (text.charCodeAt(at) === 123 /* { */) {
+ try {
+ const value: unknown = JSON.parse(text.slice(at, end))
+
+ if (typeof value === 'object' && value !== null && !Array.isArray(value)) on(value as Record<string, unknown>)
+ else stats.bad += 1
+ } catch {
+ stats.bad += 1
+ }
+ } else if (end > at) stats.bad += 1
+
+ at = end + 1
+ }
+
+ return stats
+}
+
+/** Free text for a cell: whole escape sequences gone, control and invisible characters gone, credentials masked, one line, cut with an ellipsis. */
+export const shown = (value: unknown, max: number): string => cleanText(plain(typeof value === 'string' ? value.slice(0, max * 4) : '', max))
+
+export const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value)
+export const str = (value: unknown): string | undefined => (typeof value === 'string' ? value : undefined)
+export const timeMs = (value: unknown): number | undefined => {
+ const ms = typeof value === 'string' ? Date.parse(value) : typeof value === 'number' ? value : Number.NaN
+
+ return Number.isFinite(ms) && ms > 946_684_800_000 && ms < 8.64e15 ? ms : undefined
+}
+
+/** A test runner's summary line in a tool's output, found without a backtracking pattern. Null when none is there. */
+export function testLine(output: string): string | null {
+ const lines = output.slice(-6000).split('\n')
+
+ for (let i = lines.length - 1; i >= 0; i -= 1) {
+ const line = (lines[i] ?? '').trim()
+
+ if (line.length > 0 && line.length < 300 && /\b\d+ (?:passed|failed|passing|failing)\b|\btest result:|\bTests?:\s+\d+/.test(line)) return shown(line, 90)
+ }
+
+ return null
+}
+
+const TEST_COMMAND = /\b(?:vitest|jest|pytest|mocha|cargo (?:test|nextest)|npm (?:run )?test|pnpm (?:run )?test|yarn test|go test|node --test)\b/
+
+export const isTestCommand = (command: string): boolean => TEST_COMMAND.test(command.slice(0, 600))
diff --git a/plugins/ruflo-console/hooks/data/harness-track.ts b/plugins/ruflo-console/hooks/data/harness-track.ts
new file mode 100644
index 0000000000..0bd6637c9c
--- /dev/null
+++ b/plugins/ruflo-console/hooks/data/harness-track.ts
@@ -0,0 +1,84 @@
+/**
+ * The incremental half of every file-backed adapter (ADR-486): each candidate is stat-ed (a link is refused, a vanished file is dropped), and
+ * it is read again only when its size or mtime changed. A read that fails keeps the earlier summary and says so (stale), never a blank row.
+ * One pass reads at most PASS_BYTES; what does not fit waits for the next pass, which is how 20 busy sessions stay inside a tick.
+ */
+import { readWindow } from './harness-text'
+import type { SessionFs } from './harness'
+
+export type Candidate = { path: string; nativeId: string; folder: string; size: number; mtimeMs: number }
+export type Held<S> = { mtimeMs: number; size: number; value: S | null; noPreview: string | null; stale: string | null; whole: boolean }
+export type Memory<S> = Map<string, Held<S>>
+
+export const PASS_BYTES = 12_000_000
+const CONCURRENCY = 8
+
+const WHY: Record<string, string> = { 'too-large': 'transcript is larger than this host can read', refused: 'the host refused the read', missing: 'file is gone', 'not-regular': 'not a regular file' }
+
+export async function settle<S>(fs: SessionFs, memory: Memory<S>, cands: readonly Candidate[], summarize: (text: string, whole: boolean, cand: Candidate) => S): Promise<{ cand: Candidate; held: Held<S> }[]> {
+ const out: { cand: Candidate; held: Held<S> }[] = []
+ let budget = PASS_BYTES
+
+ const one = async (cand: Candidate): Promise<void> => {
+ let stat: Awaited<ReturnType<SessionFs['stat']>>
+
+ try {
+ stat = await fs.stat(cand.path)
+ } catch {
+ stat = undefined
+ }
+
+ if (stat === undefined) {
+ memory.delete(cand.path)
+
+ return
+ }
+
+ const before = memory.get(cand.path)
+ const size = stat.size ?? cand.size
+ const mtimeMs = stat.mtimeMs ?? cand.mtimeMs
+
+ if (stat.isLink === true || (stat.kind !== undefined && stat.kind !== 'file')) {
+ const held: Held<S> = { mtimeMs, size, value: null, noPreview: WHY['not-regular'] as string, stale: null, whole: false }
+
+ memory.set(cand.path, held)
+ out.push({ cand: { ...cand, size, mtimeMs }, held })
+
+ return
+ }
+
+ if (before !== undefined && before.mtimeMs === mtimeMs && before.size === size && before.stale === null) {
+ out.push({ cand: { ...cand, size, mtimeMs }, held: before })
+
+ return
+ }
+
+ // A file that fits no more of this pass keeps its earlier summary (or none) until the next pass.
+ const cost = Math.min(size, 300_000)
+
+ if (budget - cost < 0 && before !== undefined) {
+ const held = { ...before, stale: before.stale ?? 'newer than the last read' }
+
+ memory.set(cand.path, held)
+ out.push({ cand: { ...cand, size, mtimeMs }, held })
+
+ return
+ }
+
+ budget -= cost
+
+ const window = await readWindow(fs, cand.path, size)
+ let held: Held<S>
+
+ if (window.text !== null) held = { mtimeMs, size, value: summarize(window.text, window.whole, { ...cand, size, mtimeMs }), noPreview: null, stale: null, whole: window.whole }
+ else if (before?.value !== undefined && before.value !== null) held = { ...before, mtimeMs, size, stale: `read failed: ${WHY[window.reason] ?? window.reason}` }
+ else held = { mtimeMs, size, value: null, noPreview: WHY[window.reason] ?? window.reason, stale: null, whole: false }
+
+ memory.set(cand.path, held)
+ out.push({ cand: { ...cand, size, mtimeMs }, held })
+ }
+
+ for (let i = 0; i < cands.length; i += CONCURRENCY) await Promise.all(cands.slice(i, i + CONCURRENCY).map(cand => one(cand).catch(() => undefined)))
+
+ return out
+}
diff --git a/plugins/ruflo-console/hooks/data/harness.ts b/plugins/ruflo-console/hooks/data/harness.ts
new file mode 100644
index 0000000000..13d35b6a95
--- /dev/null
+++ b/plugins/ruflo-console/hooks/data/harness.ts
@@ -0,0 +1,109 @@
+/**
+ * The session workspace's adapter contract (ADR-486). A harness adapter finds the sessions one agent harness keeps on this machine and
+ * says, per capability, whether it can do that and why not. An action a harness has not declared stays unavailable; nothing is inferred.
+ * Discovery is local and read-only: it makes no model call, spawns no process and wakes no agent.
+ */
+import type { ReaderFs } from './files'
+
+export const HARNESS_IDS = ['claude', 'codex', 'ruflo'] as const
+export type HarnessId = (typeof HARNESS_IDS)[number]
+
+/** What an adapter may declare. `approvals`: it can tell that a session is waiting for a yes. */
+export const CAPABILITIES = ['discovery', 'preview', 'approvals', 'resume', 'fork', 'messaging', 'stop'] as const
+export type Capability = (typeof CAPABILITIES)[number]
+export type CapabilityState = { supported: boolean; why: string }
+export type Capabilities = Record<Capability, CapabilityState>
+
+export const yes = (why = 'verified against the on-disk format'): CapabilityState => ({ supported: true, why })
+export const no = (why: string): CapabilityState => ({ supported: false, why })
+
+/** The four kinds the attention queue shows. */
+export const ATTENTION_KINDS = ['needs-approval', 'question', 'failed', 'completed-unread'] as const
+export type AttentionKind = (typeof ATTENTION_KINDS)[number]
+
+/** Cost is never guessed: `reported` came from the harness, `estimated` from a stated rule, `unavailable` is shown as such. */
+export type Cost = { label: 'reported' | 'estimated' | 'unavailable'; usd?: number; note?: string }
+
+export type Preview = {
+ /** The latest response, sanitised and cut. Never model-facing, never persisted, never exported. */
+ latest: string
+ tool: string | null
+ files: string[]
+ test: string | null
+}
+
+export type Signals = {
+ /** A question put to the person is open (the harness asked, nothing has answered). */
+ question: boolean
+ /** An approval is open (only an adapter that declares `approvals` sets it). */
+ approval: boolean
+ /** The last tool failed and nothing followed it. */
+ failed: boolean
+ /** The last turn finished at this time. */
+ turnEndedAtMs: number | null
+}
+
+export type SessionStatus = 'working' | 'idle' | 'done' | 'failed' | 'unknown'
+
+export type SessionRow = {
+ /** Identity: harness + canonical home + native id. Two rows never share one. */
+ key: string
+ harness: HarnessId
+ home: string
+ nativeId: string
+ title: string
+ status: SessionStatus
+ /** The working directory the harness recorded, or null when it could not be read (never guessed from the folder name). */
+ cwd: string | null
+ /** The project folder name the harness keeps this session in; the group label when no cwd is known. */
+ folder: string
+ repo: string
+ worktree: string | null
+ branch: string | null
+ /** The mission this session is known to belong to, by an exact id the harness recorded; null otherwise. */
+ mission: string | null
+ updatedMs: number
+ size: number
+ /** Why this row could not be tied to one session (ambiguous id, id mismatch); it then sits in the unassigned bucket. */
+ unassigned: string | null
+ /** The last read failed or the window was incomplete: what is shown is from an earlier read or from the tail only. */
+ stale: string | null
+ /** Started outside Ruflo: nothing in Ruflo launched it. */
+ external: boolean
+ cost: Cost
+ signals: Signals
+ preview: Preview | null
+ /** Mission context lines (assigned task, dependencies, claims, ADRs, verification): only what the console's own records hold. */
+ context: string[]
+ /** Why there is no preview (too large for this host, unreadable). */
+ noPreview: string | null
+}
+
+export type ScanResult = { state: 'ok' | 'not-detected' | 'failed'; rows: SessionRow[]; note: string }
+
+/** What a host can do for a read: `readTail` exists only where the host offers it (ADR-473). */
+export type SessionFs = ReaderFs & { readTail?: (path: string, bytes: number) => Promise<string> }
+
+export type ScanEnv = {
+ fs: SessionFs
+ /** Claude Code's config directory and Codex's home, or null when unknown. */
+ claudeDir: string | null
+ codexDir: string | null
+ nowMs: number
+ /** Relist everything (slow pass); otherwise only what changed and the recently active files. */
+ full: boolean
+}
+
+export interface HarnessAdapter {
+ readonly id: HarnessId
+ readonly label: string
+ readonly capabilities: Capabilities
+ scan(env: ScanEnv): Promise<ScanResult>
+}
+
+/** Splits a recorded cwd into its repository and worktree by path alone (no git, no disk): `<repo>/.claude/worktrees/<name>` and its kin. */
+export function repoOf(cwd: string): { repo: string; worktree: string | null } {
+ const marker = /^(.*?)\/(?:\.claude\/worktrees|\.git-worktrees|\.worktrees)\/([^/]+)/.exec(cwd)
+
+ return marker !== null && marker[1] !== undefined && marker[2] !== undefined ? { repo: marker[1] === '' ? '/' : marker[1], worktree: marker[2] } : { repo: cwd, worktree: null }
+}
diff --git a/plugins/ruflo-console/hooks/data/sessions-attention.ts b/plugins/ruflo-console/hooks/data/sessions-attention.ts
new file mode 100644
index 0000000000..4560cb512d
--- /dev/null
+++ b/plugins/ruflo-console/hooks/data/sessions-attention.ts
@@ -0,0 +1,83 @@
+/**
+ * The attention queue (ADR-486): what needs the person, across every harness. Four kinds, in this order: needs-approval, question, failed,
+ * completed-unread. An approval or a question stays until the harness stops reporting it (viewing never clears one). A failure or a completion
+ * clears once its content was actually displayed (`markViewed`, committed by the page after the frame that drew the preview), and comes back
+ * only if the session moves on to something newer. Completions older than the baseline (when this queue first ran) are history, not unread.
+ * An unassigned row raises nothing: its identity is in doubt.
+ */
+import { ATTENTION_KINDS, type AttentionKind, type SessionRow } from './harness'
+
+export type Viewed = { baselineMs: number; seen: Record<string, number> }
+export const SEEN_MAX = 500
+
+export type AttentionItem = { id: string; kind: AttentionKind; rowKey: string | null; title: string; harness: string; atMs: number; detail: string; stale: boolean }
+export type PendingAsk = { label: string; askedAtMs: number } | null
+
+const DETAIL: Record<AttentionKind, string> = { 'needs-approval': 'waiting for your yes', question: 'asked you a question', failed: 'the last tool failed', 'completed-unread': 'finished since you looked' }
+
+export const newViewed = (nowMs: number): Viewed => ({ baselineMs: nowMs, seen: {} })
+
+/** A stored value read back: anything not shaped like a Viewed is a fresh one, never trusted. */
+export function viewedOf(raw: unknown, nowMs: number): Viewed {
+ if (typeof raw !== 'object' || raw === null) return newViewed(nowMs)
+
+ const value = raw as { baselineMs?: unknown; seen?: unknown }
+ const seen: Record<string, number> = {}
+
+ if (typeof value.seen === 'object' && value.seen !== null) {
+ for (const [key, stamp] of Object.entries(value.seen).slice(0, SEEN_MAX)) if (typeof stamp === 'number' && Number.isFinite(stamp)) seen[key.slice(0, 300)] = stamp
+ }
+
+ return { baselineMs: typeof value.baselineMs === 'number' && Number.isFinite(value.baselineMs) ? value.baselineMs : nowMs, seen }
+}
+
+const seenKey = (rowKey: string, kind: AttentionKind) => `${rowKey}|${kind}`
+
+export function attentionOf(rows: readonly SessionRow[], viewed: Viewed, pending: PendingAsk): AttentionItem[] {
+ const items: AttentionItem[] = []
+
+ if (pending !== null) items.push({ id: 'console:pending', kind: 'needs-approval', rowKey: null, title: pending.label, harness: 'console', atMs: pending.askedAtMs, detail: 'a confirm is waiting for your yes', stale: false })
+
+ for (const row of rows) {
+ if (row.unassigned !== null) continue
+
+ const add = (kind: AttentionKind, atMs: number) => items.push({ id: seenKey(row.key, kind), kind, rowKey: row.key, title: row.title, harness: row.harness, atMs, detail: DETAIL[kind], stale: row.stale !== null })
+
+ if (row.signals.approval) add('needs-approval', row.updatedMs)
+ if (row.signals.question) add('question', row.updatedMs)
+ if (row.signals.failed && Math.max(1, row.updatedMs) > (viewed.seen[seenKey(row.key, 'failed')] ?? 0)) add('failed', Math.max(1, row.updatedMs))
+
+ const ended = row.signals.turnEndedAtMs
+
+ if (ended !== null && ended >= viewed.baselineMs && ended > (viewed.seen[seenKey(row.key, 'completed-unread')] ?? 0) && !row.signals.question) add('completed-unread', ended)
+ }
+
+ return items.sort((a, b) => ATTENTION_KINDS.indexOf(a.kind) - ATTENTION_KINDS.indexOf(b.kind) || b.atMs - a.atMs)
+}
+
+/** Records that the content of these items was displayed. Approvals and questions are not recorded: only the harness resolves them. */
+export function markViewed(viewed: Viewed, items: readonly AttentionItem[]): Viewed {
+ const seen = { ...viewed.seen }
+ let changed = false
+
+ for (const item of items) {
+ if (item.rowKey === null || (item.kind !== 'failed' && item.kind !== 'completed-unread')) continue
+ if ((seen[item.id] ?? 0) >= item.atMs) continue
+
+ seen[item.id] = item.atMs
+ changed = true
+ }
+
+ if (!changed) return viewed
+
+ const kept = Object.entries(seen).sort((a, b) => b[1] - a[1]).slice(0, SEEN_MAX)
+
+ return { baselineMs: viewed.baselineMs, seen: Object.fromEntries(kept) }
+}
+
+export const countsOf = (items: readonly AttentionItem[]): Record<AttentionKind, number> => ({
+ 'needs-approval': items.filter(item => item.kind === 'needs-approval').length,
+ question: items.filter(item => item.kind === 'question').length,
+ failed: items.filter(item => item.kind === 'failed').length,
+ 'completed-unread': items.filter(item => item.kind === 'completed-unread').length,
+})
diff --git a/plugins/ruflo-console/hooks/data/sessions-index.ts b/plugins/ruflo-console/hooks/data/sessions-index.ts
new file mode 100644
index 0000000000..a661ceb16a
--- /dev/null
+++ b/plugins/ruflo-console/hooks/data/sessions-index.ts
@@ -0,0 +1,63 @@
+/**
+ * The session workspace's index (ADR-486): the adapters' rows merged into one list, each with an identity that cannot be mistaken for
+ * another's. Identity is harness + canonical home + native id. A row whose id is claimed by more than one file, or whose entries name another
+ * id, is UNASSIGNED: it is listed in its own bucket, shows no preview, and never raises an attention item, because the one thing this page must
+ * not do is show one session's output under another's name. Grouping is by repository, then worktree, from the recorded cwd's path alone.
+ */
+import { HARNESS_IDS, type Capabilities, type HarnessId, type ScanResult, type SessionRow } from './harness'
+
+export type HarnessReport = { id: HarnessId; label: string; state: ScanResult['state']; note: string; count: number; capabilities: Capabilities }
+export type Group = { label: string; repo: string; unassigned: boolean; rows: SessionRow[] }
+export type Index = { rows: SessionRow[]; groups: Group[]; reports: HarnessReport[]; unassigned: number; builtAtMs: number }
+export type Scanned = { id: HarnessId; label: string; capabilities: Capabilities; result: ScanResult }
+
+const SEVERITY: Record<SessionRow['status'], number> = { failed: 0, working: 1, idle: 2, done: 3, unknown: 4 }
+
+/** The last two path segments, so a long path stays recognisable in a group heading. */
+export const shortRepo = (repo: string): string => {
+ const parts = repo.split('/').filter(part => part !== '')
+
+ return parts.length <= 2 ? repo : `…/${parts.slice(-2).join('/')}`
+}
+
+export function buildIndex(scans: readonly Scanned[], own: ReadonlySet<string>, nowMs: number): Index {
+ const all = scans.flatMap(scan => scan.result.rows)
+ const seen = new Map<string, number>()
+
+ for (const row of all) seen.set(row.key, (seen.get(row.key) ?? 0) + 1)
+
+ const rows: SessionRow[] = all.map((row, i) => {
+ const copies = seen.get(row.key) ?? 1
+ // A duplicated id gets a key of its own, so selecting one copy can never select (or show) the other.
+ const key = copies > 1 ? `${row.key}~${row.folder}~${i}` : row.key
+ const unassigned = copies > 1 ? `the id is claimed by ${copies} files` : row.unassigned
+
+ return { ...row, key, unassigned, external: row.harness === 'ruflo' ? false : !own.has(row.nativeId), ...(unassigned !== null && { preview: null, noPreview: 'unassigned: not shown', title: `${row.harness} file ${row.nativeId.slice(0, 8)} in ${row.folder}`, cwd: null, branch: null, context: [] }) }
+ })
+
+ const groups = new Map<string, Group>()
+
+ for (const row of rows) {
+ const bucket = row.unassigned !== null
+ const id = bucket ? '\u0000unassigned' : `${row.repo}\u0000${row.worktree ?? ''}`
+ const held = groups.get(id) ?? { label: bucket ? 'unassigned' : `${shortRepo(row.repo)}${row.worktree === null ? '' : ` › ${row.worktree}`}`, repo: row.repo, unassigned: bucket, rows: [] }
+
+ held.rows.push(row)
+ groups.set(id, held)
+ }
+
+ const ordered = [...groups.values()].map(group => ({ ...group, rows: group.rows.sort((a, b) => SEVERITY[a.status] - SEVERITY[b.status] || b.updatedMs - a.updatedMs) }))
+
+ ordered.sort((a, b) => Number(a.unassigned) - Number(b.unassigned) || Math.max(...b.rows.map(r => r.updatedMs)) - Math.max(...a.rows.map(r => r.updatedMs)))
+
+ return {
+ rows,
+ groups: ordered,
+ unassigned: rows.filter(row => row.unassigned !== null).length,
+ builtAtMs: nowMs,
+ reports: HARNESS_IDS.map(id => scans.find(scan => scan.id === id)).flatMap(scan => (scan === undefined ? [] : [{ id: scan.id, label: scan.label, state: scan.result.state, note: scan.result.note, count: scan.result.rows.length, capabilities: scan.capabilities }])),
+ }
+}
+
+/** The row with this key, or undefined: the only lookup the preview uses, so a selection can only ever resolve to the row it names. */
+export const rowOf = (index: Index | null, key: string | null): SessionRow | undefined => (index === null || key === null ? undefined : index.rows.find(row => row.key === key))
diff --git a/plugins/ruflo-console/hooks/data/sessions-options.ts b/plugins/ruflo-console/hooks/data/sessions-options.ts
new file mode 100644
index 0000000000..0eada1ad08
--- /dev/null
+++ b/plugins/ruflo-console/hooks/data/sessions-options.ts
@@ -0,0 +1,14 @@
+/** The session workspace's two options (ADR-486), read the way every other option family is: a value the plugin does not know is its default. */
+export type SessionOptions = {
+ /** The attention queue and session browser on the Room. Read-only discovery; on by default. */
+ sessionWorkspace: boolean
+ /** The preview beside the list. Off draws no transcript text at all. */
+ sessionPreview: boolean
+}
+
+export const sessionOptionsOf = (raw: unknown): SessionOptions => {
+ const value = (typeof raw === 'object' && raw !== null ? raw : {}) as Record<string, unknown>
+ const on = (v: unknown): boolean => v !== false && v !== 'false'
+
+ return { sessionWorkspace: on(value.sessionWorkspace), sessionPreview: on(value.sessionPreview) }
+}
diff --git a/plugins/ruflo-console/hooks/register.ts b/plugins/ruflo-console/hooks/register.ts
index 2cb4ca4311..446324e59a 100644
--- a/plugins/ruflo-console/hooks/register.ts
+++ b/plugins/ruflo-console/hooks/register.ts
@@ -3,6 +3,7 @@ import { tolerantPress } from './press-guard'
import { ANSWER_KEYS } from './views/attention'
import { createController, type Controller } from './controller'
+import { startSessions } from './sessions'
import { record } from './data/events'
import { plain } from './data/parse'
import { dispatch } from './dispatch'
@@ -249,6 +250,7 @@ export const register: Register = (on, raw: PluginOptions) => {
bound.rufloTools().then(counted => void (state.rufloTools = counted), () => undefined),
])
control.start()
+ startSessions(state, bound)
await control.refresh()
control.autoOpen()
diff --git a/plugins/ruflo-console/hooks/sessions.ts b/plugins/ruflo-console/hooks/sessions.ts
new file mode 100644
index 0000000000..4d65ae124e
--- /dev/null
+++ b/plugins/ruflo-console/hooks/sessions.ts
@@ -0,0 +1,252 @@
+/**
+ * The session workspace's runtime (ADR-486): one Workspace per console state (a side table, so nothing a transcript said can reach the state
+ * that is snapshotted, exported or shown to a model), the scan that fills it, the selection, and the "read means viewed" commit.
+ *
+ * Scans are stat-first and incremental (data/harness-track.ts): a fast pass once a second while the pane is shown, a full relist every 15 s,
+ * and almost nothing while it is closed. Nothing here starts a process, makes a model call, or touches a session it lists.
+ */
+import { buildIndex, type Index, type Scanned } from './data/sessions-index'
+import { attentionOf, countsOf, markViewed, viewedOf, type AttentionItem, type Viewed } from './data/sessions-attention'
+import { claudeAdapter } from './data/harness-claude'
+import { codexAdapter } from './data/harness-codex'
+import { rufloAdapter, type LedgerFacts, type RufloInput } from './data/harness-ruflo'
+import type { HarnessAdapter, SessionFs } from './data/harness'
+import { mcOf } from './mission-control'
+import { replaceFile } from './activity-io'
+import type { Host } from './host'
+import type { State } from './state'
+
+export const VIEWED_KEY = 'ruflo-console/sessions-viewed'
+const FAST_MS = 1000
+const FULL_MS = 15_000
+const CLOSED_MS = 30_000
+const SHOWN_TTL_MS = 10_000
+
+export type Workspace = {
+ adapters: HarnessAdapter[]
+ index: Index | null
+ selected: string | null
+ /** Which attention row the cursor is on (an index into the queue). */
+ cursor: number
+ viewed: Viewed | null
+ scanning: boolean
+ lastScanMs: number
+ lastFullMs: number
+ scanTimes: number[]
+ /** Rows whose preview text a frame actually drew, with when: the page's evidence that content was displayed (data/sessions-attention.ts). */
+ shown: Map<string, number>
+ /** A line about the last action that could not run, with its reason. */
+ note: string
+ signature: string
+ /** The counts last written to the summary file, so it is rewritten only when one changes. */
+ summary: string
+ timer: { cancel: () => void } | null
+}
+
+const spaces = new WeakMap<State, Workspace>()
+
+export function rufloInputOf(state: State, nowMs: number): RufloInput {
+ const ledger = new Map<string, LedgerFacts>()
+
+ for (const mission of mcOf(state).missions.values()) ledger.set(mission.id, { ...(mission.adrs !== undefined && { adrs: mission.adrs }), tasks: mission.tasks.map(task => ({ id: task.id, dependsOn: task.dependsOn, ...(task.rufloTaskId !== undefined && { rufloTaskId: task.rufloTaskId }) })) })
+
+ return { cwd: state.cwd, missions: state.snapshot?.missions ?? null, agents: state.snapshot?.agents ?? [], nowMs, ledger, claimedIssues: new Set((state.snapshot?.claims ?? []).filter(claim => claim.status !== 'released').map(claim => claim.issueId)) }
+}
+
+export function workspaceOf(state: State): Workspace {
+ let found = spaces.get(state)
+
+ if (found === undefined) {
+ found = { adapters: [claudeAdapter(), codexAdapter(), rufloAdapter(() => rufloInputOf(state, Date.now()))], index: null, selected: null, cursor: 0, viewed: null, scanning: false, lastScanMs: 0, lastFullMs: 0, scanTimes: [], shown: new Map(), note: '', signature: '', summary: '', timer: null }
+ spaces.set(state, found)
+ }
+
+ return found
+}
+
+/** The native ids of the sessions the console itself started (the terminal's saved conversations): everything else is outside Ruflo. */
+export const ownIds = (state: State): ReadonlySet<string> => new Set(Object.values(state.terminal.sessions).filter((id): id is string => typeof id === 'string'))
+
+const codexDirOf = (state: State): string | null => (state.home === null ? null : `${state.home.replace(/\/+$/, '')}/.codex`)
+
+/** One pass over every adapter. Never rejects; a failing adapter leaves its report saying so and keeps its earlier rows. */
+export async function scanSessions(state: State, host: Pick<Host, 'fs' | 'invalidate'>, full: boolean, nowMs: number = Date.now()): Promise<void> {
+ const ws = workspaceOf(state)
+
+ if (ws.scanning) return
+
+ ws.scanning = true
+
+ const started = performance.now()
+
+ try {
+ const env = { fs: host.fs as SessionFs, claudeDir: state.configDir, codexDir: codexDirOf(state), nowMs, full }
+ const scans: Scanned[] = await Promise.all(
+ ws.adapters.map(async adapter => ({
+ id: adapter.id,
+ label: adapter.label,
+ capabilities: adapter.capabilities,
+ result: await adapter.scan(env).catch(() => ({ state: 'failed' as const, rows: [], note: 'the scan threw; nothing was read' })),
+ })),
+ )
+
+ ws.index = buildIndex(scans, ownIds(state), nowMs)
+ ws.lastScanMs = nowMs
+ if (full) ws.lastFullMs = nowMs
+ if (ws.selected !== null && !ws.index.rows.some(row => row.key === ws.selected)) ws.selected = null
+ ws.scanTimes.push(performance.now() - started)
+ if (ws.scanTimes.length > 50) ws.scanTimes.shift()
+
+ const signature = `${ws.index.rows.map(row => `${row.key}:${row.updatedMs}:${row.status}:${row.stale ?? ''}`).join(',')}|${state.pending?.label ?? ''}`
+
+ if (signature !== ws.signature) {
+ ws.signature = signature
+ if (state.view === 'room' || state.view === 'overview') host.invalidate()
+ }
+ } finally {
+ ws.scanning = false
+ }
+}
+
+/** The queue as the page draws it (the console's own pending confirm included). Empty until the viewed state has loaded. */
+export function queueOf(state: State): AttentionItem[] {
+ const ws = workspaceOf(state)
+
+ if (ws.index === null || ws.viewed === null) return state.pending === null ? [] : attentionOf([], { baselineMs: Date.now(), seen: {} }, { label: state.pending.label, askedAtMs: state.pending.askedAtMs })
+
+ return attentionOf(ws.index.rows, ws.viewed, state.pending === null ? null : { label: state.pending.label, askedAtMs: state.pending.askedAtMs })
+}
+
+export const attentionCounts = (state: State) => countsOf(queueOf(state))
+
+/** Selecting a row changes only which row is looked at: no read, no process, no wake. */
+export function selectRow(state: State, key: string | null): void {
+ const ws = workspaceOf(state)
+
+ ws.selected = key !== null && ws.index?.rows.some(row => row.key === key) === true ? key : null
+ ws.note = ''
+}
+
+/** The view calls this when it drew a row's preview text. It only notes the fact; `commitViewed` acts on it. */
+export function noteShown(state: State, key: string, atMs: number = Date.now()): void {
+ workspaceOf(state).shown.set(key, atMs)
+}
+
+/**
+ * Read means viewed: an unread completion or a failure clears only for a row whose preview text a frame drew in the last few seconds while
+ * the Room was the page in front. A placeholder, an error line, a hidden pane or another page clears nothing. Returns whether anything cleared.
+ */
+export function commitViewed(state: State, host: Pick<Host, 'storeSet' | 'invalidate'>, nowMs: number = Date.now()): boolean {
+ const ws = workspaceOf(state)
+
+ for (const [key, at] of ws.shown) if (nowMs - at > SHOWN_TTL_MS) ws.shown.delete(key)
+
+ if (ws.viewed === null || state.view !== 'room' || !state.pane.isShown || ws.shown.size === 0) return false
+
+ const items = queueOf(state).filter(item => item.rowKey !== null && ws.shown.has(item.rowKey))
+ const next = markViewed(ws.viewed, items)
+
+ ws.shown.clear()
+
+ if (next === ws.viewed) return false
+
+ ws.viewed = next
+ void host.storeSet(VIEWED_KEY, next).catch(() => undefined)
+ host.invalidate()
+
+ return true
+}
+
+/** Where the counts-only summary ruflo-mods can show lives: the console's own state folder, in a ruflo project, rewritten only when a count changes. */
+export const ATTENTION_FILE = '.claude-flow/console/attention.json'
+
+export async function mirrorAttention(state: State, host: Pick<Host, 'fs' | 'run'>, nowMs: number = Date.now()): Promise<void> {
+ const ws = workspaceOf(state)
+
+ if (ws.viewed === null || ws.index === null || state.snapshot?.isRufloProject !== true) return
+
+ const counts = attentionCounts(state)
+ const key = `${counts['needs-approval']}/${counts.question}/${counts.failed}/${counts['completed-unread']}`
+
+ if (key === ws.summary) return
+
+ ws.summary = key
+ // Counts only: no title, path or transcript text is in this file.
+ const text = `${JSON.stringify({ schema: 'ruflo-console.attention/1', approve: counts['needs-approval'], question: counts.question, failed: counts.failed, unread: counts['completed-unread'], atMs: nowMs })}\n`
+
+ if ((await replaceFile(host, state.cwd, `${state.cwd.replace(/\/+$/, '')}/${ATTENTION_FILE}`, text)) !== null) ws.summary = ''
+}
+
+export type SessionActions = {
+ select: (key: string) => void
+ /** Moves the selection through the rows in the order the page lists them. */
+ move: (by: number) => void
+ /** Selects the session an attention item is about (the console's own confirm has none). */
+ jump: (itemId: string) => void
+ refresh: () => void
+ /** Enter on a row: opens it natively only where the harness declared it can; otherwise says why not. */
+ open: (key: string) => void
+}
+
+export function sessionActions(state: State, host: Pick<Host, 'fs' | 'invalidate'>): SessionActions {
+ const ws = workspaceOf(state)
+ const order = () => ws.index?.groups.flatMap(group => group.rows) ?? []
+
+ return {
+ select: key => {
+ selectRow(state, key)
+ host.invalidate()
+ },
+ move: by => {
+ const rows = order()
+ const at = rows.findIndex(row => row.key === ws.selected)
+
+ if (rows.length > 0) selectRow(state, rows[Math.max(0, Math.min(rows.length - 1, (at < 0 ? (by > 0 ? -1 : rows.length) : at) + by))]?.key ?? null)
+ host.invalidate()
+ },
+ jump: id => {
+ const item = queueOf(state).find(candidate => candidate.id === id)
+
+ if (item?.rowKey != null) selectRow(state, item.rowKey)
+ host.invalidate()
+ },
+ refresh: () => void scanSessions(state, host, true),
+ open: key => {
+ const row = ws.index?.rows.find(candidate => candidate.key === key)
+ const caps = ws.index?.reports.find(report => report.id === row?.harness)?.capabilities
+
+ ws.note = row === undefined ? 'that session is gone' : caps?.resume.supported === true ? 'this harness can open sessions, but phase 1 wires no opener' : `open is unavailable for ${row.harness}: ${caps?.resume.why ?? 'not declared'}`
+ host.invalidate()
+ },
+ }
+}
+
+/** Starts the watcher once. A closed pane scans rarely; a shown one every second (stat-only unless something changed). */
+export function startSessions(state: State, host: Host): void {
+ const ws = workspaceOf(state)
+
+ if (ws.timer !== null) return
+
+ // The baseline is the first time this queue ever ran: older completions are history, not unread. It is stored so a restart keeps it.
+ void host.storeGet(VIEWED_KEY).then(
+ raw => {
+ ws.viewed = viewedOf(raw, Date.now())
+ if (typeof raw !== 'object' || raw === null) void host.storeSet(VIEWED_KEY, ws.viewed).catch(() => undefined)
+ },
+ () => (ws.viewed = viewedOf(null, Date.now())),
+ )
+
+ ws.timer = host.every(FAST_MS, () => {
+ if (!state.options.sessionWorkspace) return
+
+ const now = Date.now()
+ const isSeen = state.pane.isOpen && state.pane.isShown
+
+ if (!isSeen && now - ws.lastScanMs < CLOSED_MS) return
+
+ void scanSessions(state, host, now - ws.lastFullMs >= FULL_MS, now).then(() => {
+ commitViewed(state, host)
+ void mirrorAttention(state, host, now)
+ })
+ })
+}
diff --git a/plugins/ruflo-console/hooks/state.ts b/plugins/ruflo-console/hooks/state.ts
index dd470a8c5a..fe2568f8fb 100644
--- a/plugins/ruflo-console/hooks/state.ts
+++ b/plugins/ruflo-console/hooks/state.ts
@@ -1,5 +1,6 @@
import type { PluginOptions, Timer } from 'claude-code'
import { guardOptionsOf, type GuardOptions } from './data/wf-alerts'
+import { sessionOptionsOf, type SessionOptions } from './data/sessions-options'
import { convoOptionsOf, type ConvoOptions } from './data/wf-targets'
import { emptyAuto, type AutoState } from './data/automate'
@@ -102,7 +103,7 @@ export const CLI_PREFIXES = {
export type CliChoice = keyof typeof CLI_PREFIXES
-export type Options = GuardOptions & ConvoOptions & {
+export type Options = GuardOptions & ConvoOptions & SessionOptions & {
cli: CliChoice
/** How often the disk is re-read while the pane or band shows (seconds, 2-60). */
refreshSeconds: number
@@ -144,6 +145,7 @@ export function optionsOf(raw: PluginOptions | undefined): Options {
eventsPersist: value.eventsPersist !== false && value.eventsPersist !== 'false',
...guardOptionsOf(raw),
...convoOptionsOf(raw),
+ ...sessionOptionsOf(raw),
}
}
diff --git a/plugins/ruflo-console/hooks/version.ts b/plugins/ruflo-console/hooks/version.ts
index 277dd4ea05..fadeb1a5a5 100644
--- a/plugins/ruflo-console/hooks/version.ts
+++ b/plugins/ruflo-console/hooks/version.ts
@@ -2,4 +2,4 @@
* The console's version, shown on the header so a person can tell which build is running. Kept equal to the plugin's manifest
* (`.claude-plugin/plugin.json`); tests/version.spec.ts fails if the two drift.
*/
-export const CONSOLE_VERSION = '0.40.8'
+export const CONSOLE_VERSION = '0.41.0'
diff --git a/plugins/ruflo-console/hooks/views/common.ts b/plugins/ruflo-console/hooks/views/common.ts
index 1367feb9a2..67fe17a939 100644
--- a/plugins/ruflo-console/hooks/views/common.ts
+++ b/plugins/ruflo-console/hooks/views/common.ts
@@ -7,6 +7,7 @@ import type { AskActions } from '../ask-claude'
import type { OptimizerActions } from '../optimizer'
import { askedBy } from '../data/room'
import type { RoomActions } from '../room'
+import type { SessionActions } from '../sessions'
import type { WatchActions } from '../watch'
import type { WhatsNewActions } from '../whatsnew'
import type { AdrActions } from '../adr-actions'
@@ -103,6 +104,8 @@ export type Actions = {
timeline: TimelineActions
/** The Room (ADR-448): the draft, what to send through, the feed's source filter, search, pause and paging. */
room: RoomActions
+ /** The session workspace (ADR-486): select, move, jump from the attention queue, rescan, and the (unavailable) native open. */
+ sessions: SessionActions
/** Ask Claude about this section (a visible prompt or a /btw aside) or run the plugin command that fits it: each asks first. */
ask: AskActions
/** ruHelp, the built-in help: a question, a guide, a step's button, and asking Claude with the docs. */
@@ -155,6 +158,8 @@ export type Ctx = {
cards?: boolean
/** The page's attention panel (views/attention.ts): lab views hand their result rows to it with `slot`. */
attention?: Attention
+ /** True while the page is drawn as a text answer a model may read (viewText): a transcript is never drawn then (ADR-486). */
+ text?: boolean
}
export type Look = 'bbs' | 'plain'
diff --git a/plugins/ruflo-console/hooks/views/overview.ts b/plugins/ruflo-console/hooks/views/overview.ts
index f5811dfd8f..1b73f082a9 100644
--- a/plugins/ruflo-console/hooks/views/overview.ts
+++ b/plugins/ruflo-console/hooks/views/overview.ts
@@ -6,6 +6,7 @@ import type { StartId } from '../starts'
import { controlRows, isControlActive } from './control'
import { optimizerRows } from './optimizer'
import { uniqueAgents } from '../data/swarm-status'
+import { attentionOverviewRows } from './sessions'
import { onDisk, swarmFacts } from './swarm'
import { ago, button, col, count, kv, live, row, picture, rule, sourceLine, starts, text, THEME, type Ctx } from './common'
@@ -76,6 +77,7 @@ export function overviewView(ctx: Ctx): RenderElement {
const modsBlocked = modsSeen.filter(mod => mod.blocked > 0).length
rows.push(kv(ctx, 'mods reporting', modsSeen.length === 0 ? 'none yet' : `${modsSeen.length}${modsBlocked > 0 ? ` · ${modsBlocked} blocked something` : ''}`, modsBlocked > 0 ? THEME.warn : undefined))
+ rows.push(...attentionOverviewRows(ctx))
rows.push(row(ctx, [button(ctx, 'overview-mods', 'The Room: Mods', () => ctx.act.view('room'))], 'overview-mods-row'))
// The swarm's own count, never the agent store's: the store holds every agent ever spawned, so a 0-agent swarm once read "259 agents".
const facts = swarm === null ? null : swarmFacts(swarm, nowMs, snap?.agents ?? [])
diff --git a/plugins/ruflo-console/hooks/views/pane.ts b/plugins/ruflo-console/hooks/views/pane.ts
index 30e67444d2..e22a156eaa 100644
--- a/plugins/ruflo-console/hooks/views/pane.ts
+++ b/plugins/ruflo-console/hooks/views/pane.ts
@@ -449,13 +449,13 @@ export function paneView(base: Ctx): RenderElement {
type Plain = { type: string; props: { children?: unknown; label?: string } }
-const plainKit = (): Ctx['kit'] => {
+export const plainKit = (): Ctx['kit'] => {
const element = (type: string) => (props: Record<string, unknown>) => ({ type, props }) as never
return { Box: element('Box'), Text: element('Text'), Button: element('Button') }
}
-function linesOf(node: unknown, out: string[]): void {
+export function linesOf(node: unknown, out: string[]): void {
if (node === null || node === undefined || typeof node === 'boolean') return
if (typeof node === 'string' || typeof node === 'number') {
out.push(String(node))
@@ -491,7 +491,7 @@ function linesOf(node: unknown, out: string[]): void {
* a surface without the pane, or a script that wants to read what the console sees.
*/
export function viewText(ctx: Omit<Ctx, 'kit' | 'pictures'>, view: ViewId): string {
- const body = BODIES[view]({ ...ctx, kit: plainKit(), pictures: new Map() })
+ const body = BODIES[view]({ ...ctx, kit: plainKit(), pictures: new Map(), text: true })
const out: string[] = []
linesOf(body, out)
diff --git a/plugins/ruflo-console/hooks/views/room.ts b/plugins/ruflo-console/hooks/views/room.ts
index f493dcc7b6..27896d5f3c 100644
--- a/plugins/ruflo-console/hooks/views/room.ts
+++ b/plugins/ruflo-console/hooks/views/room.ts
@@ -10,6 +10,7 @@ import { lanesOf } from './frames'
import { VIEWS, type ViewId } from '../state'
import { statsOf } from './manage'
import { modsRows } from './mods'
+import { sessionRows } from './sessions'
const TONE_COLOR = { ok: THEME.ok, warn: THEME.warn, bad: THEME.bad, info: THEME.info } as const
const SOURCES: readonly { id: 'all' | RoomSource; label: string }[] = [
@@ -61,6 +62,7 @@ export function roomView(ctx: Ctx): RenderElement {
rows.push(text(ctx, ` expects: ${banner.expect}${banner.view === null ? '' : ` · raised on ${banner.view}`} · ${banner.leftS}s left to answer${banner.leftS === 0 ? ' (too late: it will not run, ask again)' : ''}`, { color: TONE_COLOR[banner.tone] }))
}
+ rows.push(...sessionRows(ctx))
rows.push(rule(ctx, 'Say something', 'each asks first, as anywhere else'))
const Input = ctx.kit.Input
diff --git a/plugins/ruflo-console/hooks/views/sessions.ts b/plugins/ruflo-console/hooks/views/sessions.ts
new file mode 100644
index 0000000000..c0b42059b6
--- /dev/null
+++ b/plugins/ruflo-console/hooks/views/sessions.ts
@@ -0,0 +1,160 @@
+/**
+ * The session workspace on the Room and a line on the Overview (ADR-486): the attention queue ("Needs you"), the session browser grouped by
+ * repository and worktree, and the preview of the selected session. Every string drawn from a transcript went through the one sanitiser
+ * (data/harness-text.ts `shown`) when it was read. The preview is drawn only when the page is drawn for a person: `ctx.text` (a text answer
+ * a model may read) gets the structure and never a line of a transcript. A frame that drew a preview says so (`noteShown`), and that is the
+ * only thing that ever clears an unread completion.
+ */
+import type { RenderElement } from 'claude-code'
+
+import type { AttentionKind, SessionRow } from '../data/harness'
+import { CAPABILITIES } from '../data/harness'
+import { rowOf } from '../data/sessions-index'
+import { attentionCounts, noteShown, queueOf, workspaceOf } from '../sessions'
+import { ago, button, clip, row, rule, text, THEME, type Ctx } from './common'
+import { fullRows } from './full-rows'
+
+const KIND_LABEL: Record<AttentionKind, string> = { 'needs-approval': 'needs your yes', question: 'asked a question', failed: 'failed', 'completed-unread': 'finished' }
+const KIND_COLOR: Record<AttentionKind, string> = { 'needs-approval': THEME.warn, question: THEME.warn, failed: THEME.bad, 'completed-unread': THEME.ok }
+const STATUS_MARK: Record<SessionRow['status'], string> = { working: '●', idle: '○', done: '✓', failed: '✗', unknown: '?' }
+/** A title the harness wrote is transcript text: a text answer a model may read names the session by harness and id instead. */
+const titleOf = (ctx: Ctx, harness: string, key: string | null, title: string): string => (ctx.text === true && harness !== 'ruflo' && harness !== 'console' ? `${harness} session ${(key?.split(':').pop() ?? '').slice(0, 8)}` : title)
+const SHOWN_ROWS = 30
+const QUEUE_ROWS = 8
+
+const costText = (cost: SessionRow['cost']): string => (cost.label === 'unavailable' ? 'cost n/a' : `${cost.usd === undefined ? '' : `$${cost.usd.toFixed(2)} `}${cost.label}${cost.note === undefined ? '' : ` (${cost.note})`}`.trim())
+
+/** The Overview's one line: how many things need the person, or that nothing does. Empty when the workspace is off. */
+export function attentionOverviewRows(ctx: Ctx): RenderElement[] {
+ if (!ctx.state.options.sessionWorkspace) return []
+
+ const counts = attentionCounts(ctx.state)
+ const total = counts['needs-approval'] + counts.question + counts.failed + counts['completed-unread']
+ const detail = total === 0 ? 'nothing needs you' : `${counts['needs-approval']} to approve · ${counts.question} questions · ${counts.failed} failed · ${counts['completed-unread']} finished`
+
+ return [row(ctx, [text(ctx, ` sessions: ${detail}`, { color: total === 0 ? THEME.ok : THEME.warn }), button(ctx, 'overview-sessions', 'open in the Room', () => ctx.act.view('room'))], 'overview-sessions-row')]
+}
+
+function previewRows(ctx: Ctx, found: SessionRow): RenderElement[] {
+ const { state, nowMs } = ctx
+ const caps = workspaceOf(state).index?.reports.find(report => report.id === found.harness)?.capabilities
+ const rows: RenderElement[] = [rule(ctx, 'Preview', `${found.harness} · ${clip(found.nativeId, 12)}`)]
+
+ rows.push(text(ctx, ` ${titleOf(ctx, found.harness, found.key, found.title)}`, { bold: true }))
+ rows.push(text(ctx, ` ${found.status}${found.stale === null ? '' : ` · STALE: ${found.stale}`} · ${found.external ? 'started outside Ruflo' : 'started by Ruflo'} · updated ${found.updatedMs > 0 ? ago(found.updatedMs, nowMs) : 'n/a'} · ${costText(found.cost)}`, { dimColor: true }))
+ if (found.cwd !== null) rows.push(text(ctx, ` in ${clip(found.cwd, Math.max(20, ctx.columns - 10))}${found.branch === null ? '' : ` @ ${found.branch}`}`, { dimColor: true }))
+ for (const [i, line] of found.context.entries()) rows.push(text(ctx, ` ${clip(line, ctx.columns - 6)}`, { dimColor: true, ...(i === 0 && { bold: false }) }))
+
+ if (found.unassigned !== null) {
+ rows.push(text(ctx, ` Unassigned: ${found.unassigned}. Nothing is shown for it, so it cannot be mistaken for another session.`, { color: THEME.warn }))
+
+ return rows
+ }
+
+ if (!state.options.sessionPreview) {
+ rows.push(text(ctx, ' The preview is off (Settings: sessionPreview); no transcript text is drawn.', { dimColor: true }))
+ } else if (ctx.text === true) {
+ rows.push(text(ctx, ' (transcript text is not included in text answers)', { dimColor: true }))
+ } else if (found.preview === null) {
+ rows.push(text(ctx, ` No preview: ${found.noPreview ?? 'nothing was read yet'}.`, { dimColor: true }))
+ } else {
+ const p = found.preview
+
+ if (p.latest !== '') rows.push(...fullRows(ctx, ' latest: ', p.latest, { key: 'sess-latest', maxLines: 6 }))
+ else rows.push(text(ctx, ' latest: nothing said yet', { dimColor: true }))
+
+ rows.push(text(ctx, ` tool: ${p.tool ?? 'none seen'}`, { dimColor: true }))
+ rows.push(text(ctx, ` files: ${p.files.length === 0 ? 'none edited' : clip(p.files.join(', '), Math.max(20, ctx.columns - 12))}`, { dimColor: true }))
+ rows.push(text(ctx, ` tests: ${p.test ?? 'none run'}`, { dimColor: true }))
+ // Drawn text is the evidence "viewed" waits for; the page's tick commits it (sessions.ts `commitViewed`).
+ if (p.latest !== '' || p.tool !== null || p.files.length > 0 || p.test !== null) noteShown(state, found.key, nowMs)
+ }
+
+ const open = caps?.resume
+ const openText = open?.supported === true ? 'open is not wired in this version' : `open: unavailable (${open?.why ?? 'not declared'})`
+
+ rows.push(row(ctx, [text(ctx, ` ${openText}`, { dimColor: true }), button(ctx, `sess-open-${found.key}`, 'open', () => ctx.act.sessions.open(found.key))], 'sess-open-row'))
+
+ return rows
+}
+
+/** The queue, the browser and the preview, in that order. Empty when the workspace is off. */
+export function sessionRows(ctx: Ctx): RenderElement[] {
+ const { state, nowMs } = ctx
+
+ if (!state.options.sessionWorkspace) return []
+
+ const ws = workspaceOf(state)
+ const queue = queueOf(state)
+ const rows: RenderElement[] = [rule(ctx, 'Needs you', queue.length === 0 ? 'nothing' : `${queue.length}`)]
+
+ if (queue.length === 0) rows.push(text(ctx, ' Nothing needs you. Approvals, questions, failures and finished work from every session appear here, from sessions started outside Ruflo too.', { dimColor: true }))
+
+ for (const item of queue.slice(0, QUEUE_ROWS)) {
+ rows.push(
+ row(
+ ctx,
+ [
+ text(ctx, ` ${KIND_LABEL[item.kind].padEnd(14)}`, { bold: true, color: KIND_COLOR[item.kind] }),
+ text(ctx, `${item.harness.padEnd(8)}`, { dimColor: true }),
+ item.rowKey === null ? text(ctx, clip(item.title, ctx.columns - 36)) : button(ctx, `sess-jump-${item.id}`, clip(titleOf(ctx, item.harness, item.rowKey, item.title), Math.max(12, ctx.columns - 36)), () => ctx.act.sessions.jump(item.id)),
+ text(ctx, ` ${ago(item.atMs, nowMs)}${item.stale ? ' · stale' : ''}`, { dimColor: true }),
+ ],
+ `sess-q-${item.id}`,
+ ),
+ )
+ }
+
+ if (queue.length > QUEUE_ROWS) rows.push(text(ctx, ` +${queue.length - QUEUE_ROWS} more`, { dimColor: true }))
+
+ const index = ws.index
+
+ rows.push(rule(ctx, 'Sessions', index === null ? 'looking…' : `${index.rows.length} found${index.unassigned > 0 ? ` · ${index.unassigned} unassigned` : ''}`))
+
+ if (index === null) return rows
+
+ for (const report of index.reports) {
+ const caps = CAPABILITIES.map(cap => `${cap} ${report.capabilities[cap].supported ? '✓' : '✗'}`).join(' · ')
+
+ rows.push(text(ctx, ` ${report.label}: ${report.state === 'not-detected' ? 'not detected' : report.state === 'failed' ? 'FAILED, showing the last read' : `${report.count} tracked`} · ${clip(report.note, 60)}`, { color: report.state === 'failed' ? THEME.warn : undefined, dimColor: report.state !== 'failed' }))
+ rows.push(text(ctx, ` can: ${caps}`, { dimColor: true }))
+ }
+
+ let left = SHOWN_ROWS
+
+ for (const group of index.groups) {
+ if (left <= 0) break
+
+ rows.push(text(ctx, ` ${group.label}`, { bold: true, color: group.unassigned ? THEME.warn : THEME.head }))
+
+ for (const found of group.rows.slice(0, left)) {
+ const picked = ws.selected === found.key
+
+ left -= 1
+ rows.push(
+ row(
+ ctx,
+ [
+ text(ctx, ` ${STATUS_MARK[found.status]} `, { color: found.status === 'failed' ? THEME.bad : found.status === 'working' ? THEME.ok : undefined, dimColor: found.status === 'idle' || found.status === 'unknown' }),
+ button(ctx, `sess-${found.key}`, `${picked ? '▾' : '▸'} ${clip(titleOf(ctx, found.harness, found.key, found.title), Math.max(12, ctx.columns - 46))}`, () => ctx.act.sessions.select(found.key)),
+ text(ctx, ` ${found.harness} · ${found.updatedMs > 0 ? ago(found.updatedMs, nowMs) : 'n/a'}${found.external ? ' · outside' : ''}${found.stale === null ? '' : ' · stale'}`, { dimColor: true }),
+ ],
+ `sess-row-${found.key}`,
+ ),
+ )
+ }
+ }
+
+ if (index.rows.length > SHOWN_ROWS) rows.push(text(ctx, ` +${index.rows.length - SHOWN_ROWS} more, the newest are listed first`, { dimColor: true }))
+
+ rows.push(row(ctx, [button(ctx, 'sess-prev', '◂ prev', () => ctx.act.sessions.move(-1)), button(ctx, 'sess-next', 'next ▸', () => ctx.act.sessions.move(1)), button(ctx, 'sess-refresh', 'rescan', ctx.act.sessions.refresh)], 'sess-nav'))
+
+ const found = rowOf(index, ws.selected)
+
+ if (found === undefined) rows.push(text(ctx, ' Pick a session to see its latest response, current tool, edited files and test result. Browsing never wakes or starts anything.', { dimColor: true }))
+ else rows.push(...previewRows(ctx, found))
+
+ if (ws.note !== '') rows.push(text(ctx, ` ${ws.note}`, { color: THEME.warn }))
+
+ return rows
+}
diff --git a/plugins/ruflo-console/scripts/smoke.sh b/plugins/ruflo-console/scripts/smoke.sh
index f4f9330e1e..fe934ea58e 100755
--- a/plugins/ruflo-console/scripts/smoke.sh
+++ b/plugins/ruflo-console/scripts/smoke.sh
@@ -11,9 +11,9 @@ step() { printf "→ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares ruflo-console 0.40.8"
+step "1. plugin.json declares ruflo-console 0.41.0"
grep -q '"name": "ruflo-console"' "$ROOT/.claude-plugin/plugin.json" \
- && grep -q '"version": "0.40.8"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
+ && grep -q '"version": "0.41.0"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
step "2. hooks.json names exactly one module and no classic hook commands"
grep -q '"modules": \["./register.ts"\]' "$HOOKS/hooks.json" && ! grep -q '"command"' "$HOOKS/hooks.json" \
diff --git a/plugins/ruflo-console/tests/fixtures/sessions-fs.ts b/plugins/ruflo-console/tests/fixtures/sessions-fs.ts
new file mode 100644
index 0000000000..643f4bd3f0
--- /dev/null
+++ b/plugins/ruflo-console/tests/fixtures/sessions-fs.ts
@@ -0,0 +1,188 @@
+/**
+ * A synthetic machine for the session workspace tests (ADR-486): an in-memory disk with 20 mixed sessions, none of them real. Every session
+ * carries a unique TOKEN in what it says, so a test can prove that selecting a row shows that row's words and no other row's.
+ */
+import type { SessionFs } from '../../hooks/data/harness'
+
+export const NOW = Date.UTC(2026, 9, 9, 12, 0, 0)
+export const HOME = '/home/u'
+export const CLAUDE = `${HOME}/.claude`
+export const CODEX = `${HOME}/.codex`
+
+type File = { content: string; mtimeMs: number; size?: number; kind?: 'file' | 'symlink'; statLink?: boolean }
+
+export type Disk = { files: Map<string, File>; reads: string[]; tails: string[]; failList: Set<string>; failRead: Set<string> }
+
+export const newDisk = (): Disk => ({ files: new Map(), reads: [], tails: [], failList: new Set(), failRead: new Set() })
+
+const parent = (path: string) => path.slice(0, path.lastIndexOf('/'))
+
+export function fsOn(disk: Disk, withTail = true): SessionFs {
+ const fs: SessionFs = {
+ read: async path => {
+ disk.reads.push(path)
+
+ const file = disk.files.get(path)
+
+ if (file === undefined || disk.failRead.has(path)) throw new Error('refused')
+ if ((file.size ?? file.content.length) > 4 * 1024 * 1024) throw new Error('over 4 MiB')
+
+ return file.content
+ },
+ stat: async path => {
+ const file = disk.files.get(path)
+
+ if (file !== undefined) return { kind: file.kind === 'symlink' && file.statLink !== true ? 'symlink' : 'file', size: file.size ?? file.content.length, mtimeMs: file.mtimeMs, isLink: file.statLink === true || file.kind === 'symlink' }
+
+ return [...disk.files.keys()].some(key => key.startsWith(`${path}/`)) ? { kind: 'dir' } : undefined
+ },
+ list: async path => {
+ if (disk.failList.has(path)) throw new Error('listing refused')
+
+ const names = new Map<string, { kind: string; size?: number; mtimeMs: number }>()
+
+ for (const [key, file] of disk.files) {
+ if (!key.startsWith(`${path}/`)) continue
+
+ const rest = key.slice(path.length + 1)
+ const slash = rest.indexOf('/')
+ const name = slash < 0 ? rest : rest.slice(0, slash)
+ const prior = names.get(name)
+
+ names.set(name, slash < 0 ? { kind: file.kind === 'symlink' ? 'symlink' : file.statLink === true ? 'file' : 'file', size: file.size ?? file.content.length, mtimeMs: file.mtimeMs } : { kind: 'dir', mtimeMs: Math.max(prior?.mtimeMs ?? 0, file.mtimeMs) })
+ }
+
+ if (names.size === 0) throw new Error('no such directory')
+
+ return [...names].map(([name, entry]) => ({ name, ...entry }))
+ },
+ }
+
+ if (withTail) {
+ fs.readTail = async (path, bytes) => {
+ disk.tails.push(path)
+
+ return (disk.files.get(path)?.content ?? '').slice(-bytes)
+ }
+ }
+
+ return fs
+}
+
+const j = (value: unknown) => JSON.stringify(value)
+export const uuid = (n: number) => `${n.toString(16).padStart(8, '0')}-0000-4000-8000-${n.toString(16).padStart(12, '0')}`
+const iso = (ms: number) => new Date(ms).toISOString()
+
+export type ClaudeSpec = { n: number; folder: string; cwd: string; token: string; end: 'completed' | 'failed' | 'question' | 'working' | 'idle'; ageMs: number; cost?: number; edits?: string[]; test?: boolean; idInEntries?: string }
+
+/** The lines Claude Code writes for a session, in the shapes read on a real machine (only what the adapter uses). */
+export function claudeLines(spec: ClaudeSpec): string {
+ const at = NOW - spec.ageMs
+ const id = spec.idInEntries ?? uuid(spec.n)
+ const base = (offset: number) => ({ sessionId: id, cwd: spec.cwd, gitBranch: 'main', timestamp: iso(at - offset), isSidechain: false })
+ const lines: unknown[] = [{ type: 'user', ...base(9000), message: { role: 'user', content: `please do ${spec.token}` } }]
+
+ for (const [i, file] of (spec.edits ?? []).entries()) {
+ lines.push({ type: 'assistant', ...base(8000 - i * 100), message: { role: 'assistant', content: [{ type: 'tool_use', id: `e${i}`, name: 'Edit', input: { file_path: file } }] } })
+ lines.push({ type: 'user', ...base(7900 - i * 100), message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: `e${i}`, content: 'ok' }] } })
+ }
+
+ if (spec.test === true) {
+ lines.push({ type: 'assistant', ...base(5000), message: { role: 'assistant', content: [{ type: 'tool_use', id: 'tt', name: 'Bash', input: { command: 'npx vitest run' } }] } })
+ lines.push({ type: 'user', ...base(4900), message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'tt', content: 'noise\nTests 12 passed (12)\n' }] } })
+ }
+
+ if (spec.end === 'failed') {
+ lines.push({ type: 'assistant', ...base(2000), message: { role: 'assistant', content: [{ type: 'tool_use', id: 'f1', name: 'Bash', input: { command: 'make' } }] } })
+ lines.push({ type: 'user', ...base(1000), message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'f1', is_error: true, content: 'boom' }] } })
+ } else if (spec.end === 'question') {
+ lines.push({ type: 'assistant', ...base(1000), message: { role: 'assistant', content: [{ type: 'text', text: `which one ${spec.token}?` }, { type: 'tool_use', id: 'q1', name: 'AskUserQuestion', input: { question: 'x' } }] } })
+ } else if (spec.end === 'working') {
+ lines.push({ type: 'assistant', ...base(500), message: { role: 'assistant', content: [{ type: 'text', text: `working on ${spec.token}` }, { type: 'tool_use', id: 'w1', name: 'Bash', input: { command: 'sleep 1' } }] } })
+ } else {
+ lines.push({ type: 'assistant', ...base(1000), message: { role: 'assistant', stop_reason: 'end_turn', content: [{ type: 'text', text: `done ${spec.token}` }] } })
+ if (spec.end === 'completed') lines.push({ type: 'system', subtype: 'turn_duration', ...base(0), durationMs: 5 })
+ }
+
+ lines.push({ type: 'ai-title', sessionId: id, aiTitle: `title ${spec.token}` })
+ if (spec.cost !== undefined) lines.push({ type: 'cost-state', sessionId: id, totalCostUSD: spec.cost, hasUnknownModelCost: false })
+
+ return `${lines.map(j).join('\n')}\n`
+}
+
+export function addClaude(disk: Disk, spec: ClaudeSpec, extra: Partial<File> = {}): string {
+ const path = `${CLAUDE}/projects/${spec.folder}/${uuid(spec.n)}.jsonl`
+
+ disk.files.set(path, { content: claudeLines(spec), mtimeMs: NOW - spec.ageMs, ...extra })
+
+ return path
+}
+
+export type CodexSpec = { n: number; day: string; cwd: string; token: string; end: 'complete' | 'aborted' | 'working'; ageMs: number; metaId?: string }
+
+export function addCodex(disk: Disk, spec: CodexSpec): string {
+ const at = NOW - spec.ageMs
+ const rec = (offset: number, type: string, payload: Record<string, unknown>) => j({ timestamp: iso(at - offset), type, payload })
+ const lines = [rec(3000, 'session_meta', { id: spec.metaId ?? uuid(spec.n), cwd: spec.cwd }), rec(2000, 'event_msg', { type: 'task_started', turn_id: 't' }), rec(1500, 'response_item', { type: 'function_call', name: 'shell', call_id: 'c1', arguments: '{}' })]
+
+ if (spec.end !== 'working') lines.push(rec(1200, 'response_item', { type: 'function_call_output', call_id: 'c1', output: 'x' }))
+ if (spec.end === 'complete') lines.push(rec(0, 'event_msg', { type: 'task_complete', turn_id: 't', last_agent_message: `codex says ${spec.token}` }))
+ if (spec.end === 'aborted') lines.push(rec(0, 'event_msg', { type: 'turn_aborted', turn_id: 't', reason: 'interrupted' }))
+
+ const path = `${CODEX}/sessions/${spec.day}/rollout-2026-10-09T10-00-00-${uuid(spec.n)}.jsonl`
+
+ disk.files.set(path, { content: `${lines.join('\n')}\n`, mtimeMs: at })
+
+ return path
+}
+
+export const TOKENS: string[] = []
+
+/** The 20-session machine: 8 Claude in three repositories (one in a worktree), a duplicated id, an id mismatch, a hostile transcript, a link, 3 Codex, and ruflo's own. */
+export function twentySessions(): { disk: Disk; tokens: Record<string, string> } {
+ const disk = newDisk()
+ const tokens: Record<string, string> = {}
+ const claude = (spec: Omit<ClaudeSpec, 'token'>, extra: Partial<File> = {}) => {
+ const token = `TOK${spec.n}X`
+
+ tokens[`claude-${spec.n}`] = token
+ addClaude(disk, { ...spec, token }, extra)
+ }
+
+ claude({ n: 1, folder: '-work-repo-a', cwd: '/work/repo-a', end: 'completed', ageMs: 60_000, cost: 1.25, edits: ['/work/repo-a/src/a.ts'], test: true })
+ claude({ n: 2, folder: '-work-repo-a', cwd: '/work/repo-a', end: 'failed', ageMs: 300_000 })
+ claude({ n: 3, folder: '-work-repo-a-wt', cwd: '/work/repo-a/.claude/worktrees/feat-x', end: 'question', ageMs: 120_000 })
+ claude({ n: 4, folder: '-work-repo-b', cwd: '/work/repo-b', end: 'working', ageMs: 2000 })
+ claude({ n: 5, folder: '-work-repo-b', cwd: '/work/repo-b', end: 'idle', ageMs: 3_600_000 })
+ claude({ n: 6, folder: '-work-repo-c', cwd: '/work/repo-c', end: 'completed', ageMs: 30_000 })
+ claude({ n: 7, folder: '-work-repo-c', cwd: '/work/repo-c', end: 'idle', ageMs: 7_200_000, cost: 0.4 })
+ claude({ n: 8, folder: '-work-repo-c', cwd: '/work/repo-c', end: 'completed', ageMs: 5_000_000 })
+ claude({ n: 14, folder: '-work-repo-b', cwd: '/work/repo-b', end: 'idle', ageMs: 9_000_000, cost: 2.5 })
+ // The same session id in two project folders: ambiguous, both unassigned.
+ claude({ n: 9, folder: '-work-repo-a', cwd: '/work/repo-a', end: 'completed', ageMs: 50_000 })
+ claude({ n: 9, folder: '-work-repo-b', cwd: '/work/repo-b', end: 'completed', ageMs: 40_000 })
+ // An entry that names another session than its file.
+ claude({ n: 10, folder: '-work-repo-b', cwd: '/work/repo-b', end: 'completed', ageMs: 45_000, idInEntries: uuid(999) })
+ // Hostile: stat says 5 MB, the tail is garbage, an over-long line, escape sequences, a bidi override and a credential-shaped string.
+ const hostile = `${'\u0000garbage not json\n'.repeat(500)}${`{"type":"assistant","message":{"content":[{"type":"text","text":"${'A'.repeat(450_000)}"}]}}\n`}{"type":"assistant","sessionId":"${uuid(11)}","timestamp":"${iso(NOW - 10_000)}","cwd":"/work/repo-c","message":{"stop_reason":"end_turn","content":[{"type":"text","text":"\\u001b]0;pwned\\u0007\\u001b[31mred\\u001b[0m \\u202eevil sk-ant-api03-${'x'.repeat(40)} TOK11X"}]}}\n{"type":"system","subtype":"turn_duration","sessionId":"${uuid(11)}","timestamp":"${iso(NOW - 10_000)}"}\n`
+
+ tokens['claude-11'] = 'TOK11X'
+ disk.files.set(`${CLAUDE}/projects/-work-repo-c/${uuid(11)}.jsonl`, { content: hostile, mtimeMs: NOW - 10_000, size: 5_000_000 })
+ // A transcript that is a link to a file outside the config directory: never read, never shown.
+ disk.files.set(`${CLAUDE}/projects/-work-repo-c/${uuid(12)}.jsonl`, { content: 'ESCAPED-SECRET-MARKER\n', mtimeMs: NOW - 5000, statLink: true })
+ // A project folder that is a link: skipped whole.
+ disk.files.set(`${CLAUDE}/projects/-linked/${uuid(13)}.jsonl`, { content: 'ESCAPED-SECRET-MARKER\n', mtimeMs: NOW - 5000, kind: 'symlink' })
+
+ const codex = (spec: Omit<CodexSpec, 'token'>) => {
+ const token = `TOK${spec.n}X`
+
+ tokens[`codex-${spec.n}`] = token
+ addCodex(disk, { ...spec, token })
+ }
+
+ codex({ n: 21, day: '2026/10/09', cwd: '/work/repo-a', end: 'complete', ageMs: 20_000 })
+ codex({ n: 22, day: '2026/10/09', cwd: '/work/repo-b', end: 'aborted', ageMs: 400_000 })
+ codex({ n: 23, day: '2026/10/08', cwd: '/work/repo-c', end: 'working', ageMs: 4000 })
+
+ return { disk, tokens }
+}
diff --git a/plugins/ruflo-console/tests/fixtures/sessions-world.ts b/plugins/ruflo-console/tests/fixtures/sessions-world.ts
new file mode 100644
index 0000000000..16f390053b
--- /dev/null
+++ b/plugins/ruflo-console/tests/fixtures/sessions-world.ts
@@ -0,0 +1,48 @@
+/** The shared rig for the session workspace specs (ADR-486): a console state over the synthetic 20-session machine. */
+import type { Host } from '../../hooks/host'
+import { workspaceOf, sessionActions } from '../../hooks/sessions'
+import { newState, type State } from '../../hooks/state'
+import type { Actions, Ctx } from '../../hooks/views/common'
+import { linesOf, plainKit } from '../../hooks/views/pane'
+import { sessionRows } from '../../hooks/views/sessions'
+import { CLAUDE, fsOn, HOME, NOW, twentySessions, type Disk } from './sessions-fs'
+
+export const mission = (id: string, state: string, objective: string) => ({ id, objective, state, revision: 1, executionMode: 'x', plan: { revision: 1, taskCount: 0, tasks: [] }, budget: null, evidence: { count: 0, verified: 0 }, executor: null, unresolvedOperations: 0, updatedAtMs: NOW - 1000 })
+
+export function world(opts: { disk?: Disk; tokens?: Record<string, string>; tail?: boolean } = {}) {
+ const made = opts.disk === undefined ? twentySessions() : { disk: opts.disk, tokens: opts.tokens ?? {} }
+ const state: State = newState({})
+ const stored = new Map<string, unknown>()
+ const spawned: string[] = []
+
+ state.cwd = '/work/repo-a'
+ state.home = HOME
+ state.configDir = CLAUDE
+ state.view = 'room'
+ state.pane.isOpen = true
+ state.pane.isShown = true
+ state.snapshot = { missions: { observedAtMs: NOW, isTruncated: false, missions: [mission('m1', 'awaitingAuthorization', 'ship TOKM1X'), mission('m2', 'completed', 'done TOKM2X')] }, agents: [{ id: 'a1', type: 'coder', name: 'worker-one', status: 'failed' }], claims: [] } as unknown as State['snapshot']
+
+ const host = {
+ fs: fsOn(made.disk, opts.tail !== false),
+ invalidate: () => undefined,
+ storeSet: async (key: string, value: unknown) => void stored.set(key, value),
+ storeGet: async (key: string) => stored.get(key),
+ run: async (argv: readonly string[]) => (spawned.push(argv.join(' ')), Promise.reject(new Error('no process'))),
+ spawn: (argv: readonly string[]) => (spawned.push(argv.join(' ')), Promise.reject(new Error('no process'))),
+ } as unknown as Host
+
+ workspaceOf(state).viewed = { baselineMs: NOW - 3_600_000, seen: {} }
+
+ return { ...made, state, host, stored, spawned }
+}
+
+export const ctxOf = (state: State, host: Host, extra: Partial<Ctx> = {}): Ctx => ({ kit: plainKit(), state, nowMs: NOW, columns: 140, pictures: new Map(), act: { sessions: sessionActions(state, host), view: () => undefined, room: new Proxy({}, { get: () => () => undefined }) } as unknown as Actions, ...extra })
+export const drawn = (state: State, host: Host, extra: Partial<Ctx> = {}): string => {
+ const out: string[] = []
+
+ for (const element of sessionRows(ctxOf(state, host, extra))) linesOf(element, out)
+
+ return out.join('\n')
+}
+
diff --git a/plugins/ruflo-console/tests/sessions-real-fs.spec.ts b/plugins/ruflo-console/tests/sessions-real-fs.spec.ts
new file mode 100644
index 0000000000..224a305702
--- /dev/null
+++ b/plugins/ruflo-console/tests/sessions-real-fs.spec.ts
@@ -0,0 +1,101 @@
+/**
+ * The session workspace over a real directory (ADR-486): the synthetic machine written to a temp folder and read through node's own file
+ * system with link-aware stats, the way the host's `$.fs` reports them. A real symlink to a file outside the folder must never be read, a
+ * linked project folder must never be entered, and a real pass over 20 sessions is timed.
+ * npx vitest run plugins/ruflo-console/tests/sessions-real-fs.spec.ts
+ */
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs'
+import { lstat, open, readdir, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { afterAll, describe, expect, it } from 'vitest'
+
+import type { SessionFs } from '../hooks/data/harness'
+import { rowOf } from '../hooks/data/sessions-index'
+import { scanSessions, workspaceOf } from '../hooks/sessions'
+import { NOW, uuid } from './fixtures/sessions-fs'
+import { world } from './fixtures/sessions-world'
+
+const root = mkdtempSync(join(tmpdir(), 'ruflo-sessions-'))
+
+afterAll(() => rmSync(root, { recursive: true, force: true }))
+
+const nodeFs: SessionFs = {
+ read: path => readFile(path, 'utf8'),
+ stat: async path => {
+ const l = await lstat(path).catch(() => undefined)
+
+ return l === undefined ? undefined : { size: l.size, mtimeMs: l.mtimeMs, kind: l.isFile() ? 'file' : l.isDirectory() ? 'dir' : 'other', isLink: l.isSymbolicLink() }
+ },
+ list: async path => Promise.all((await readdir(path, { withFileTypes: true })).map(async d => ({ name: d.name, kind: d.isSymbolicLink() ? 'symlink' : d.isDirectory() ? 'dir' : 'file', size: (await lstat(join(path, d.name))).size, mtimeMs: (await lstat(join(path, d.name))).mtimeMs }))),
+ readTail: async (path, bytes) => {
+ const handle = await open(path, 'r')
+
+ try {
+ const size = (await handle.stat()).size
+ const n = Math.min(bytes, size)
+ const buffer = Buffer.alloc(n)
+
+ await handle.read(buffer, 0, n, size - n)
+
+ return buffer.toString('utf8')
+ } finally {
+ await handle.close()
+ }
+ },
+}
+
+describe('over a real directory', () => {
+ it('never reads through a real symlink, enters a linked folder, or follows a link out of the config directory', async () => {
+ const w = world()
+ const outside = join(root, 'outside-secret.jsonl')
+
+ writeFileSync(outside, 'ESCAPED-SECRET-MARKER\n')
+
+ for (const [path, file] of w.disk.files) {
+ const real = join(root, path)
+
+ if (file.kind === 'symlink' || file.statLink === true) continue
+
+ mkdirSync(dirname(real), { recursive: true })
+ writeFileSync(real, file.content)
+ utimesSync(real, file.mtimeMs / 1000, file.mtimeMs / 1000)
+ }
+
+ const config = join(root, '/home/u/.claude')
+
+ symlinkSync(outside, join(config, 'projects/-work-repo-c', `${uuid(12)}.jsonl`))
+ mkdirSync(join(root, 'elsewhere'), { recursive: true })
+ writeFileSync(join(root, 'elsewhere', `${uuid(13)}.jsonl`), 'ESCAPED-SECRET-MARKER\n')
+ symlinkSync(join(root, 'elsewhere'), join(config, 'projects/-linked'))
+
+ const state = world().state
+ const reads: string[] = []
+ const host = { fs: { ...nodeFs, read: (path: string) => (reads.push(path), nodeFs.read(path)) }, invalidate: () => undefined } as never
+
+ state.configDir = config
+ state.home = join(root, '/home/u')
+
+ const started = performance.now()
+
+ await scanSessions(state, host, true, NOW)
+
+ const full = performance.now() - started
+ const index = workspaceOf(state).index!
+ const link = index.rows.find(row => row.nativeId === uuid(12))
+
+ // The listing already says it is a link, so it is not a session at all (the synthetic spec covers a link only a stat reveals).
+ expect(link).toBeUndefined()
+ expect(index.rows.some(row => row.nativeId === uuid(13))).toBe(false)
+ expect(reads.some(path => path.includes('outside-secret') || path.includes('elsewhere') || path.includes(uuid(12)))).toBe(false)
+ expect(JSON.stringify([...index.rows])).not.toContain('ESCAPED-SECRET')
+ expect(rowOf(index, `claude:${config}:${uuid(1)}`)?.preview?.latest).toContain('TOK1X')
+
+ const again = performance.now()
+
+ await scanSessions(state, host, false, NOW + 1000)
+ console.log(`real disk: full pass ${full.toFixed(1)} ms, incremental pass ${(performance.now() - again).toFixed(1)} ms over ${index.rows.length} sessions`)
+ expect(full).toBeLessThan(1000)
+ })
+})
diff --git a/plugins/ruflo-console/tests/sessions-safety.spec.ts b/plugins/ruflo-console/tests/sessions-safety.spec.ts
new file mode 100644
index 0000000000..a0e531738d
--- /dev/null
+++ b/plugins/ruflo-console/tests/sessions-safety.spec.ts
@@ -0,0 +1,260 @@
+/**
+ * The session workspace's safety and budgets (ADR-486): hostile and unreadable input, what never leaves the workspace, the 2 s and 100 ms budgets,
+ * the adapters on their own, and the counts-only summary for ruflo-mods. The measured numbers are printed; the thresholds are the requirement's.
+ * npx vitest run plugins/ruflo-console/tests/sessions-safety.spec.ts
+ */
+import { describe, expect, it } from 'vitest'
+
+import { claudeAdapter } from '../hooks/data/harness-claude'
+import { codexAdapter } from '../hooks/data/harness-codex'
+import { LINE_CAP, scanRecords, shown } from '../hooks/data/harness-text'
+import { rowOf } from '../hooks/data/sessions-index'
+import type { Host } from '../hooks/host'
+import { mirrorAttention, queueOf, scanSessions, selectRow, workspaceOf } from '../hooks/sessions'
+import { viewText } from '../hooks/views/pane'
+import { addClaude, CLAUDE, CODEX, fsOn, NOW, uuid } from './fixtures/sessions-fs'
+import { ctxOf, drawn, world } from './fixtures/sessions-world'
+
+describe('hostile and unreadable input', () => {
+ it('bounds a 5 MB garbage transcript, strips escapes and bidi, and masks a credential', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+
+ const row = rowOf(workspaceOf(w.state).index!, `claude:${CLAUDE}:${uuid(11)}`)!
+ // eslint-disable-next-line no-control-regex
+ const control = /[\u0000-\u001f\u007f-\u009f‪-‮]/
+
+ expect(row.preview).not.toBeNull()
+ expect(row.preview!.latest.length).toBeLessThanOrEqual(600)
+ expect(row.preview!.latest).toContain('TOK11X')
+ expect(row.preview!.latest).not.toMatch(control)
+ expect(row.preview!.latest).not.toContain('pwned')
+ expect(row.preview!.latest).not.toContain('sk-ant-api03')
+ expect(w.disk.tails.length).toBeGreaterThan(0)
+ expect(w.disk.reads.some(path => path.includes(uuid(11)))).toBe(false)
+ })
+
+ it('on a host with no tail read, lists a large transcript without reading it and says why', async () => {
+ const w = world({ tail: false })
+
+ await scanSessions(w.state, w.host, true, NOW)
+
+ const row = rowOf(workspaceOf(w.state).index!, `claude:${CLAUDE}:${uuid(11)}`)!
+
+ expect(row.preview).toBeNull()
+ expect(row.noPreview).toContain('larger than this host can read')
+ expect(w.disk.reads.some(path => path.includes(uuid(11)))).toBe(false)
+ })
+
+ it('skips a line over the cap and a non-object line without parsing them, and stops at the line limit', () => {
+ const seen: string[] = []
+ const stats = scanRecords(`${'x'.repeat(LINE_CAP + 10)}\n[1,2]\n{"a":1}\nnot json\n{"b":2}`, record => seen.push(Object.keys(record)[0]!))
+
+ expect(seen).toEqual(['a', 'b'])
+ expect(stats).toMatchObject({ skipped: 1, bad: 2 })
+ expect(scanRecords('{}\n'.repeat(60_000), () => undefined).lines).toBe(30_000)
+ })
+
+ it('has no backtracking on file text: a pathological line is handled in linear time', () => {
+ const started = performance.now()
+
+ shown(`${'a '.repeat(200_000)}‮${'\u001b['.repeat(50_000)}`, 600)
+ scanRecords(`{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Bash","input":{"command":"${'vitest '.repeat(50_000)}"}}]}}`, () => undefined)
+ expect(performance.now() - started).toBeLessThan(1500)
+ })
+
+ it('keeps the earlier rows, marked stale, when discovery or a read fails', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+
+ const before = workspaceOf(w.state).index!.rows.filter(row => row.harness === 'claude').length
+
+ w.disk.failList.add(`${CLAUDE}/projects`)
+ await scanSessions(w.state, w.host, true, NOW + 5000)
+
+ const after = workspaceOf(w.state).index!
+
+ expect(after.reports.find(report => report.id === 'claude')?.state).toBe('failed')
+ expect(after.rows.filter(row => row.harness === 'claude')).toHaveLength(before)
+ expect(after.rows.filter(row => row.harness === 'claude').every(row => row.stale !== null)).toBe(true)
+ expect(drawn(w.state, w.host)).toContain('FAILED, showing the last read')
+
+ // A single file whose read now fails keeps its summary.
+ w.disk.failList.clear()
+
+ const path = addClaude(w.disk, { n: 1, folder: '-work-repo-a', cwd: '/work/repo-a', token: 'TOK1X', end: 'completed', ageMs: 60_000, cost: 1.25 })
+
+ w.disk.files.get(path)!.mtimeMs = NOW + 1000
+ w.disk.failRead.add(path)
+ await scanSessions(w.state, w.host, true, NOW + 9000)
+
+ const kept = rowOf(workspaceOf(w.state).index!, `claude:${CLAUDE}:${uuid(1)}`)!
+
+ expect(kept.stale).toContain('read failed')
+ expect(kept.preview?.latest).toContain('TOK1X')
+ })
+})
+
+describe('what never leaves the workspace', () => {
+ it('draws no transcript text into a text answer a model may read', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+ selectRow(w.state, `claude:${CLAUDE}:${uuid(1)}`)
+
+ const answer = viewText({ state: w.state, nowMs: NOW, columns: 140, act: ctxOf(w.state, w.host).act }, 'room')
+
+ expect(answer).toContain('transcript text is not included in text answers')
+ for (const token of Object.values(w.tokens)) expect(answer).not.toContain(token)
+ })
+
+ it('keeps transcript text out of the console state that is snapshotted or exported', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+
+ const dump = JSON.stringify(w.state, (_key, value: unknown) => (value instanceof Map ? [...value] : value instanceof Set ? [...value] : typeof value === 'function' ? undefined : value))
+
+ for (const token of Object.values(w.tokens)) expect(dump).not.toContain(token)
+ expect([...w.stored.values()].map(value => JSON.stringify(value)).join('')).not.toContain('TOK')
+ })
+
+ it('starts no process and makes no model call while scanning', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+ await scanSessions(w.state, w.host, false, NOW + 1000)
+ expect(w.spawned).toEqual([])
+ })
+
+ it('draws nothing when the workspace is off, and no transcript when only the preview is off', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+ w.state.options.sessionPreview = false
+ selectRow(w.state, `claude:${CLAUDE}:${uuid(1)}`)
+ expect(drawn(w.state, w.host)).not.toContain('done TOK1X')
+ expect(drawn(w.state, w.host)).toContain('The preview is off')
+ w.state.options.sessionWorkspace = false
+ expect(drawn(w.state, w.host)).toBe('')
+ })
+})
+
+describe('budgets', () => {
+ it('surfaces a new approval-class change and a new completion within 2 s of its being written', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+
+ const before = queueOf(w.state).length
+ // A session finishes: its file grows and its mtime moves.
+ const path = addClaude(w.disk, { n: 77, folder: '-work-repo-a', cwd: '/work/repo-a', token: 'TOK77X', end: 'completed', ageMs: 500 })
+ const started = performance.now()
+
+ await scanSessions(w.state, w.host, false, NOW + 600)
+
+ const scanMs = performance.now() - started
+
+ expect(path).toContain(uuid(77))
+ expect(queueOf(w.state).some(item => item.rowKey === `claude:${CLAUDE}:${uuid(77)}` && item.kind === 'completed-unread')).toBe(true)
+ expect(queueOf(w.state).length).toBe(before + 1)
+ // The watcher ticks every 1000 ms: the worst case is a full tick plus the pass itself.
+ const worst = 1000 + scanMs
+
+ console.log(`surfacing: pass ${scanMs.toFixed(1)} ms, worst case ${worst.toFixed(1)} ms (budget 2000)`)
+ expect(worst).toBeLessThan(2000)
+ })
+
+ it('reads nothing again for an unchanged session', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+
+ const reads = w.disk.reads.length + w.disk.tails.length
+
+ await scanSessions(w.state, w.host, false, NOW + 1000)
+ expect(w.disk.reads.length + w.disk.tails.length).toBe(reads)
+ })
+
+ it('moves the selection through the whole list in under 100 ms p95', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+
+ const rows = workspaceOf(w.state).index!.rows
+ const times: number[] = []
+
+ for (let i = 0; i < 1500; i += 1) {
+ const key = rows[i % rows.length]!.key
+ const started = performance.now()
+
+ selectRow(w.state, key)
+ drawn(w.state, w.host)
+ times.push(performance.now() - started)
+ }
+
+ times.sort((a, b) => a - b)
+
+ const p95 = times[Math.floor(times.length * 0.95)]!
+
+ console.log(`selection: p50 ${times[Math.floor(times.length / 2)]!.toFixed(2)} ms, p95 ${p95.toFixed(2)} ms, max ${times.at(-1)!.toFixed(2)} ms over ${times.length} selections of ${rows.length} rows (budget 100)`)
+ expect(p95).toBeLessThan(100)
+ // The keypress did no I/O: nothing was read after the scan.
+ const reads = w.disk.reads.length
+
+ selectRow(w.state, rows[0]!.key)
+ drawn(w.state, w.host)
+ expect(w.disk.reads.length).toBe(reads)
+ })
+})
+
+describe('adapters on their own', () => {
+ it('reads Codex rollouts by their verified events', async () => {
+ const w = world()
+ const result = await codexAdapter().scan({ fs: fsOn(w.disk), claudeDir: null, codexDir: CODEX, nowMs: NOW, full: true })
+
+ expect(result.state).toBe('ok')
+ expect(result.rows.map(row => row.status).sort()).toEqual(['done', 'failed', 'working'])
+ expect(result.rows.find(row => row.status === 'failed')?.preview?.latest).toBe('turn aborted: interrupted')
+ })
+
+ it('finds a Claude session started after the first pass without a full relist', async () => {
+ const w = world()
+ const adapter = claudeAdapter()
+ const env = { fs: fsOn(w.disk), claudeDir: CLAUDE, codexDir: null, nowMs: NOW }
+
+ await adapter.scan({ ...env, full: true })
+ addClaude(w.disk, { n: 88, folder: '-work-repo-b', cwd: '/work/repo-b', token: 'TOK88X', end: 'question', ageMs: 100 })
+
+ const next = await adapter.scan({ ...env, full: false })
+
+ expect(next.rows.find(row => row.nativeId === uuid(88))?.signals.question).toBe(true)
+ })
+})
+
+describe('the summary for ruflo-mods', () => {
+ it('writes four counts and a time, nothing from a transcript, only in a ruflo project and only when a count changes', async () => {
+ const w = world()
+ const writes: { argv: readonly string[]; stdin: string }[] = []
+ const host = { ...w.host, run: async (argv: readonly string[], _t: number, stdin = '') => (writes.push({ argv, stdin }), { exitCode: 0, stdout: '', stderr: '', isStdoutTruncated: false, isStderrTruncated: false }) } as unknown as Host
+
+ await scanSessions(w.state, host, true, NOW)
+ ;(w.state.snapshot as unknown as { isRufloProject: boolean }).isRufloProject = false
+ await mirrorAttention(w.state, host, NOW)
+ expect(writes.filter(entry => entry.stdin.includes('ruflo-console.attention'))).toHaveLength(0)
+ ;(w.state.snapshot as unknown as { isRufloProject: boolean }).isRufloProject = true
+ await mirrorAttention(w.state, host, NOW)
+
+ const mine = writes.filter(entry => entry.stdin.includes('ruflo-console.attention'))
+
+ expect(mine).toHaveLength(1)
+ expect(JSON.parse(mine[0]!.stdin)).toMatchObject({ schema: 'ruflo-console.attention/1', approve: 1, question: 1 })
+ expect(mine[0]!.stdin).not.toContain('TOK')
+ expect(mine[0]!.argv.join(' ')).toContain('.claude-flow/console/attention.json')
+ await mirrorAttention(w.state, host, NOW + 5000)
+ expect(writes.filter(entry => entry.stdin.includes('ruflo-console.attention'))).toHaveLength(1)
+ })
+})
+
diff --git a/plugins/ruflo-console/tests/sessions.spec.ts b/plugins/ruflo-console/tests/sessions.spec.ts
new file mode 100644
index 0000000000..fd928d312d
--- /dev/null
+++ b/plugins/ruflo-console/tests/sessions.spec.ts
@@ -0,0 +1,256 @@
+/**
+ * The session workspace (ADR-486), against a synthetic machine of 20 mixed sessions (tests/fixtures/sessions-fs.ts): what each adapter finds
+ * and refuses, identity and the unassigned bucket, the attention queue, "read means viewed", and that a selection only ever shows its own session.
+ * npx vitest run plugins/ruflo-console/tests/sessions.spec.ts
+ */
+import { describe, expect, it } from 'vitest'
+
+import { attentionOf, markViewed } from '../hooks/data/sessions-attention'
+import { rowOf } from '../hooks/data/sessions-index'
+import { commitViewed, queueOf, scanSessions, selectRow, sessionActions, workspaceOf } from '../hooks/sessions'
+import type { State } from '../hooks/state'
+import { CLAUDE, newDisk, NOW, uuid } from './fixtures/sessions-fs'
+import { drawn, mission, world } from './fixtures/sessions-world'
+
+describe('discovery and identity', () => {
+ it('finds each adapter’s sessions, puts the ambiguous ones in the unassigned bucket and never reads a link', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+
+ const index = workspaceOf(w.state).index!
+ const by = (id: string) => index.rows.filter(row => row.harness === id)
+
+ expect(by('claude').length).toBe(14)
+ expect(by('codex').length).toBe(3)
+ expect(by('ruflo').length).toBe(3)
+ expect(index.rows.length).toBe(20)
+ expect(index.unassigned).toBe(3)
+ expect(index.groups.at(-1)?.unassigned).toBe(true)
+ expect(index.groups.at(-1)?.rows.map(row => row.nativeId).sort()).toEqual([uuid(9), uuid(9), uuid(10)].sort())
+ // The duplicated id yields two rows with two different keys: selecting one can never select the other.
+ expect(new Set(index.rows.map(row => row.key)).size).toBe(index.rows.length)
+ // A link is a row with no content; a linked project folder is not entered at all.
+ expect(rowOf(index, `claude:${CLAUDE}:${uuid(12)}`)).toMatchObject({ preview: null, noPreview: 'not a regular file' })
+ expect(w.disk.reads.some(path => path.includes(uuid(12)) || path.includes('-linked'))).toBe(false)
+ expect(index.rows.some(row => row.folder === '-linked')).toBe(false)
+ })
+
+ it('groups by repository and worktree from the recorded path alone, and by mission for ruflo’s own', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+
+ const labels = workspaceOf(w.state).index!.groups.map(group => group.label)
+
+ expect(labels).toContain('/work/repo-a')
+ expect(labels).toContain('/work/repo-a › feat-x')
+ expect(rowOf(workspaceOf(w.state).index!, 'ruflo:ruflo:mission-m1')).toMatchObject({ mission: 'm1', external: false })
+ })
+
+ it('marks sessions Ruflo did not start as outside, and only those the console holds as its own', async () => {
+ const w = world()
+
+ w.state.terminal.sessions = { claude: uuid(1) }
+ await scanSessions(w.state, w.host, true, NOW)
+
+ const index = workspaceOf(w.state).index!
+
+ expect(rowOf(index, `claude:${CLAUDE}:${uuid(1)}`)?.external).toBe(false)
+ expect(rowOf(index, `claude:${CLAUDE}:${uuid(2)}`)?.external).toBe(true)
+ })
+
+ it('declares only what was verified, and says why not for the rest', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+
+ const caps = Object.fromEntries(workspaceOf(w.state).index!.reports.map(report => [report.id, report.capabilities]))
+
+ for (const id of ['claude', 'codex']) {
+ expect(caps[id]).toMatchObject({ discovery: { supported: true }, preview: { supported: true }, approvals: { supported: false }, resume: { supported: false }, fork: { supported: false }, messaging: { supported: false }, stop: { supported: false } })
+ expect(caps[id]!.approvals.why.length).toBeGreaterThan(10)
+ }
+
+ expect(caps.ruflo).toMatchObject({ approvals: { supported: true }, resume: { supported: false } })
+ })
+
+ it('reports an adapter whose store is absent as not detected, and never throws', async () => {
+ const empty = world({ disk: newDisk() })
+
+ await scanSessions(empty.state, empty.host, true, NOW)
+
+ const reports = workspaceOf(empty.state).index!.reports
+
+ expect(reports.find(report => report.id === 'claude')?.state).toBe('not-detected')
+ expect(reports.find(report => report.id === 'codex')?.state).toBe('not-detected')
+ })
+})
+
+describe('the attention queue', () => {
+ it('raises the four kinds in order, from sessions Ruflo did not start too, and nothing for an unassigned row', async () => {
+ const w = world()
+
+ w.state.pending = { label: 'create the mission', args: [], expect: 'x', askedAtMs: NOW - 4000 } as unknown as State['pending']
+ await scanSessions(w.state, w.host, true, NOW)
+
+ const queue = queueOf(w.state)
+ const kinds = queue.map(item => item.kind)
+
+ expect(kinds[0]).toBe('needs-approval')
+ expect(queue.filter(item => item.kind === 'needs-approval').map(item => item.harness).sort()).toEqual(['console', 'ruflo'])
+ expect(queue.find(item => item.kind === 'question')?.rowKey).toBe(`claude:${CLAUDE}:${uuid(3)}`)
+ expect(queue.filter(item => item.kind === 'failed').map(item => item.harness).sort()).toEqual(['claude', 'codex', 'ruflo'])
+ expect(queue.filter(item => item.kind === 'completed-unread').length).toBeGreaterThanOrEqual(4)
+ expect(kinds).toEqual([...kinds].sort((a, b) => ['needs-approval', 'question', 'failed', 'completed-unread'].indexOf(a) - ['needs-approval', 'question', 'failed', 'completed-unread'].indexOf(b)))
+ // No item names any of the three unassigned rows.
+ const unassigned = new Set(workspaceOf(w.state).index!.rows.filter(row => row.unassigned !== null).map(row => row.key))
+
+ expect(queue.some(item => item.rowKey !== null && unassigned.has(item.rowKey))).toBe(false)
+ })
+
+ it('treats completions older than the baseline as history, not unread', async () => {
+ const w = world()
+
+ workspaceOf(w.state).viewed = { baselineMs: NOW + 1, seen: {} }
+ await scanSessions(w.state, w.host, true, NOW)
+ expect(queueOf(w.state).some(item => item.kind === 'completed-unread')).toBe(false)
+ })
+
+ it('keeps an approval until the harness stops reporting it, however often it is looked at', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+ selectRow(w.state, 'ruflo:ruflo:mission-m1')
+ drawn(w.state, w.host)
+ commitViewed(w.state, w.host, NOW)
+ expect(queueOf(w.state).some(item => item.id === 'ruflo:ruflo:mission-m1|needs-approval')).toBe(true)
+ // The harness reports it resolved: it goes.
+ ;(w.state.snapshot as unknown as { missions: { missions: ReturnType<typeof mission>[] } }).missions.missions[0]!.state = 'running'
+ await scanSessions(w.state, w.host, true, NOW)
+ expect(queueOf(w.state).some(item => item.id === 'ruflo:ruflo:mission-m1|needs-approval')).toBe(false)
+ })
+})
+
+describe('read means viewed', () => {
+ const completedKey = `claude:${CLAUDE}:${uuid(1)}`
+ const pendingFor = (w: ReturnType<typeof world>) => queueOf(w.state).some(item => item.rowKey === completedKey && item.kind === 'completed-unread')
+
+ it('clears a completion only after its preview text was drawn, and persists the viewed state', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+ expect(pendingFor(w)).toBe(true)
+ // Selecting alone, or committing with nothing drawn, clears nothing.
+ selectRow(w.state, completedKey)
+ expect(commitViewed(w.state, w.host, NOW)).toBe(false)
+ expect(pendingFor(w)).toBe(true)
+ // A frame drew the excerpt: the commit clears it, and the store holds it.
+ expect(drawn(w.state, w.host)).toContain('TOK1X')
+ expect(commitViewed(w.state, w.host, NOW)).toBe(true)
+ expect(pendingFor(w)).toBe(false)
+ expect(JSON.stringify(w.stored.get('ruflo-console/sessions-viewed'))).toContain(completedKey)
+ // Nothing else was cleared by it.
+ expect(queueOf(w.state).some(item => item.kind === 'completed-unread')).toBe(true)
+ })
+
+ it('does not clear when the preview is off, drawn for a model, a placeholder, in another view, or in a hidden pane', async () => {
+ const off = world()
+
+ off.state.options.sessionPreview = false
+ await scanSessions(off.state, off.host, true, NOW)
+ selectRow(off.state, completedKey)
+ expect(drawn(off.state, off.host)).not.toContain('done TOK1X')
+ expect(commitViewed(off.state, off.host, NOW)).toBe(false)
+
+ const textual = world()
+
+ await scanSessions(textual.state, textual.host, true, NOW)
+ selectRow(textual.state, completedKey)
+ drawn(textual.state, textual.host, { text: true })
+ expect(commitViewed(textual.state, textual.host, NOW)).toBe(false)
+
+ // A row with no preview (the link) draws a placeholder, which is not content.
+ const linked = world()
+
+ await scanSessions(linked.state, linked.host, true, NOW)
+ selectRow(linked.state, `claude:${CLAUDE}:${uuid(12)}`)
+ expect(drawn(linked.state, linked.host)).toContain('No preview')
+ expect(workspaceOf(linked.state).shown.size).toBe(0)
+
+ const away = world()
+
+ await scanSessions(away.state, away.host, true, NOW)
+ selectRow(away.state, completedKey)
+ drawn(away.state, away.host)
+ away.state.view = 'swarm'
+ expect(commitViewed(away.state, away.host, NOW)).toBe(false)
+ away.state.view = 'room'
+ away.state.pane.isShown = false
+ expect(commitViewed(away.state, away.host, NOW)).toBe(false)
+ })
+
+ it('brings a cleared failure back only when the session moves on to something newer', () => {
+ const row = { key: 'k', unassigned: null, stale: null, title: 't', harness: 'claude', updatedMs: 100, signals: { question: false, approval: false, failed: true, turnEndedAtMs: null } } as unknown as Parameters<typeof attentionOf>[0][number]
+ const first = attentionOf([row], { baselineMs: 0, seen: {} }, null)
+ const viewed = markViewed({ baselineMs: 0, seen: {} }, first)
+
+ expect(first).toHaveLength(1)
+ expect(attentionOf([row], viewed, null)).toHaveLength(0)
+ expect(attentionOf([{ ...row, updatedMs: 200 }], viewed, null)).toHaveLength(1)
+ })
+})
+
+describe('a selection only ever shows its own session', () => {
+ it('draws each row’s own words and none of the other rows’, for every row', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+
+ const index = workspaceOf(w.state).index!
+ const all = Object.values({ ...w.tokens, m1: 'TOKM1X', m2: 'TOKM2X' })
+ let checked = 0
+
+ for (const row of index.rows) {
+ selectRow(w.state, row.key)
+
+ const text = drawn(w.state, w.host)
+ const preview = text.slice(text.indexOf('Preview'))
+ const own = all.filter(token => (row.preview?.latest ?? '').includes(token) || row.title.includes(token) || (row.preview?.files ?? []).some(file => file.includes(token)))
+
+ for (const token of all) if (!own.includes(token)) expect(preview, `${row.key} must not show ${token}`).not.toContain(token)
+ if (row.unassigned !== null) for (const token of all) expect(preview).not.toContain(token)
+ checked += 1
+ }
+
+ expect(checked).toBe(20)
+ })
+
+ it('draws the latest response, tool, edited files, test result and cost label of a session', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+ selectRow(w.state, `claude:${CLAUDE}:${uuid(1)}`)
+
+ const text = drawn(w.state, w.host)
+
+ expect(text).toContain('done TOK1X')
+ expect(text).toContain('files: /work/repo-a/src/a.ts')
+ expect(text).toContain('tests: passed: Tests 12 passed (12)')
+ expect(text).toContain('$1.25 reported')
+ expect(text).toContain('started outside Ruflo')
+ selectRow(w.state, `claude:${CLAUDE}:${uuid(5)}`)
+ expect(drawn(w.state, w.host)).toContain('cost n/a')
+ })
+
+ it('shows the open action as unavailable, with the harness’s reason', async () => {
+ const w = world()
+
+ await scanSessions(w.state, w.host, true, NOW)
+ selectRow(w.state, `claude:${CLAUDE}:${uuid(1)}`)
+ expect(drawn(w.state, w.host)).toContain('open: unavailable (opening a session is a model turn')
+ sessionActions(w.state, w.host).open(`claude:${CLAUDE}:${uuid(1)}`)
+ expect(workspaceOf(w.state).note).toContain('open is unavailable for claude')
+ })
+})
+
diff --git a/plugins/ruflo-mods/.claude-plugin/plugin.json b/plugins/ruflo-mods/.claude-plugin/plugin.json
index 9e63e506a7..3a08c4887b 100644
--- a/plugins/ruflo-mods/.claude-plugin/plugin.json
+++ b/plugins/ruflo-mods/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-mods",
"description": "ruflo as a Claude Code mod (function hooks, ADR-404): in-process prompt routing, edit learning signals, tighten-only tool checks from ruflo policy, the cost-tracker budget ladder, a mod trust gate for newly installed mods, and the $.ruflo noun other mods compose their status with. Opt-in and removable: the classic hook-handler hooks stay the default and take every event back whenever the mod is not loaded.",
- "version": "0.3.16",
+ "version": "0.4.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -96,6 +96,13 @@
"required": false,
"default": false
},
+ "sessionAttention": {
+ "type": "boolean",
+ "title": "Session attention row",
+ "description": "Show one row in /ruflo-mods with the ruflo-console's attention counts (sessions waiting for approval, with a question, failed, or finished and unread), read from the small summary file the console keeps in .claude-flow/console/. Four counts only; no session title, path or transcript text. Observability only: never denies, rewrites or delays anything. Off by default.",
+ "required": false,
+ "default": false
+ },
"modTrust": {
"type": "string",
"title": "Mod trust gate",
diff --git a/plugins/ruflo-mods/CHANGELOG.md b/plugins/ruflo-mods/CHANGELOG.md
index ac2c613f06..4dcf920e61 100644
--- a/plugins/ruflo-mods/CHANGELOG.md
+++ b/plugins/ruflo-mods/CHANGELOG.md
@@ -2,6 +2,9 @@
Newest first. One `## <version> — <date>` heading per version, then `feat:`, `fix:`, `breaking:` and `chore:` bullets (ADR-478). Built from git history; older versions: `git log -- plugins/ruflo-mods`.
+## 0.4.0 — 2026-10-09
+- feat: sessionAttention option (default off): one attention row in /ruflo-mods with the console's four counts (to approve, questions, failed, finished unread). Counts only; no gating behaviour changed (ADR-486).
+
## 0.3.16 — 2026-10-07
- feat: shared toast system with levels, dedupe, persistence and Settings (ADR-477)
- feat: shared toast policy and its call sites (ADR-477), work in progress
diff --git a/plugins/ruflo-mods/README.md b/plugins/ruflo-mods/README.md
index 9eba99528c..a951548e29 100644
--- a/plugins/ruflo-mods/README.md
+++ b/plugins/ruflo-mods/README.md
@@ -93,6 +93,7 @@ Claude Code reads a plugin's options from `pluginConfigs["ruflo-mods@ruflo"].opt
| `compactCarry` | `false` | `session.compact` (ADR-451 item 7): appends at most 600 characters to what the compaction summary keeps: swarm id, topology word, agent count, open claim ids and status, last route agent, budget and policy words. Fixed words and identifiers only, screened, fails open, skipped when no swarm or claim is open. No live evidence doc yet; design in [ADR-451](../../v3/docs/adr/ADR-451-mod-capability-roadmap.md) |
| `capabilityProbe` | `false` | Observability only (ADR-451 item 5): `/ruflo-mods` gains `probe: engine <version> · events fired n/m · never fired: ...`; reads no payload and never denies, rewrites or delays. Live run: [ruflo-mods-options-live-2026-10.md](../../v3/docs/validation/ruflo-mods-options-live-2026-10.md); design in [ADR-451](../../v3/docs/adr/ADR-451-mod-capability-roadmap.md) |
| `sessionRollup` | `false` | Observability only (ADR-451 item 6): at session end one counter record (no prompt text, inputs or paths) goes to a user-global ledger capped at 50 sessions and 32 KB; `/ruflo-mods` shows the last few. Live run: [ruflo-mods-options-live-2026-10.md](../../v3/docs/validation/ruflo-mods-options-live-2026-10.md); design in [ADR-451](../../v3/docs/adr/ADR-451-mod-capability-roadmap.md) |
+| `sessionAttention` | `false` | Observability only (ADR-486): one `attention:` row in `/ruflo-mods` with ruflo-console's four counts (to approve, questions, failed, finished unread), read from `.claude-flow/console/attention.json`. Counts only; nothing gates, denies or delays. |
| `modTrust` | `observe` | `observe` / `refuse-risky` / `off`: the mod trust gate. Evidence: [capability review](../../v3/docs/validation/mod-capability-review-2026-10.md) |
| `modTrustAllow` | empty | Comma-separated plugin ids (`name@marketplace`, e.g. `ruflo-swarm@ruflo,ruflo-console@ruflo`) the gate never refuses. Evidence: [capability review](../../v3/docs/validation/mod-capability-review-2026-10.md) |
| `guidanceContext` | `false` | Screened lexical excerpts (at most five, 4096 characters) from a compiler-exported guidance projection; advisory, cannot authorize tool calls. Design in [ADR-447](../../v3/docs/adr/ADR-447-native-mod-guidance-observation-loop.md); evidence: [native guidance](../../v3/docs/validation/ADR-447-native-guidance-evidence.md) |
diff --git a/plugins/ruflo-mods/hooks/attention.ts b/plugins/ruflo-mods/hooks/attention.ts
new file mode 100644
index 0000000000..344d55109d
--- /dev/null
+++ b/plugins/ruflo-mods/hooks/attention.ts
@@ -0,0 +1,28 @@
+/** The console's attention summary (ADR-486): counts only, written by ruflo-console into its own state folder and read here as a courtesy. */
+export const ATTENTION_STATUS = '.claude-flow/console/attention.json'
+export const ATTENTION_MAX_BYTES = 2048
+/** A summary older than this is not shown as current: the console writes it only when a count changes, so a quiet queue stays unchanged for hours. */
+const count = (n: unknown) => (typeof n === 'number' && Number.isFinite(n) && n >= 0 ? Math.min(Math.floor(n), 99_999) : undefined)
+
+/**
+ * The one `attention:` row of `/ruflo-mods`, or undefined when the file is absent, foreign or malformed. Only four counts and the time the
+ * console wrote them are shown: no title, path or transcript text exists in the file, and none from it reaches the report. The file is written
+ * by the console and not authenticated; it never decides anything, and nothing here gates, denies or delays a hook.
+ */
+export function attentionLine(text: string, nowMs: number): string | undefined {
+ if (text.length > ATTENTION_MAX_BYTES) return undefined
+ try {
+ const o = JSON.parse(text) as { schema?: unknown; approve?: unknown; question?: unknown; failed?: unknown; unread?: unknown; atMs?: unknown }
+ if (o.schema !== 'ruflo-console.attention/1') return undefined
+ const approve = count(o.approve)
+ const question = count(o.question)
+ const failed = count(o.failed)
+ const unread = count(o.unread)
+ if (approve === undefined || question === undefined || failed === undefined || unread === undefined) return undefined
+ const at = typeof o.atMs === 'number' && Number.isFinite(o.atMs) && o.atMs > 0 && o.atMs <= nowMs + 60_000 ? Math.max(0, Math.round((nowMs - o.atMs) / 1000)) : undefined
+ const when = at === undefined ? 'time unknown' : at < 90 ? `${at}s ago` : at < 5400 ? `${Math.round(at / 60)}m ago` : `${Math.round(at / 3600)}h ago`
+ return ` attention: ${approve} to approve · ${question} question${question === 1 ? '' : 's'} · ${failed} failed · ${unread} finished unread (from the console, changed ${when}; unauthenticated)`
+ } catch {
+ return undefined
+ }
+}
diff --git a/plugins/ruflo-mods/hooks/options.ts b/plugins/ruflo-mods/hooks/options.ts
index f914379489..bee7b28d48 100644
--- a/plugins/ruflo-mods/hooks/options.ts
+++ b/plugins/ruflo-mods/hooks/options.ts
@@ -18,6 +18,7 @@ export type ModOptions = {
readonly compactCarry: boolean
readonly capabilityProbe: boolean
readonly sessionRollup: boolean
+ readonly sessionAttention: boolean
readonly modTrust: TrustPolicy
readonly modTrustAllow: ReadonlySet<string>
}
@@ -49,6 +50,7 @@ export function readOptions(options: PluginOptions | undefined): ModOptions {
compactCarry: bool(o.compactCarry, false),
capabilityProbe: bool(o.capabilityProbe, false),
sessionRollup: bool(o.sessionRollup, false),
+ sessionAttention: bool(o.sessionAttention, false),
modTrust: TRUST.includes(o.modTrust as TrustPolicy) ? (o.modTrust as TrustPolicy) : 'observe',
modTrustAllow: names(o.modTrustAllow),
}
diff --git a/plugins/ruflo-mods/hooks/session.ts b/plugins/ruflo-mods/hooks/session.ts
index eec2d21def..4381b4e188 100644
--- a/plugins/ruflo-mods/hooks/session.ts
+++ b/plugins/ruflo-mods/hooks/session.ts
@@ -4,13 +4,28 @@ import type { GuidanceHooks } from './guidance'
import { versionText } from './probe'
import { HANDSHAKE_MARKER, ownedEvents } from './ownership'
import type { ModOptions } from './options'
+import { ATTENTION_MAX_BYTES, ATTENTION_STATUS, attentionLine } from './attention'
import { MAX_BYTES, PROTECTOR_STATUS, protectorLine } from './protector'
import { redraw, report, under, type ModState } from './state'
import { bindToasts } from './toast'
/** `/ruflo-mods` plus the protector row when `.claude-flow/protector-mod/status.json` is present and readable (bounded, regular file only). */
-async function reportWithProtector($: EngineInterface, s: ModState): Promise<string> {
- const base = report(s)
+/** The `attention:` row when the sessionAttention option is on and the console's summary file is a small regular file; never anything else. */
+async function attentionRow($: EngineInterface, s: ModState, on: boolean): Promise<string | undefined> {
+ if (!on) return undefined
+ try {
+ const path = under(s, ATTENTION_STATUS)
+ const st = await $.fs.stat(path)
+ if (st.kind !== 'file' || st.size > ATTENTION_MAX_BYTES) return undefined
+ return attentionLine(await $.fs.read(path), await $.clock.now().catch(() => Date.now()))
+ } catch {
+ return undefined
+ }
+}
+
+async function reportWithProtector($: EngineInterface, s: ModState, withAttention = false): Promise<string> {
+ const extra = await attentionRow($, s, withAttention)
+ const base = extra === undefined ? report(s) : `${report(s)}\n${extra}`
try {
const path = under(s, PROTECTOR_STATUS)
const st = await $.fs.stat(path)
@@ -108,13 +123,13 @@ export function registerSession(on: On, state: ModState, options: ModOptions, gu
return next(e)
})
- on('command.run', { command: 'ruflo-mods' }, async $ => ({ text: await reportWithProtector($, state) }))
+ on('command.run', { command: 'ruflo-mods' }, async $ => ({ text: await reportWithProtector($, state, options.sessionAttention) }))
// `/ruflo` is ruflo-console's one command for every ruflo mod; its `mods` subcommand is this report. The console
// registers `/ruflo`; this hook answers `mods` wherever it sits in the chain and passes every other word on.
// `/ruflo-mods` above stays registered as its alias: ADR-406 removes, renames or reassigns no command.
// `/ruflo-console` is the same command as `/ruflo` (kept by ADR-406), so its `mods` is answered too.
for (const command of ['ruflo', 'ruflo-console'] as const) {
- on('command.run', { command }, async ($, e, next) => (e.args.trim().split(/\s+/)[0]?.toLowerCase() === 'mods' ? { text: await reportWithProtector($, state) } : next(e)))
+ on('command.run', { command }, async ($, e, next) => (e.args.trim().split(/\s+/)[0]?.toLowerCase() === 'mods' ? { text: await reportWithProtector($, state, options.sessionAttention) } : next(e)))
}
}
diff --git a/plugins/ruflo-mods/scripts/smoke.sh b/plugins/ruflo-mods/scripts/smoke.sh
index 927d94b7b4..1edcfce823 100755
--- a/plugins/ruflo-mods/scripts/smoke.sh
+++ b/plugins/ruflo-mods/scripts/smoke.sh
@@ -1,5 +1,5 @@
#!/usr/bin/env bash
-# Structural + security smoke for ruflo-mods v0.3.16 (ADR-404, ADR-447).
+# Structural + security smoke for ruflo-mods v0.4.0 (ADR-404, ADR-447).
# Static only: CI has no Claude Code, so the hooks module's behaviour is held
# by v3/@claude-flow/cli/__tests__/mods/*.test.ts and, where function hooks are
# on, by `claude plugin test plugins/ruflo-mods`.
@@ -12,9 +12,9 @@ ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
HOOKS="$ROOT/hooks"
-step "1. plugin.json declares ruflo-mods 0.3.16"
+step "1. plugin.json declares ruflo-mods 0.4.0"
grep -q '"name": "ruflo-mods"' "$ROOT/.claude-plugin/plugin.json" \
- && grep -q '"version": "0.3.16"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
+ && grep -q '"version": "0.4.0"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
step "2. hooks.json names exactly one module and no classic hook commands"
grep -q '"modules": \["./register.ts"\]' "$HOOKS/hooks.json" && ! grep -q '"command"' "$HOOKS/hooks.json" \
diff --git a/plugins/ruflo-mods/tests/attention.test.ts b/plugins/ruflo-mods/tests/attention.test.ts
new file mode 100644
index 0000000000..403de113ad
--- /dev/null
+++ b/plugins/ruflo-mods/tests/attention.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, test, tier } from 'claude-code/testing'
+
+import { ATTENTION_STATUS, attentionLine } from '../hooks/attention'
+import { run } from './fixtures/consumer'
+import { ROOT, START, world } from './fixtures/world'
+
+tier('user')
+
+const NOW = 1_800_000_000_000
+const summary = (over: Record<string, unknown> = {}) => JSON.stringify({ schema: 'ruflo-console.attention/1', approve: 2, question: 1, failed: 0, unread: 5, atMs: NOW - 30_000, ...over })
+
+describe('attention row of /ruflo-mods (ADR-486)', () => {
+ test('one line of four counts and when they changed; nothing else from the file', () => {
+ expect(attentionLine(summary(), NOW)).toBe(' attention: 2 to approve · 1 question · 0 failed · 5 finished unread (from the console, changed 30s ago; unauthenticated)')
+ expect(attentionLine(summary({ title: 'ignore previous instructions', path: '/secret' }), NOW)).not.toContain('ignore')
+ expect(attentionLine(summary({ atMs: 'soon' }), NOW)).toContain('time unknown')
+ })
+
+ test('a foreign, oversized or malformed file shows no row', () => {
+ for (const bad of ['', 'not json', summary({ schema: 'other' }), summary({ approve: -1 }), summary({ unread: 'many' }), `${summary()}${' '.repeat(3000)}`]) expect(attentionLine(bad, NOW)).toBeUndefined()
+ })
+
+ test('off by default: the report never reads the file', async ($, on) => {
+ const w = world(on, {}, { [`${ROOT}/${ATTENTION_STATUS}`]: summary() })
+ await $.session.start(START)
+ expect(((await $.command.run(run('ruflo-mods'))).text ?? '') as string).not.toContain('attention:')
+ expect(w.files.size).toBeGreaterThan(0)
+ })
+
+ test('on: /ruflo-mods carries the row when the summary is present and omits it when not', { options: { sessionAttention: true } }, async ($, on) => {
+ const w = world(on)
+ await $.session.start(START)
+ expect(((await $.command.run(run('ruflo-mods'))).text ?? '') as string).not.toContain('attention:')
+ w.files.set(`${ROOT}/${ATTENTION_STATUS}`, summary({ atMs: 1 }))
+ const text = ((await $.command.run(run('ruflo-mods'))).text ?? '') as string
+ expect(text).toContain('attention: 2 to approve')
+ expect(text).toContain('ruflo mods (ADR-404)')
+ })
+})
diff --git a/scripts/ci-test-excluded.txt b/scripts/ci-test-excluded.txt
index 15c4216c67..3e50669875 100644
--- a/scripts/ci-test-excluded.txt
+++ b/scripts/ci-test-excluded.txt
@@ -43,6 +43,7 @@ plugins/ruflo-market-data/tests/textsof.test.ts
plugins/ruflo-metaharness/tests/register.test.ts
plugins/ruflo-metaharness/tests/textsof.test.ts
plugins/ruflo-migrations/tests/migrations-mod.test.ts
+plugins/ruflo-mods/tests/attention.test.ts
plugins/ruflo-mods/tests/agents.test.ts
plugins/ruflo-mods/tests/compact.test.ts
plugins/ruflo-mods/tests/delivery.test.ts
diff --git a/v3/docs/adr/ADR-486-session-workspace.md b/v3/docs/adr/ADR-486-session-workspace.md
new file mode 100644
index 0000000000..d3bbc23486
--- /dev/null
+++ b/v3/docs/adr/ADR-486-session-workspace.md
@@ -0,0 +1,133 @@
+# ADR 486: Session workspace: attention queue, session browser and preview
+
+Status: Accepted (phase 1 implemented; items 4 to 6 accepted as roadmap)
+
+Date: 2026-10-09
+
+Builds on: ADR-448 (the Room), ADR-473 (incremental transcripts, and what the host `$.fs` can read), ADR-481 (one sanitiser for drawn text), ADR-444 (Claude controls the console), ADR-477 (toasts), ADR-406 (mission observation)
+
+Numbering: ADR-485 is taken twice (the x-gateway query tools, and the open ruvnet-brain grounding change); this is 486.
+
+## 1. Context
+
+Twenty agents are only manageable if the person is told which one needs them. Today the Room shows the one pending confirm, an event feed and the
+mods; the Workflows page reads one project's workflow runs. Nothing lists the Claude Code, Codex and Ruflo sessions on the machine together, and
+nothing says "this one is waiting for you" unless it was started through the console. Design input (rUv, 2026-10-09): a unified session
+workspace with an attention queue and a live preview, in this order of value: (1) attention queue, (2) session browser, (3) preview beside the
+list, (4) mission composer, (5) search previous work, (6) fork and compare. The biggest risk named was associating the wrong terminal or
+transcript with a session.
+
+Reference material: a public project's dashboard and harness docs were read for the shape of the idea only. No code or text was taken from it
+(its licence is unknown); everything here is implemented from the requirements above and from formats read on this machine.
+
+## 2. Decision
+
+**One workspace on the existing Room, not a new destination.** The Room already owns "waiting for a yes", the feed and the mods, so it gains a
+**Needs you** queue, a **Sessions** browser grouped by repository and worktree, and a **Preview** of the selected session. The Overview gains one
+line with the four counts. `sessionWorkspace` (default on) turns the section off; `sessionPreview` (default on) turns off every line of a
+session's response, tool, files and tests (titles stay, they name the row).
+
+### 2.1 Harness adapters declare what they can do
+
+`hooks/data/harness.ts` defines `HarnessAdapter { id, label, capabilities, scan(env) }`. Capabilities are `discovery, preview, approvals, resume,
+fork, messaging, stop`, each `{ supported, why }`. An action a harness has not declared stays unavailable and the page says why (Enter on a
+row shows "open: unavailable (reason)"). Declared, verified against the on-disk formats on this machine:
+
+| adapter | discovery | preview | approvals | resume | fork | messaging | stop |
+|---|---|---|---|---|---|---|---|
+| `claude` (`<config>/projects/<folder>/<id>.jsonl`) | yes | yes | no: Claude Code writes no pending permission request into the transcript | no | no | no | no |
+| `codex` (`<codex>/sessions/Y/M/D/rollout-*-<id>.jsonl`) | yes | yes | no: none appears in the rollouts read | no | no | no | no |
+| `ruflo` (mission observation, agent stores; no disk read) | yes | status and counts only | yes: `awaitingAuthorization` | no | no | no | no |
+
+`resume` is "no" everywhere because opening a session is a model turn; browsing must never start or wake one. The cost label is **reported**
+(Claude's `cost-state.totalCostUSD`, a mission's settled spend), **estimated** (a mission's estimate; nothing is estimated for transcripts, there
+is no price table here) or **unavailable**, shown as such, never as zero.
+
+### 2.2 Identity, and what is not sure stays unassigned
+
+Identity is `harness + canonical home + native id`. The native id is the file name's id. A row becomes **unassigned** when an entry inside the file
+names a different id (Claude's `sessionId`, Codex's `session_meta.id`) or when two files claim the same id. An unassigned row sits in its own
+bucket, shows no title from the file, no preview and no cwd, and raises **no attention item**. Duplicated rows get distinct keys so selecting one can
+never select (or show) the other. The recorded `cwd` is split into repository and worktree by path alone (`<repo>/.claude/worktrees/<name>` and
+kin): no git runs, no disk is touched. Where a file's cwd cannot be read (a transcript the host cannot read) the group is the project folder's
+name; it is never decoded back into a path.
+
+### 2.3 The attention queue
+
+Kinds, in order: `needs-approval, question, failed, completed-unread`. Rules:
+
+- **Approvals and questions stay until the harness stops reporting them**; looking at one never clears it. The console's own pending confirm is an
+ approval item for as long as `state.pending` is set.
+- **Read means viewed.** A failure or a completion clears only after a frame actually drew that session's preview text (`noteShown`), committed by
+ the page's tick (`commitViewed`) while the Room is the page in front and the pane is shown. A placeholder, an error line, a text answer, a hidden
+ pane, another page, or `sessionPreview` off clears nothing. A cleared failure returns if the session moves on to something newer.
+- **History is not unread.** The first run records a baseline; completions older than it are not queued. The viewed map (at most 500 entries,
+ numbers only) is the only thing persisted, in the plugin's store.
+- **Unknown stays unknown.** A claude failure is "the last tool failed and nothing followed it for 30 s"; a question is an open `AskUserQuestion`; a
+ completion is a `turn_duration` after the last conversation line. Anything else is not guessed.
+- **Stale is shown.** When listing fails the earlier rows are kept, marked stale, with the adapter reported FAILED; a read that fails keeps the
+ earlier summary.
+
+### 2.4 Discovery is local, bounded and incremental
+
+No model call, no process, no wake. Every file is stat-ed first (a link is refused, a vanished file dropped) and read again only when size or mtime
+changed; a pass reads at most 12 MB. A fast pass runs every second while the pane is shown (the 60 newest sessions, the 8 most recently active
+project folders, folders whose mtime moved) and a full relist every 15 s; a closed pane scans every 30 s. A window is the whole file under 2 MB
+or its last 256 KB where the host offers `readTail`; a line over 400 KB is skipped unparsed, at most 30,000 lines are looked at, and nothing uses
+a backtracking pattern on file text. **The host `$.fs` has no tail read (ADR-473)**, so on the real host a transcript over 2 MB is listed from its
+stat and shows "larger than this host can read" instead of a preview; it is not guessed from the folder name. Previews are computed during the scan,
+so moving the selection does no I/O.
+
+### 2.5 Mission context
+
+A Ruflo mission row shows the active task and what it follows, how many of its tasks are claimed, the ADRs attached to it, and how much of its
+evidence is verified, from the observation, the ledger and the claims the console already reads. Only what exists is shown.
+
+### 2.6 ruflo-mods
+
+`sessionAttention` (default off) adds one `attention:` row to `/ruflo-mods` with four counts and when they changed. The console keeps those counts
+(only) in `.claude-flow/console/attention.json`, in a ruflo project, rewritten only when a count changes. No gating behaviour changed.
+
+## 3. Threat model
+
+| threat | control |
+|---|---|
+| Wrong session shown or acted on | identity above; unassigned bucket; distinct keys; lookup only by key; a property test draws every row and checks no other row's words appear |
+| Escape sequences, bidi, control characters, credentials in transcript text | every string drawn is cut and cleaned at read time by the one sanitiser (`plain` + the workflows `cleanText` mask, ADR-481 rules); a title or path is cleaned too |
+| Transcript text reaching a model | the preview lives in a side table, not in `State`; `viewText` (what `console_state` and ask-claude read) draws structure and "transcript text is not included", and transcript titles read `claude session <id>`; anything a model sees still passes `modelLine` |
+| Transcript text on disk, in snapshots, recordings, telemetry | nothing is written but the viewed map and four counts; a test dumps the whole console state and the store and finds no transcript text |
+| Hostile JSONL: huge, garbage, one enormous line, deep nesting | window and line caps above, 12 MB per pass, at most 60 tracked sessions per adapter; a 5 MB garbage fixture is bounded and its escape/bidi/credential content stripped |
+| Path traversal and symlinks | project and file names are matched against fixed patterns; a link (by listing or by stat) is never read; a linked project folder is never entered; tested on a real directory |
+| Waking an agent | no adapter spawns or messages; a test fails the host's `run` and `spawn` and scans |
+| ReDoS | no nested quantifiers on file text; a pathological line is timed |
+
+## 4. Roadmap (accepted, not built)
+
+4. **Mission composer** (goal, project, harness; model, budget and permissions behind an options panel). Only offers a harness whose adapter
+ declares the action, and starts a session through the existing confirm-gated mission path.
+5. **Search previous work**, text first, then RuVector semantic over the same bounded windows, with passages shown and resume offered only
+ where `resume` is declared. Search results obey 2.2 and the threat model; an index would hold derived vectors, never raw transcripts.
+6. **Fork and compare**: branch a task into isolated worktrees (ADR-441 worktree-per-writer) and compare tests, cost and changes. Needs `fork`
+ declared by the harness and one writer per worktree; cost compares only like labels.
+
+## 5. Alternatives
+
+- **A new top-level page.** Rejected: the Room already holds pending asks and events; a second place to look defeats the point.
+- **Read approvals from the terminal or the process list.** Rejected: associating the wrong terminal is the named risk, and it needs a process
+ read. Approvals come from what the harness reports.
+- **Decode the project folder name into a cwd.** Rejected: the encoding is lossy.
+- **Persist previews for fast starts.** Rejected: it would write transcript text. The scan is fast enough.
+- **Mark read on selection.** Rejected: selecting is not seeing; the draw is the evidence.
+
+## 6. Consequences
+
+- The Room is longer; the section is off with one option, and the preview with another.
+- On the real host a session over 2 MB has a row and no preview until the host offers a tail read; Codex rollouts with a `session_meta` id that
+ differs from the file name (4 here) are unassigned rather than guessed.
+- Claude and Codex approvals are not detected. They will appear when a harness exposes them, behind a verified format and a new capability claim.
+
+## 7. Verification
+
+`tests/sessions.spec.ts`, `sessions-safety.spec.ts`, `sessions-real-fs.spec.ts` (synthetic fixtures only), mods `tests/attention.test.ts`. A
+read-only pass over this machine's real stores found sessions, ambiguity and timings (reported in the PR). Not verified: behaviour of a live Claude
+Code permission prompt in the transcript; Codex approval events; the host's `$.fs` read latency under load.
diff --git a/v3/docs/adr/INDEX-mod-system.md b/v3/docs/adr/INDEX-mod-system.md
index df8e2bf8e7..620740d4e5 100644
--- a/v3/docs/adr/INDEX-mod-system.md
+++ b/v3/docs/adr/INDEX-mod-system.md
@@ -68,6 +68,7 @@ Two files carry the number 430 (the menu's accents, and the menu-design amendmen
| 478 | Console What's new page, plugin changelogs | Accepted | 10-07 | 428, 477 | — | — | [ADR-478](ADR-478-console-whats-new.md) | — |
| 480 | Console ADRs page: your project's ADRs, and missions, loops and swarms that follow them | Accepted | 10-07 | 407, 443, 444, 450, 474, 477, 478 | — | this PR | console 0.39.0, swarm 0.3.5, workflows 0.6.4 | `adr.spec`, `adr-write.spec`, `adr-integration.spec`, `adr-page.spec`, `adr-mutation.spec`, `adr-digest.spec` |
| 483 | Console advisor checkpoints for mission loops (plan, repeated failure, before done) | Accepted | 10-08 | 441, 443, 444, 477, 480, 481 | — | this PR | console 0.40.0 | `mission-advisor.spec`, `mission-advisor-mutation.spec` |
+| 486 | Session workspace: attention queue, session browser and preview on the Room (Claude, Codex and Ruflo sessions) | Accepted | 10-09 | 406, 444, 448, 473, 477, 481 | — | this PR | console 0.41.0, mods 0.4.0 | `sessions.spec`, `sessions-safety.spec`, `sessions-real-fs.spec`, `attention.test` |
Other ADRs outside 404-451 that the mod ADRs lean on: 150 (removable integrations), 174 (failures as a learning signal), 322 and 322A/B/C (flywheel, evaluation and promotion, receipts), 324 and 325 (policy engine, claims plane), 103 (witness). The console's Mods section (`hooks/data/mods.ts`, console 0.33.1, PR #3707) reads the status files ADR 446 defines.