π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(ruflo-console): ruRE can read an outside folder the person allows (ADR-499, console 0.48.0) (#4452)
rUvd36d72a9ff6c
diff --git a/plugins/ruflo-console/.claude-plugin/plugin.json b/plugins/ruflo-console/.claude-plugin/plugin.jsonindex 0302fd2d5f..e0759059ba 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.47.0",+ "version": "0.48.0","author": {"name": "ruvnet","url": "https://github.com/ruvnet"@@ -105,6 +105,13 @@"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},+ "rureFolders": {+ "type": "string",+ "title": "Outside folders ruRE may read",+ "description": "Folders outside the project that the ruRE page may analyze, as name=/absolute/folder pairs separated by semicolons (for example samples=/data/samples; vendor=/opt/vendor/bin). A sample then names one as @samples/app/tool. Plain characters only (letters, digits . _ - /), no spaces, at most 16, never a filesystem root; a link in the folder or on the way is refused, and nothing else outside the project can be named. Changing it is an install-class change: it always waits for your Yes (the card shows the exact folders), and Claude's console tools can only propose it at the full control level. ruRE parses and never runs what it reads. Empty by default.",+ "required": false,+ "default": ""+ },"sessionWorkspace": {"type": "boolean","title": "Session workspace",diff --git a/plugins/ruflo-console/CHANGELOG.md b/plugins/ruflo-console/CHANGELOG.mdindex a1348c8d98..2aa2160327 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.48.0 β 2026-10-24+- feat: ruRE can read a folder outside the project that you allow (ADR-499). New option `rureFolders` (`name=/absolute/folder; name2=β¦`); a ruRE sample then names it as `@name/sub/file`. Changing the option is an install-class change that always waits for your Yes (Claude's console tools can only propose it at the full control level), so Claude can reach an outside folder only through a name you defined. A folder that is a link, a link anywhere below it, `..`, an absolute path typed as a sample, an unknown name, and a filesystem root are all refused; ruRE still only parses.+- chore: the preflight of a ruRE row now receives the console's options (same line count in the runner).+## 0.47.0 β 2026-10-23- feat: a **CUDA** row on the ruRE page (ADR-497) for the new `rure_analyze_cuda` tool: for a CUDA program, a `.cubin`, a `.fatbin` or a `.ptx` it shows the fatbin entries (kind, target `sm_NN`, compression), each kernel with its register count, code size and constant/shared memory, and the PTX version, target and kernel names. Needs a ruflo CLI that has the tool (the release after 3.60.1); on an older one the row says to update, as the other ruRE rows do.- feat: DETECT sends `.cubin`, `.fatbin` and `.ptx` files to the CUDA row, and the native-binary row says "holds CUDA code" for a program with a `.nv_fatbin` section, pointing at it.diff --git a/plugins/ruflo-console/hooks/actions.ts b/plugins/ruflo-console/hooks/actions.tsindex 48b1bee2ac..1b05595e52 100644--- a/plugins/ruflo-console/hooks/actions.ts+++ b/plugins/ruflo-console/hooks/actions.ts@@ -7,6 +7,7 @@ import { idOf, type AgentRecord, type ClaimRecord, type Claimant, type TaskRecorimport type { Snapshot } from './data/snapshot'import type { Findings } from './data/failure'import type { Host } from './host'+import type { Options } from './state'import type { WriteOp } from './data/write-via'export type ActionSpec = {@@ -23,7 +24,7 @@ export type ActionSpec = {* Before anything starts (a read at once, a confirmed action after the confirm): a reason it must not run (shown as the result, nothing spawned), or what to run* instead (the arguments, label, lab id, note and reader a check chose, ADR-496), or null to run as built. ADR-495 added it; ADR-496 lets it choose.*/- preflight?: (host: Pick<Host, 'fs'>) => Promise<string | Partial<Pick<ActionSpec, 'args' | 'label' | 'lab' | 'note' | 'lines'>> | null>+ preflight?: (host: Pick<Host, 'fs'>, options: Pick<Options, 'rureFolders'>) => Promise<string | Partial<Pick<ActionSpec, 'args' | 'label' | 'lab' | 'note' | 'lines'>> | null>/** A local check after a confirmed action succeeds; never part of background refreshes. */verifyLocal?: (host: Pick<Host, 'fs' | 'home'>) => Promise<boolean>/** Reads only: runs at once, without the confirm step, and shows what the CLI printed. */diff --git a/plugins/ruflo-console/hooks/data/devtools.ts b/plugins/ruflo-console/hooks/data/devtools.tsindex 2df26e01b8..d924db4d7e 100644--- a/plugins/ruflo-console/hooks/data/devtools.ts+++ b/plugins/ruflo-console/hooks/data/devtools.ts@@ -4,6 +4,7 @@* as `{"content":[{"type":"text","text":"<JSON>"}],"isError":β¦}`, so the readers unwrap that first.*/import { jsonAfter } from './cli'+import { aliasSampleOf } from './rure-folders'import { plain, recordOf } from './parse'import { labLines } from '../mh-lab'import { rureLines } from './rure'@@ -52,7 +53,7 @@ const RULES: Record<DevField, { test: (text: string) => string | null; rule: strref: { test: text => (/^[A-Za-z0-9@][A-Za-z0-9._/~^@{}-]{0,99}$/.test(text.trim()) ? text.trim() : null), rule: 'a git ref: HEAD, HEAD~3, main..HEAD, a branch or a sha (letters, digits . _ / ~ ^ @ { } -, not starting with -)' },path: { test: pathOf, rule: 'a path under the project: relative, letters, digits . _ / -, no .. segment, at most 160' },// ruRE (ADR-494): the file or folder to analyze. Same rule as `path`: only what is inside the project can be named here.- sample: { test: pathOf, rule: 'a file or folder under the project: relative, letters, digits . _ / -, no .. segment, at most 160 (the ruRE page analyzes only what is inside this project)' },+ sample: { test: text => pathOf(text) ?? aliasSampleOf(text), rule: 'a file or folder under the project: relative, letters, digits . _ / -, no .. segment, at most 160; or @name/sub/file inside an outside folder you allowed in the option rureFolders (ADR-499)' },label: { test: text => (/^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$/.test(text.trim()) ? text.trim() : null), rule: 'a label: letters, digits . _ -, at most 40, not starting with . or -' },url: { test: urlOf, rule: 'an http(s) URL with no spaces or quotes, at most 300' },target: { test: text => (/^@e\d{1,5}$/.test(text.trim()) ? text.trim() : null), rule: 'an element ref from a snapshot: @e1, @e12 β¦' },diff --git a/plugins/ruflo-console/hooks/data/rure-folders.ts b/plugins/ruflo-console/hooks/data/rure-folders.tsnew file mode 100644index 0000000000..fc80577b0b--- /dev/null+++ b/plugins/ruflo-console/hooks/data/rure-folders.ts@@ -0,0 +1,109 @@+/**+ * Folders outside the project that ruRE may read (ADR-499). The person names them in the plugin option `rureFolders` as+ * `name=/absolute/folder` pairs; a ruRE sample then reaches one as `@name` or `@name/sub/file`. Nothing else outside the project can be named:+ * not an absolute path, not `..`, and Claude cannot define a folder on its own (a plugin option change is install-class: Claude's console tools can only+ * propose it at the full control level, and it always waits for the person's Yes, which shows the folders).+ * The sample stays a plain relative-looking token until the preflight resolves it, so the field rule needs no knowledge of the option.+ * Leaf: pure functions; the host's `stat` is passed in. Nothing here runs a command.+ */+import type { ReaderFs } from './files'++/** The folders as the option holds them: alias -> absolute folder, no trailing slash. A null-prototype object, so an alias can be called anything. */+export type Folders = Readonly<Record<string, string>>++const ALIAS = /^[A-Za-z0-9_-]{1,32}$/+/** A POSIX folder or a Windows one with forward slashes: plain characters only (no spaces, no `~`, no `$`, no `..`). */+const FOLDER = /^(?:\/|[A-Za-z]:\/)[A-Za-z0-9._/-]{1,198}$/+const MAX_FOLDERS = 16++const isLinkKind = (kind: string | undefined): boolean => kind === 'symlink' || kind === 'link'+const isDir = (kind: string | undefined): boolean => kind === 'dir' || kind === 'directory'++/** A folder that is every file (`/`, `C:/`) or a system root is not a choice a typo should reach. */+const tooBroad = (path: string): boolean => path.replace(/^[A-Za-z]:/, '').split('/').filter(part => part !== '').length < 2++/**+ * The option's text (`docs=/data/samples; bins=/opt/vendor/bin`) as folders. A pair that breaks any rule is dropped, never repaired: a folder the+ * person meant but mistyped is then unknown, which refuses, where a repaired one could name a place they did not mean.+ */+export function parseFolders(raw: unknown): Folders {+ const out: Record<string, string> = Object.create(null) as Record<string, string>++ if (typeof raw !== 'string' || raw.length > 4000) return out++ for (const pair of raw.split(/[;\n]/)) {+ const at = pair.indexOf('=')++ if (at < 1) continue++ const alias = pair.slice(0, at).trim()+ const folder = pair.slice(at + 1).trim().replaceAll('\\', '/').replace(/\/+$/, '')++ if (!ALIAS.test(alias) || !FOLDER.test(folder) || tooBroad(folder)) continue+ if (folder.split('/').some(part => part === '..' || part === '.')) continue+ if (alias in out || Object.keys(out).length >= MAX_FOLDERS) continue++ out[alias] = folder+ }++ return out+}++/** A sample that names an allowed folder starts with `@`. */+export const isAliased = (sample: string): boolean => sample.startsWith('@')++/** The text rule for the part after `@`: `name` or `name/rel/path`, plain characters, no `..`, no empty part. */+export const aliasSampleOf = (text: string): string | null => {+ const value = text.trim()+ const match = /^@([A-Za-z0-9_-]{1,32})((?:\/[A-Za-z0-9._-]{1,100}){0,12})$/.exec(value)++ if (match === null || value.length > 160) return null++ return match[2]!.split('/').every(part => part !== '..' && part !== '.') ? value : null+}++/** What an aliased sample means: the allowed folder, the part below it, and the absolute path of both. Or why it means nothing. */+export function resolveAlias(sample: string, folders: Folders): { alias: string; root: string; rel: string; path: string } | { refuse: string } {+ const match = /^@([A-Za-z0-9_-]+)(\/.*)?$/.exec(sample)++ if (match === null) return { refuse: `${sample} is not a folder name this page knows` }++ const alias = match[1]!+ const root = folders[alias]++ if (root === undefined) {+ const known = Object.keys(folders)++ return { refuse: known.length === 0 ? `@${alias}: no outside folder is allowed. You can allow one in the ruflo-console option rureFolders (name=/folder); changing it always asks you first.` : `@${alias} is not one of your allowed folders (${known.map(name => `@${name}`).join(', ')})` }+ }++ const rel = (match[2] ?? '').replace(/^\/+/, '')++ return { alias, root, rel, path: rel === '' ? root : `${root}/${rel}` }+}++/**+ * `null` when the folder and everything below it down to the sample are real (not links), or the reason. The folder itself must be a folder and+ * not a link: a link there could lead anywhere the person never looked. A part that is not there is fine (the tool says "not found" itself);+ * a host that cannot stat answers like a missing part, so the check narrows what runs and never widens it.+ */+export async function foldersLinkCheck(fs: Pick<ReaderFs, 'stat'>, root: string, rel: string): Promise<string | null> {+ const top = await fs.stat(root).catch(() => undefined)++ if (top === undefined) return `${root} is not there: check the folder in rureFolders`+ if (top.isLink === true || isLinkKind(top.kind)) return `${root} is a link: name the real folder in rureFolders, because ruRE does not follow links`+ if (!isDir(top.kind)) return `${root} is not a folder`++ let at = root++ for (const part of rel.split('/').filter(piece => piece !== '')) {+ at = `${at}/${part}`++ const stat = await fs.stat(at).catch(() => undefined)++ if (stat === undefined) return null+ if (stat.isLink === true || isLinkKind(stat.kind)) return `${at} is a link: it could lead out of the allowed folder, so ruRE does not follow it`+ }++ return null+}diff --git a/plugins/ruflo-console/hooks/devtools.ts b/plugins/ruflo-console/hooks/devtools.tsindex 4f53bdc166..89852029ea 100644--- a/plugins/ruflo-console/hooks/devtools.ts+++ b/plugins/ruflo-console/hooks/devtools.ts@@ -195,7 +195,7 @@ export function devSpec(entry: DevEntry, fields: DevFields): ActionSpec | null {...(DECLARED[entry.cost] !== undefined && { declared: DECLARED[entry.cost] }),...(entry.note !== undefined && { note: entry.note }),...(entry.timeoutMs !== undefined && { timeoutMs: entry.timeoutMs }),- ...(entry.group.startsWith('rure-') && fields.sample !== '' && { preflight: rurePreflight(entry, fields.sample) }),+ ...(entry.group.startsWith('rure-') && fields.sample !== '' && { preflight: rurePreflight(entry, fields.sample, args) }),}}diff --git a/plugins/ruflo-console/hooks/help-topics-more.ts b/plugins/ruflo-console/hooks/help-topics-more.tsindex 33eb2df61e..8abb14fa08 100644--- a/plugins/ruflo-console/hooks/help-topics-more.ts+++ b/plugins/ruflo-console/hooks/help-topics-more.ts@@ -253,7 +253,7 @@ export const MORE_TOPICS: readonly HelpTopic[] = [group: 'Console',summary: 'static reverse engineering of a file in your project: what it imports, exposes and carries',steps: [- { text: 'Open ruRE (TOOLS group, or /ruflo rure). Type the path of a file or folder inside this project in the sample field; the page cannot reach anything outside the project.', go: { view: 'rure' } },+ { text: 'Open ruRE (TOOLS group, or /ruflo rure). Type the path of a file or folder inside this project in the sample field; the page cannot reach anything outside the project except a folder you allowed in the option rureFolders, named @name/file (allowing one always asks you first).', go: { view: 'rure' } },{ text: 'Unsure which row fits? DETECT picks: a folder is JavaScript source, .cubin, .fatbin or .ptx is CUDA, .hex or .evm is EVM bytecode, anything else a native binary. It never unpacks an .asar (it names UNPACK .ASAR, which asks first); a .dll or .exe may be .NET.' },{ text: 'Or pick the row yourself: APP MAP and FIND FEATURE for JavaScript or Electron source, UNPACK .ASAR for a packed app, NATIVE BINARY for ELF, PE or Mach-O, .NET ASSEMBLY for managed code, CUDA for GPU code, EVM BYTECODE for a contract. A read runs at once and shows below.' },{ text: 'UNPACK .ASAR asks first: it writes the files to a temp folder outside the project. Copy that folder under the project (cp -r) to run APP MAP or FIND FEATURE on it here.' },diff --git a/plugins/ruflo-console/hooks/runner.ts b/plugins/ruflo-console/hooks/runner.tsindex a8da837904..f338c6a31d 100644--- a/plugins/ruflo-console/hooks/runner.ts+++ b/plugins/ruflo-console/hooks/runner.ts@@ -117,7 +117,7 @@ export function createRunner(state: State, host: Host, deps: RunnerDeps): Runnerhost.invalidate()try {- const prep = await spec.preflight?.(host)+ const prep = await spec.preflight?.(host, state.options)if (typeof prep === 'string') {if (spec.lab !== undefined) panel.result = { id: spec.lab, label: spec.label, ok: false, exitCode: null, lines: [prep], atMs: Date.now() }say(spec.label, false, prep)diff --git a/plugins/ruflo-console/hooks/rure.ts b/plugins/ruflo-console/hooks/rure.tsindex e1b46c5a5d..05abee2ff4 100644--- a/plugins/ruflo-console/hooks/rure.ts+++ b/plugins/ruflo-console/hooks/rure.ts@@ -9,6 +9,8 @@import { devLines, need, tool } from './data/devtools'import { detectReader } from './data/rure-detect'import { sampleLinkCheck } from './data/rure-guard'+import { foldersLinkCheck, isAliased, resolveAlias, type Folders } from './data/rure-folders'+import type { Host } from './host'import type { ActionSpec } from './actions'import type { DevEntry } from './devtools'@@ -34,7 +36,9 @@ export const RURE: readonly DevEntry[] = [* What runs before a ruRE row (ADR-495, ADR-496): the sample must not be, or sit behind, a link; and DETECT then picks the reader from* what the host says about the sample, so the row runs that reader's call with that reader's lines, or says why it cannot choose.*/-export const rurePreflight = (entry: DevEntry, sample: string): NonNullable<ActionSpec['preflight']> => async host => {+export const rurePreflight = (entry: DevEntry, sample: string, built: readonly string[] | null): NonNullable<ActionSpec['preflight']> => async (host, options) => {+ if (isAliased(sample)) return aliasedPreflight(entry, sample, built, host, options.rureFolders)+const linked = await sampleLinkCheck(host.fs, sample)if (linked !== null) return linked@@ -46,3 +50,32 @@ export const rurePreflight = (entry: DevEntry, sample: string): NonNullable<Actireturn { args: tool(pick.tool, pick.params), label: `ruRE: detect β ${RURE.find(row => row.id === pick.id)?.name ?? pick.id}`, lab: pick.id, note: pick.why, lines: (out, err) => devLines(pick.id, out, err) }}++/**+ * A sample in an allowed outside folder (ADR-499): `@name/sub/file` becomes the folder's absolute path, after the links on the way are checked.+ * The row's own argv carries the `@name` text (so nothing absolute was ever built from a field); the resolved path replaces it in the one JSON+ * argument every ruRE call has. DETECT picks its reader from what the host says about the resolved path.+ */+async function aliasedPreflight(entry: DevEntry, sample: string, built: readonly string[] | null, host: Pick<Host, 'fs'>, folders: Folders): ReturnType<NonNullable<ActionSpec['preflight']>> {+ const at = resolveAlias(sample, folders)++ if ('refuse' in at) return at.refuse++ const linked = await foldersLinkCheck(host.fs, at.root, at.rel)++ if (linked !== null) return linked+ if (entry.id === 'dt-re-auto') {+ const pick = await detectReader(host.fs, at.path)++ if ('refuse' in pick) return pick.refuse++ return { args: tool(pick.tool, pick.params), label: `ruRE: detect β ${RURE.find(row => row.id === pick.id)?.name ?? pick.id}`, lab: pick.id, note: `${pick.why} (in @${at.alias})`, lines: (out, err) => devLines(pick.id, out, err) }+ }++ const slot = built === null ? -1 : built.indexOf('-p')+ const params: unknown = slot < 0 ? null : JSON.parse(built![slot + 1] ?? 'null')++ if (built === null || typeof params !== 'object' || params === null || (params as { path?: unknown }).path !== sample) return `${entry.name}: could not place ${sample}`++ return { args: built.map((part, index) => (index === slot + 1 ? JSON.stringify({ ...params, path: at.path }) : part)), note: `${entry.note ?? ''}${entry.note === undefined ? '' : '; '}reads ${at.path} (@${at.alias})` }+}diff --git a/plugins/ruflo-console/hooks/state.ts b/plugins/ruflo-console/hooks/state.tsindex c6704055d2..239c650d72 100644--- a/plugins/ruflo-console/hooks/state.ts+++ b/plugins/ruflo-console/hooks/state.ts@@ -2,6 +2,7 @@ import type { PluginOptions, Timer } from 'claude-code'import { isWindowsPath, trimTrailing } from './data/paths'import { guardOptionsOf, type GuardOptions } from './data/wf-alerts'import { sessionOptionsOf, type SessionOptions } from './data/sessions-options'+import { parseFolders, type Folders } from './data/rure-folders'import { convoOptionsOf, type ConvoOptions } from './data/wf-targets'import { emptyAuto, type AutoState } from './data/automate'@@ -133,6 +134,8 @@ export type Options = GuardOptions & ConvoOptions & SessionOptions & {boot: boolean/** ADR-474: keep the Events and Timeline history in `.claude-flow/console/` (events.jsonl, lanes.jsonl). On by default; masked text only. */eventsPersist: boolean+ /** ADR-499: outside folders ruRE may read, alias -> absolute folder. Set only by the person (a plugin option); empty by default. */+ rureFolders: Folders}const num = (value: unknown, fallback: number, lo: number, hi: number): number => {@@ -155,6 +158,7 @@ export function optionsOf(raw: PluginOptions | undefined): Options {look: value.look === 'plain' || value.look === 'orbital' ? value.look : 'bbs',boot: value.boot !== false,eventsPersist: value.eventsPersist !== false && value.eventsPersist !== 'false',+ rureFolders: parseFolders(value.rureFolders),...guardOptionsOf(raw),...convoOptionsOf(raw),...sessionOptionsOf(raw),diff --git a/plugins/ruflo-console/hooks/version.ts b/plugins/ruflo-console/hooks/version.tsindex 09c151b1f0..1bf1407aa9 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.47.0'+export const CONSOLE_VERSION = '0.48.0'diff --git a/plugins/ruflo-console/scripts/smoke.sh b/plugins/ruflo-console/scripts/smoke.shindex 282c79b47a..9873fb7ad2 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.47.0"+step "1. plugin.json declares ruflo-console 0.48.0"grep -q '"name": "ruflo-console"' "$ROOT/.claude-plugin/plugin.json" \- && grep -q '"version": "0.47.0"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"+ && grep -q '"version": "0.48.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/rure-folders-e2e.spec.ts b/plugins/ruflo-console/tests/rure-folders-e2e.spec.tsnew file mode 100644index 0000000000..c135b5f287--- /dev/null+++ b/plugins/ruflo-console/tests/rure-folders-e2e.spec.ts@@ -0,0 +1,106 @@+/**+ * Outside folders for ruRE, end to end (ADR-499): a real folder outside a real project, the row's own preflight with a node-fs `stat` on+ * absolute paths, then the argv it chose through the REAL built ruflo CLI and the console's reader. Skips, saying so, without a CLI that has the tools.+ * npx vitest run --dir plugins/ruflo-console/tests rure-folders-e2e+ */+import { spawnSync } from 'node:child_process'+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'+import { tmpdir } from 'node:os'+import { join, resolve } from 'node:path'+import { afterAll, beforeAll, describe, expect, it } from 'vitest'++import { emptyFields } from '../hooks/data/devtools'+import { parseFolders } from '../hooks/data/rure-folders'+import { DEV, devSpec } from '../hooks/devtools'+import type { Host } from '../hooks/host'+import { buildElf64 } from '../../../v3/@claude-flow/cli/__tests__/rure-binary-fixtures'++const CLI_DIR = resolve(__dirname, '../../../v3/@claude-flow/cli')+const CLI = join(CLI_DIR, 'bin', 'cli.js')+const TOOLS = join(CLI_DIR, 'dist', 'src', 'mcp-tools', 'rure-tools.js')+const CUDA_HOST = join(CLI_DIR, '__tests__', 'fixtures', 'cuda', 'host-cubinonly')+const HAVE_CLI = existsSync(CLI) && existsSync(TOOLS) && existsSync(CUDA_HOST) && readFileSync(TOOLS, 'utf8').includes('rure_analyze_cuda')++if (!HAVE_CLI) console.log('SKIP ruRE outside-folder e2e: build the CLI first (cd v3 && pnpm -r build)')++let project = ''+let outside = ''++/** A `stat` the way the host answers it, on the absolute path the preflight asks for. */+const fs = {+ stat: async (path: string) => {+ try {+ const info = lstatSync(path)++ return { kind: info.isDirectory() ? 'dir' : 'file', isLink: info.isSymbolicLink(), size: info.size }+ } catch {+ return undefined+ }+ },+}++/** The row as the console runs it: preflight resolves the alias, then the chosen argv runs in the project and the row's reader reads it. */+async function run(id: string, sample: string, folderOption: string): Promise<{ refused?: string; label?: string; note?: string; lines?: string[]; argv?: string[] }> {+ const spec = devSpec(DEV.find(item => item.id === id)!, { ...emptyFields(), sample })!+ const prep = await spec.preflight!({ fs } as unknown as Host, { rureFolders: parseFolders(folderOption) })++ if (typeof prep === 'string') return { refused: prep }++ const chosen = { ...spec, ...(prep ?? {}) }+ const done = spawnSync(process.execPath, [CLI, ...chosen.args], { cwd: project, encoding: 'utf8', timeout: 90_000, env: { ...process.env, NO_COLOR: '1' } })++ return { label: chosen.label, note: chosen.note, argv: [...chosen.args], lines: chosen.lines?.(done.stdout ?? '', done.stderr ?? '') ?? [] }+}++beforeAll(() => {+ if (!HAVE_CLI) return++ project = mkdtempSync(join(tmpdir(), 'ruflo-folders-e2e-project-'))+ outside = mkdtempSync(join(tmpdir(), 'ruflo-folders-e2e-outside-'))+ mkdirSync(join(outside, 'bin'))+ writeFileSync(join(outside, 'bin', 'tool'), buildElf64())+ copyFileSync(CUDA_HOST, join(outside, 'gpu-host'))+ symlinkSync('/etc/hostname', join(outside, 'bin', 'escape'))+})++afterAll(() => {+ for (const dir of [project, outside]) if (dir !== '') rmSync(dir, { recursive: true, force: true })+})++describe.skipIf(!HAVE_CLI)('ruRE reads a folder outside the project that the person allowed', () => {+ it('reads a native binary there through the real CLI', async () => {+ const out = await run('dt-re-bin', '@lab/bin/tool', `lab=${outside}`)++ expect(out.refused).toBeUndefined()+ expect(JSON.parse(out.argv![out.argv!.indexOf('-p') + 1]!).path).toBe(`${outside}/bin/tool`)+ expect(out.lines!.join('\n')).toMatch(/ELF/i)+ })++ it('DETECT reads a CUDA host binary there with the native reader and hints at the CUDA row', async () => {+ const out = await run('dt-re-auto', '@lab/gpu-host', `lab=${outside}`)++ expect(out.refused).toBeUndefined()+ expect(out.note).toContain('(in @lab)')+ expect(out.lines!.join('\n')).toMatch(/CUDA/i)+ })++ it('refuses a link inside the allowed folder that leads out, and nothing is read', async () => {+ const out = await run('dt-re-bin', '@lab/bin/escape', `lab=${outside}`)++ expect(out.refused).toMatch(/escape is a link/)+ })++ it('refuses a name that was never allowed, and an allowed folder that is itself a link', async () => {+ expect((await run('dt-re-bin', '@lab/bin/tool', '')).refused).toMatch(/no outside folder is allowed/)+ expect((await run('dt-re-bin', '@other/bin/tool', `lab=${outside}`)).refused).toMatch(/@other is not one of your allowed folders/)++ const door = join(project, 'door')++ symlinkSync(outside, door)+ expect((await run('dt-re-bin', '@d/bin/tool', `d=${door}`)).refused).toMatch(/door is a link/)+ })++ it('an absolute path typed as a sample reaches nothing, with the option set or not', () => {+ for (const sample of [`${outside}/bin/tool`, `${outside}/../x`, '/etc/hostname']) expect(devSpec(DEV.find(item => item.id === 'dt-re-bin')!, { ...emptyFields(), sample })).toBeNull()+ })+})diff --git a/plugins/ruflo-console/tests/rure-folders.spec.ts b/plugins/ruflo-console/tests/rure-folders.spec.tsnew file mode 100644index 0000000000..a9899ad249--- /dev/null+++ b/plugins/ruflo-console/tests/rure-folders.spec.ts@@ -0,0 +1,246 @@+/**+ * Outside folders for ruRE (ADR-499): the person names a folder in the option `rureFolders`; a sample reaches it as `@name/sub/file`.+ * Nothing else outside the project can be named, and a link is never followed.+ * npx vitest run --dir plugins/ruflo-console/tests rure-folders+ */+import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'+import { tmpdir } from 'node:os'+import { join } from 'node:path'+import { describe, expect, it, vi } from 'vitest'++import { DEV, devSpec } from '../hooks/devtools'+import { allows, ALWAYS_ASK, classOf, TOOL_SPECS } from '../hooks/model-tools'+import { parseConfig, setOption, settingsOf } from '../hooks/settings'+import { emptyFields, fieldValue } from '../hooks/data/devtools'+import { aliasSampleOf, foldersLinkCheck, parseFolders, resolveAlias } from '../hooks/data/rure-folders'+import type { Host } from '../hooks/host'+import { createRunner } from '../hooks/runner'+import { newState, optionsOf } from '../hooks/state'++type Entry = { isLink?: boolean; kind?: string } | undefined+const fsOf = (entries: Record<string, Entry>) => ({ stat: async (path: string) => entries[path] })+const entry = (id: string) => DEV.find(item => item.id === id)!+const folders = parseFolders('samples=/data/samples; vendor=/opt/vendor/bin')++describe('parseFolders', () => {+ it('reads name=/folder pairs, separated by ; or a new line, and drops a trailing slash', () => {+ expect(parseFolders('a=/data/x/;\nb=/opt/y')).toEqual({ a: '/data/x', b: '/opt/y' })+ expect(parseFolders('win=C:/Users/me/samples')).toEqual({ win: 'C:/Users/me/samples' })+ expect(parseFolders('win=C:\\Users\\me\\samples')).toEqual({ win: 'C:/Users/me/samples' })+ })++ it('drops, never repairs, a pair that breaks a rule', () => {+ const bad = ['a=relative/dir', 'a=/', 'a=/home', 'a=C:/', 'a=/data/../etc', 'a=/data/./x', 'a=/data/my files', 'a=~/x', 'a=/data/$HOME/x', 'a=/data/x|rm', 'a=/data/`id`', '=/data/x', 'bad name=/data/x', `a=/${'x'.repeat(220)}/y`, 'a', 'a=']++ for (const raw of bad) expect(Object.keys(parseFolders(raw)), raw).toEqual([])+ })++ it('keeps the first of a repeated name, caps the count, and answers {} to a non-string', () => {+ expect(parseFolders('a=/d/one; a=/d/two')).toEqual({ a: '/d/one' })+ expect(Object.keys(parseFolders(Array.from({ length: 40 }, (_, i) => `n${i}=/d/f${i}`).join(';')))).toHaveLength(16)+ for (const value of [undefined, null, 5, {}, ['a=/d/x']]) expect(Object.keys(parseFolders(value))).toEqual([])+ })++ it('an alias called __proto__ or constructor is a plain name, not a hole in the object', () => {+ const map = parseFolders('__proto__=/d/x; constructor=/d/y')++ expect(Object.getPrototypeOf(map)).toBeNull()+ expect(Object.keys(map).sort()).toEqual(['__proto__', 'constructor'])+ expect(resolveAlias('@toString', map)).toHaveProperty('refuse')+ })++ it('is what the console option holds', () => {+ expect(optionsOf({ rureFolders: 'x=/data/x' } as never).rureFolders).toEqual({ x: '/data/x' })+ expect(optionsOf({} as never).rureFolders).toEqual({})+ })+})++describe('the sample rule', () => {+ it('accepts @name and @name/rel/path, and still only a plain relative path otherwise', () => {+ for (const ok of ['@samples', '@samples/app', '@samples/a/b/c.dll', 'bin/tool']) expect(fieldValue('sample', ok), ok).toBe(ok)+ })++ it('refuses an absolute path, .., an empty part, @ alone, odd characters and a long name', () => {+ for (const bad of ['/data/samples/x', 'C:/x', '@', '@/x', '@a/../b', '@a//b', '@a/./b', '@a b/c', '@a/b c', '@a;b', '@a/$(x)', `@${'a'.repeat(33)}`, `@a/${'b'.repeat(101)}`, '@a/' + Array(14).fill('p').join('/')]) {+ expect(aliasSampleOf(bad), bad).toBeNull()+ expect(fieldValue('sample', bad), bad).toBeNull()+ }+ })+})++describe('resolveAlias', () => {+ it('resolves a name and the part below it', () => {+ expect(resolveAlias('@samples', folders)).toEqual({ alias: 'samples', root: '/data/samples', rel: '', path: '/data/samples' })+ expect(resolveAlias('@samples/app/tool.exe', folders)).toEqual({ alias: 'samples', root: '/data/samples', rel: 'app/tool.exe', path: '/data/samples/app/tool.exe' })+ })++ it('refuses an unknown name and says how to allow one, and with none allowed says that Claude cannot', () => {+ expect(resolveAlias('@nope/x', folders)).toMatchObject({ refuse: expect.stringContaining('@samples, @vendor') })+ expect(resolveAlias('@nope', parseFolders(''))).toMatchObject({ refuse: expect.stringMatching(/rureFolders.*asks you first/) })+ })+})++describe('foldersLinkCheck', () => {+ const dir = { kind: 'dir' }++ it('lets a real folder and real parts through, and a part that is not there (the tool says so)', async () => {+ expect(await foldersLinkCheck(fsOf({ '/d/s': dir, '/d/s/a': dir, '/d/s/a/b': { kind: 'file' } }), '/d/s', 'a/b')).toBeNull()+ expect(await foldersLinkCheck(fsOf({ '/d/s': dir }), '/d/s', 'a/missing')).toBeNull()+ })++ it('refuses a folder that is missing, not a folder, or a link', async () => {+ expect(await foldersLinkCheck(fsOf({}), '/d/s', '')).toMatch(/is not there/)+ expect(await foldersLinkCheck(fsOf({ '/d/s': { kind: 'file' } }), '/d/s', '')).toMatch(/is not a folder/)+ expect(await foldersLinkCheck(fsOf({ '/d/s': { isLink: true, kind: 'dir' } }), '/d/s', '')).toMatch(/\/d\/s is a link/)+ expect(await foldersLinkCheck(fsOf({ '/d/s': { kind: 'symlink' } }), '/d/s', '')).toMatch(/is a link/)+ })++ it('refuses a link anywhere below the folder', async () => {+ expect(await foldersLinkCheck(fsOf({ '/d/s': dir, '/d/s/a': { isLink: true } }), '/d/s', 'a/b')).toMatch(/\/d\/s\/a is a link/)+ expect(await foldersLinkCheck(fsOf({ '/d/s': dir, '/d/s/a': dir, '/d/s/a/b': { kind: 'link' } }), '/d/s', 'a/b')).toMatch(/\/d\/s\/a\/b is a link/)+ })++ it('a host that refuses stat on the folder answers like a missing folder: it refuses, it never widens', async () => {+ expect(await foldersLinkCheck({ stat: async () => Promise.reject(new Error('refused')) }, '/d/s', 'a')).toMatch(/is not there/)+ })+})++describe('the preflight of a ruRE row', () => {+ const sample = '@samples/app/tool.exe'+ const spec = (id: string, over: Record<string, string> = {}) => devSpec(entry(id), { ...emptyFields(), sample, query: 'license', ...over })!+ const hostOf = (entries: Record<string, Entry>) => ({ fs: fsOf(entries) }) as unknown as Host+ const real = { '/data/samples': { kind: 'dir' }, '/data/samples/app': { kind: 'dir' }, '/data/samples/app/tool.exe': { kind: 'file' } } as const++ it('every reader row swaps @name for the absolute path in its one JSON argument, and keeps the rest', async () => {+ for (const id of ['dt-re-bin', 'dt-re-net', 'dt-re-cuda', 'dt-re-evm', 'dt-re-js', 'dt-re-asar', 'dt-re-find']) {+ const built = spec(id)+ const out = await built.preflight!(hostOf(real), { rureFolders: folders })++ expect(built.args.join(' '), id).toContain('@samples/app/tool.exe')+ expect(out, id).toMatchObject({ args: expect.any(Array) })++ const args = (out as { args: string[] }).args+ const params = JSON.parse(args[args.indexOf('-p') + 1]!) as Record<string, unknown>++ expect(params.path, id).toBe('/data/samples/app/tool.exe')+ expect(args.slice(0, args.indexOf('-p')), id).toEqual(built.args.slice(0, built.args.indexOf('-p')))+ if (id === 'dt-re-find') expect(params.query).toBe('license')+ if (id === 'dt-re-bin') expect(params.includeStrings).toBe(true)+ }+ })++ it('DETECT picks its reader from the resolved path', async () => {+ const out = await spec('dt-re-auto', { sample: '@samples/k.cubin' }).preflight!(hostOf({ '/data/samples': { kind: 'dir' }, '/data/samples/k.cubin': { kind: 'file' } }), { rureFolders: folders })++ expect(out).toMatchObject({ lab: 'dt-re-cuda', note: expect.stringContaining('in @samples') })+ expect(JSON.parse((out as { args: string[] }).args.at(-1)!)).toMatchObject({ path: '/data/samples/k.cubin' })+ })++ it('refuses an unknown name, a linked folder and a link below it, and runs nothing', async () => {+ expect(await spec('dt-re-bin', { sample: '@other/x' }).preflight!(hostOf(real), { rureFolders: folders })).toMatch(/@other is not one of your allowed folders/)+ expect(await spec('dt-re-bin').preflight!(hostOf({ ...real, '/data/samples': { isLink: true, kind: 'dir' } }), { rureFolders: folders })).toMatch(/\/data\/samples is a link/)+ expect(await spec('dt-re-bin').preflight!(hostOf({ ...real, '/data/samples/app': { isLink: true } }), { rureFolders: folders })).toMatch(/\/data\/samples\/app is a link/)+ })++ it('with no folder allowed, an @name sample is refused, and a project path is unchanged', async () => {+ expect(await spec('dt-re-bin').preflight!(hostOf(real), { rureFolders: parseFolders('') })).toMatch(/no outside folder is allowed/)+ expect(await spec('dt-re-bin', { sample: 'bin/tool' }).preflight!(hostOf({ bin: { kind: 'dir' }, 'bin/tool': { kind: 'file' } }), { rureFolders: folders })).toBeNull()+ })+})++describe('the runner', () => {+ const runnerFor = (folderText: string, entries: Record<string, Entry>) => {+ const run = vi.fn(async () => ({ stdout: '{"success":true}', stderr: '', exitCode: 0 }))+ const host = { invalidate: () => undefined, after: () => ({ cancel: () => undefined }), run, fs: fsOf(entries) } as unknown as Host+ const state = newState({ rureFolders: folderText } as never)+ const runner = createRunner(state, host, { freshRead: async () => undefined, setView: () => undefined, drill: () => undefined, command: () => undefined })++ return { run, state, runner }+ }+ const settle = async (): Promise<void> => { for (let turn = 0; turn < 12; turn++) await new Promise<void>(resolve => setTimeout(resolve, 0)) }++ it('runs the tool with the absolute path when the person allowed the folder', async () => {+ const { run, runner } = runnerFor('samples=/data/samples', { '/data/samples': { kind: 'dir' }, '/data/samples/tool': { kind: 'file' } })++ runner.ask(devSpec(entry('dt-re-bin'), { ...emptyFields(), sample: '@samples/tool' })!, 'why')+ await settle()++ expect(run).toHaveBeenCalledTimes(1)++ const argv = (run.mock.calls[0] as unknown as [string[]])[0]++ expect(JSON.parse(argv[argv.indexOf('-p') + 1]!)).toEqual({ path: '/data/samples/tool', includeStrings: true })+ })++ it('spawns nothing and shows the reason when the folder was never allowed', async () => {+ const { run, state, runner } = runnerFor('', { '/data/samples': { kind: 'dir' } })++ runner.ask(devSpec(entry('dt-re-bin'), { ...emptyFields(), sample: '@samples/tool' })!, 'why')+ await settle()++ expect(run).not.toHaveBeenCalled()+ expect(state.lab.result?.ok).toBe(false)+ expect(state.lab.result?.lines.join(' ')).toMatch(/no outside folder is allowed/)+ })+})++describe('on a real disk', () => {+ it('a symlink inside the allowed folder that points out is refused, a plain file is not', async () => {+ const base = mkdtempSync(join(tmpdir(), 'rure-folders-'))++ try {+ const root = join(base, 'allowed')+ const outside = join(base, 'secret')++ mkdirSync(root)+ mkdirSync(outside)+ writeFileSync(join(root, 'plain.bin'), 'x')+ writeFileSync(join(outside, 'key'), 'y')+ symlinkSync(outside, join(root, 'door'))++ const { lstat } = await import('node:fs/promises')+ const fs = { stat: async (path: string) => lstat(path).then(s => ({ kind: s.isDirectory() ? 'dir' : s.isFile() ? 'file' : 'other', isLink: s.isSymbolicLink() })).catch(() => undefined) }++ expect(await foldersLinkCheck(fs, root, 'plain.bin')).toBeNull()+ expect(await foldersLinkCheck(fs, root, 'door/key')).toMatch(/door is a link/)+ expect(await foldersLinkCheck(fs, join(base, 'allowed', 'door'), 'key')).toMatch(/is a link/)+ } finally {+ rmSync(base, { recursive: true, force: true })+ }+ })+})++describe('who can allow a folder', () => {+ const CONSOLE = JSON.stringify({+ pluginId: 'ruflo-console@ruflo',+ schema: { rureFolders: { type: 'string', title: 'Outside folders ruRE may read', description: 'name=/folder pairs', default: '' } },+ inputs: { rureFolders: '' },+ choices: {},+ configured: [],+ })++ it('is an install-class option write: Claude can only propose it at the full level, and it always asks the person', () => {+ const state = newState({})+ const config = parseConfig('ruflo-console', CONSOLE)++ expect(config).not.toBeNull()+ settingsOf(state).configs.set('ruflo-console', config!)++ const spec = setOption(state, 'ruflo-console', 'rureFolders', 'lab=/data/samples', () => undefined)++ expect(spec?.argv).toEqual(['claude', 'plugin', 'configure', 'ruflo-console@ruflo', '--values-stdin'])+ expect(spec?.stdin).toBe('{"rureFolders":"lab=/data/samples"}')+ expect(spec?.label).toContain('lab=/data/samples') // the card shows the exact folders+ expect(classOf(spec as NonNullable<typeof spec>)).toBe('install')+ expect(allows('write', 'install')).toBe(false)+ expect(allows('full', 'install')).toBe(true)+ expect(ALWAYS_ASK).toContain('install')+ })++ it('Claude has no console_set field that fills the sample or the option', () => {+ const set = TOOL_SPECS.find(tool => tool.name === 'console_set')++ expect(set).toBeDefined()+ expect(set!.description).not.toMatch(/sample|rureFolders/)+ })+})diff --git a/v3/docs/adr/ADR-499-rure-outside-folders.md b/v3/docs/adr/ADR-499-rure-outside-folders.mdnew file mode 100644index 0000000000..d09888f274--- /dev/null+++ b/v3/docs/adr/ADR-499-rure-outside-folders.md@@ -0,0 +1,32 @@+# ADR 499: ruRE in the console can read a folder outside the project that you allow++Status: Accepted (built and tested, including against the real CLI; ships in ruflo-console 0.48.0)++Date: 2026-10-24++Builds on: ADR-494 (the ruRE page), ADR-495 (the sample link check), ADR-496 (DETECT), ADR-497 (CUDA row). Settings model: ADR-450.++## 1. Context++The ruRE page analyzes only what is inside the project: the `sample` field takes a relative path with no `..`. A person who wants to look at a binary that lives elsewhere (a vendor drop, a download folder, a samples disk) had to copy it into the project first. The tools themselves read any path the process can read, so the limit is this page's. Loosening it must not let a typo, a link, or Claude's tool calls widen what is reachable.++## 2. Decision++- **A named allowlist, set by the person.** New plugin option `rureFolders`: `name=/absolute/folder` pairs separated by `;` or new lines. Each pair is checked whole and dropped, never repaired, if it breaks a rule: the name is 1-32 letters, digits, `_`, `-`; the folder is absolute (POSIX, or a drive with forward slashes), plain characters only (no spaces, `~`, `$`, `..`), at most 200, not a filesystem root or a single top-level folder (`/`, `/home`, `C:/`), at most 16 folders, first of a repeated name wins. The map has a null prototype, so `__proto__` is just a name.+- **A sample reaches a folder as `@name` or `@name/sub/file`.** The field rule gains exactly that shape and nothing else: an absolute path, `..`, an empty part, a long name or odd characters in a sample are refused as before. The rule stays pure: it knows nothing of the option.+- **The preflight resolves it.** `ActionSpec.preflight` now also receives the console's options (a same-line change in the runner, which sits at its 500-line cap). An `@name` unknown to the option is refused with the names that are allowed, or with how to allow one. Otherwise the folder itself must exist, be a folder and not be a link, and no part below it down to the sample may be a link (ADR-495's rule, rooted at the allowed folder). Then the resolved absolute path replaces the `@name` text in the one `-p` JSON argument every ruRE call carries; the rest of the row is unchanged. DETECT picks its reader from the resolved path and says `(in @name)`.+- **Who can allow a folder.** Changing a plugin option is the console's existing install-class write: `claude plugin configure β¦ --values-stdin` with a card that shows the exact folders and always waits for the person's Yes. Claude's console tools can only propose it at the full control level (ADR-450), and `console_set` has no field for the sample or the option. Claude can therefore reach an outside folder only through a name the person already defined, and only with the rows it already has (`console_run dt-re-bin @lab/tool`).++## 3. Limits, stated plainly++- **Reading is time-of-check.** The link check and the tool's read are separate steps; a path swapped for a link in between is not caught. The same was true of ADR-495 inside the project. The tools parse and never run what they read, which bounds the harm to disclosure of what the analysis prints.+- **An allowed folder is trusted as a whole.** Everything under it that is not a link can be analyzed, by the person or by Claude's rows. Choose folders that hold only what you are willing to show Claude.+- **Windows:** folders are given with forward slashes (`C:/Users/me/samples`); a backslash form is converted. Paths with spaces are not accepted.+- **Unpacking an `.asar`** still writes to a temp folder and asks first; that row works on an allowed folder like the others.+- The option takes effect after plugins reload (`/reload-plugins`), like every plugin option.++## 4. Verification++- `tests/rure-folders.spec.ts` (22): parsing (accepted forms, 17 refusals, repeated names, count cap, prototype names, non-strings), the field rule (accepts `@name/...`, refuses an absolute path, `..`, empty parts, over-long names), resolution, the link check (missing, not a folder, folder is a link, link below, a host that cannot stat), the preflight for all seven reader rows (argv equal except the `path` value, `query` and `includeStrings` kept), DETECT, the runner (runs with the absolute path when allowed; spawns nothing when not), a real disk with a real symlink, and the install-class contract for the option write.+- `tests/rure-folders-e2e.spec.ts` (5): a real folder outside a real project, the preflight with a node-fs `stat` on absolute paths, then the chosen argv through the built CLI: an ELF read there, DETECT on a CUDA host binary, a link out refused, an unknown name and a linked allowed folder refused, an absolute sample reaching nothing.+- Console suite 3529 passed; `scripts/smoke.sh` 20/20.