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

fix(ruflo-console): never read a link, FIFO or folder named status.json (ADR-450 T2, 0.33.16)

ruv2c5a9f65348a
diff --git a/plugins/ruflo-console/.claude-plugin/plugin.json b/plugins/ruflo-console/.claude-plugin/plugin.json
index b8b9f87536..d69b8e3bb4 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.33.15",
+ "version": "0.33.16",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-console/hooks/data/files.ts b/plugins/ruflo-console/hooks/data/files.ts
index 57a6787774..3e6cc6674f 100644
--- a/plugins/ruflo-console/hooks/data/files.ts
+++ b/plugins/ruflo-console/hooks/data/files.ts
@@ -10,7 +10,7 @@
/** The `$.fs` calls a reader makes; each may reject. */
export type ReaderFs = {
read: (path: string) => Promise<string>
- stat: (path: string) => Promise<{ mtimeMs?: number; size?: number } | undefined>
+ stat: (path: string) => Promise<{ mtimeMs?: number; size?: number; kind?: string; isLink?: boolean } | undefined>
list: (path: string) => Promise<readonly { name: string; kind?: string; size?: number; mtimeMs?: number }[]>
}
@@ -51,7 +51,7 @@ export const FEDERATION_DIR = '.claude-flow/federation'
export const NOSTR_KEY = '.ruflo/nostr.key'
/** What one read came to: the text, or why there is none. */
-export type Read = { text: string; mtimeMs: number } | { text: null; reason: 'missing' | 'too-large' | 'refused'; size?: number }
+export type Read = { text: string; mtimeMs: number } | { text: null; reason: 'missing' | 'too-large' | 'refused' | 'not-regular'; size?: number }
/** The text of each file as last read, by path, with the mtime and size it was read at. */
export type ReadCache = Map<string, { mtimeMs: number; size: number; text: string } | { missingUntilMs: number }>
@@ -59,9 +59,12 @@ export type ReadCache = Map<string, { mtimeMs: number; size: number; text: strin
/** A path found missing is not stat-ed again for this long: a file ruflo creates shows up within it. */
export const MISSING_RECHECK_MS = 10_000
-/** Reads one file, unless its mtime and size match what was read last; stats first, so a huge file is never read. */
-export async function readBounded(fs: ReaderFs, cache: ReadCache, path: string, max = READ_MAX): Promise<Read> {
- let stat: { mtimeMs?: number; size?: number } | undefined
+/**
+ * Reads one file, unless its mtime and size match what was read last; stats first, so a huge file is never read. With `regularOnly`, a path the
+ * engine's stat reports as a link (it follows links and reads their target, even outside the project) or as anything but a file is never read.
+ */
+export async function readBounded(fs: ReaderFs, cache: ReadCache, path: string, max = READ_MAX, regularOnly = false): Promise<Read> {
+ let stat: Awaited<ReturnType<ReaderFs['stat']>>
const before = cache.get(path)
@@ -77,6 +80,12 @@ export async function readBounded(fs: ReaderFs, cache: ReadCache, path: string,
return { text: null, reason: 'missing' }
}
+ if (regularOnly && (stat?.isLink === true || (stat?.kind !== undefined && stat.kind !== 'file'))) {
+ cache.delete(path)
+
+ return { text: null, reason: 'not-regular' }
+ }
+
const mtimeMs = stat?.mtimeMs ?? -1
const size = stat?.size ?? -1
diff --git a/plugins/ruflo-console/hooks/data/mods.ts b/plugins/ruflo-console/hooks/data/mods.ts
index b92dbe5608..a143f786a3 100644
--- a/plugins/ruflo-console/hooks/data/mods.ts
+++ b/plugins/ruflo-console/hooks/data/mods.ts
@@ -112,13 +112,15 @@ export async function readMods(fs: ReaderFs, cache: ReadCache, cwd: string): Pro
const names = entries.filter(entry => entry.kind !== 'file' && DIR.test(entry.name)).map(entry => entry.name).sort()
const kept = names.slice(0, MODS_MAX_FILES)
- const reads = await Promise.all(kept.map(async name => ({ name, read: await readBounded(fs, cache, under(cwd, `${ROOT}/${name}/status.json`), MODS_MAX_BYTES) })))
+ const reads = await Promise.all(kept.map(async name => ({ name, read: await readBounded(fs, cache, under(cwd, `${ROOT}/${name}/status.json`), MODS_MAX_BYTES, true) })))
const rows: ModRow[] = []
let refused = 0
for (const { name, read } of reads) {
if (read.text === null && read.reason === 'missing') continue
+ // a link, FIFO or folder named status.json (ADR-450 T2): counted as refused, never read
+
const row = parseModStatus(name, read.text, 'mtimeMs' in read ? read.mtimeMs : null)
if (row === null) refused += 1
diff --git a/plugins/ruflo-console/hooks/version.ts b/plugins/ruflo-console/hooks/version.ts
index ca21e10111..5b7183af71 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.33.15'
+export const CONSOLE_VERSION = '0.33.16'
diff --git a/plugins/ruflo-console/scripts/smoke.sh b/plugins/ruflo-console/scripts/smoke.sh
index 922cf4c7a0..26c17b65db 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.33.15"
+step "1. plugin.json declares ruflo-console 0.33.16"
grep -q '"name": "ruflo-console"' "$ROOT/.claude-plugin/plugin.json" \
- && grep -q '"version": "0.33.15"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
+ && grep -q '"version": "0.33.16"' "$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/mods-section.spec.ts b/plugins/ruflo-console/tests/mods-section.spec.ts
index 83db229823..d20a9e440d 100644
--- a/plugins/ruflo-console/tests/mods-section.spec.ts
+++ b/plugins/ruflo-console/tests/mods-section.spec.ts
@@ -68,6 +68,43 @@ describe('orderMods', () => {
})
})
+describe('readMods, a status.json that is not a regular file (ADR-450 T2)', () => {
+ // Observed on the live engine: stat follows a link and reports the target's size plus isLink; read follows it, even outside the project.
+ const kinds: Record<string, { kind: string; isLink: boolean }> = { 'ok-mod': { kind: 'file', isLink: false }, 'link-mod': { kind: 'file', isLink: true }, 'fifo-mod': { kind: 'other', isLink: false }, 'dir-mod': { kind: 'dir', isLink: false } }
+
+ it('never reads a link, a FIFO or a folder named status.json, and counts each as refused', async () => {
+ const fs = fakeFs({ 'ok-mod': status(), 'link-mod': status(), 'fifo-mod': status(), 'dir-mod': status() })
+ const stat = fs.stat
+
+ fs.stat = async path => ({ ...(await stat(path)), ...kinds[path.split('/').at(-2) ?? ''] })
+
+ const mods = await readMods(fs, new Map(), '/p')
+
+ expect(mods.rows.map(r => r.name)).toEqual(['ok'])
+ expect(mods.refused).toBe(3)
+ expect(fs.reads).toEqual(['/p/.claude-flow/ok-mod/status.json'])
+ })
+
+ it('still reads when the engine says nothing about the kind', async () => {
+ const fs = fakeFs({ 'ok-mod': status() })
+
+ expect((await readMods(fs, new Map(), '/p')).rows).toHaveLength(1)
+ })
+
+ it('drops a cached copy once the path turns into a link', async () => {
+ const fs = fakeFs({ 'ok-mod': status() })
+ const cache = new Map()
+
+ expect((await readMods(fs, cache, '/p')).rows).toHaveLength(1)
+
+ const stat = fs.stat
+
+ fs.stat = async path => ({ ...(await stat(path)), isLink: true })
+
+ expect(await readMods(fs, cache, '/p')).toMatchObject({ rows: [], refused: 1 })
+ })
+})
+
describe('readMods', () => {
it('reads only *-mod folders and skips a folder with no status file', async () => {
const fs = fakeFs({ 'docs-mod': status({ blocked: 2 }), 'sparc-mod': status(), 'agentdb': status(), 'quiet-mod': null, 'Bad-Mod': status(), '..-mod': status() }, ['loose-mod'])
diff --git a/v3/docs/validation/adr-450-t2-symlink-probe-2026-10.md b/v3/docs/validation/adr-450-t2-symlink-probe-2026-10.md
new file mode 100644
index 0000000000..4365826b7b
--- /dev/null
+++ b/v3/docs/validation/adr-450-t2-symlink-probe-2026-10.md
@@ -0,0 +1,37 @@
+# ADR-450 T2: what the engine does with a link, FIFO or folder named status.json (2026-10-05)
+
+Probe of the live Claude Code engine (the `$.fs` file API mods and the console use), run to settle the one open question in the [T2 triage](adr-450-open-items-triage-2026-10.md).
+
+## Method
+
+A throwaway plugin (outside the repo, in a private `mktemp` directory) registered a `/t2probe` command whose handler called `$.fs.stat`, `$.fs.read` and `$.fs.list` on `<project>/m/<case>/status.json` and returned what each gave. Run with `claude -p "/t2probe a b c d" --plugin-dir <plugin> --model haiku` from the scratch project. Every target was a scratch file; nothing under HOME or a system path was touched. Reads were raced against a 4 s timeout.
+
+## Observed (exact)
+
+| Case | `stat` | `read` | `list` of the folder |
+|---|---|---|---|
+| a. regular file | `{"kind":"file","size":28,"isLink":false}` | 28 chars | `{"kind":"file","size":28,"isLink":false}` |
+| b. symlink to a file inside the project | `{"kind":"file","size":34,"isLink":true}` (the target's kind and size) | **34 chars, the target's content** | `{"kind":"other","size":0,"isLink":true}` |
+| c. symlink to a scratch file **outside** the project | `{"kind":"file","size":30,"isLink":true}` | **30 chars, the outside file's content** | `{"kind":"other","size":0,"isLink":true}` |
+| d. folder named status.json | `{"kind":"dir","size":4096,"isLink":false}` | rejected: `EISDIR` | `{"kind":"dir","isLink":false}` |
+| e. FIFO named status.json | `{"kind":"other","size":0,"isLink":false}` | returned `""` at once, no block (4 s timeout not hit) | `{"kind":"other","size":0,"isLink":false}` |
+
+## Proven
+
+- `$.fs.read` follows a symlink, including one that points outside the project. The hole in T2 was real for links.
+- `$.fs.stat` follows the link for `kind` and `size` but reports `isLink: true`; `$.fs.list` reports a link as `kind: "other"` with `isLink: true`.
+- A folder is refused by `read` (EISDIR). A FIFO read did not hang in this run.
+- The console's `ReaderFs.stat` type declared only `{ mtimeMs?, size? }`, so `kind` and `isLink` were present at runtime and dropped by the type. The triage's "no lstat" was right about the type, wrong about the engine.
+
+## Fix (console 0.33.16)
+
+The brief suggested the `fs.list` kind. `stat` is used instead because `readBounded` already calls it per file: no extra call per mod folder, and `isLink` states the thing directly. `readBounded(..., regularOnly)` returns `not-regular` (and drops any cached copy) when stat says `isLink === true` or a `kind` other than `file`; `readMods` passes it for `status.json` only, and such a row is counted as refused ("N status files not shown"). When the engine says nothing about the kind (older engine, test fakes) the file is read as before. Other console files are unchanged: they are ruflo's own state, and some may legitimately be links.
+
+Console drive (seeded project: a regular `good-mod`, a `link-mod` linking to a file claiming calls 99 / blocked 7, a `fifo-mod`): the Room page showed `Mods … 1 reporting`, `[ ▸ good ] guard on · calls 3 · blocked 0`, and `2 status files not shown: an unknown shape, too large, or unreadable`. The linked file's numbers did not appear.
+
+## Not proven
+
+- Only one engine version and Linux were probed. macOS and Windows link semantics, and junctions, were not.
+- The FIFO read returning `""` is one observation of a read with no writer; whether another engine version blocks is unknown. The guard no longer reaches `read` for a FIFO either way.
+- A race (a file swapped for a link between `stat` and `read`) is not closed; the window is one poll and the content is still capped and shape-checked.
+- Other mods' writers (`$.fs.write` to their own status path) were not probed for link behaviour.