@neuralis/brain-core 0.3.2 → 0.4.0

package/dist/src/connectors/LocalDiskConnector.js

@@ -1,1233 +0,0 @@
-import fs from 'node:fs/promises';
-import { binaryMimeTypeForPath, inferMimeTypeFromFilename } from '../domain/mime.js';
-import { looksBinaryContent } from '../domain/text.js';
-import { existsSync } from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { createHash } from 'node:crypto';
-import { execFile } from 'node:child_process';
-import { resolveSearchBinaries } from '../search/binaryResolver.js';
-import { getInlineVideoCapBytes, getInlineImageCapBytes, getInlineAudioCapBytes, getInlinePdfCapBytes, getBrainConfigBoolean, getBrainConfigNumber, resolveWatchRecovery, } from '../config/env.js';
-import { CONNECTOR_PORT_VERSION } from '@neuralis/package-system/contracts';
-import { ConnectorRawReadTooLarge, ConnectorRootAccessError, } from '@neuralis/package-system/contracts';
-import { discoverOsMounts } from '@neuralis/package-system/paths';
-import { getFsWatchHub } from '@neuralis/package-system/data';
-import { compileGlobPatterns } from '../domain/syncignore.js';
-import { DEFAULT_MAX_SCAN_FILES } from '../domain/scanCap.js';
-// Hard read cap — `brainMaxReadFileMb` platform key (default 20 MB), read
-// LIVE per call. Larger files throw `File too large` for every read-path
-// consumer (Inc 5).
-const maxReadBytes = () => getBrainConfigNumber('brainMaxReadFileMb', undefined, 20) * 1024 * 1024;
-/** One `readRaw` syscall's buffer slice — bounds a single read, not the file. */
-const RAW_READ_CHUNK = 1024 * 1024;
-// Per-MIME inline caps for binary `bytes` emission (Sidequest §2.2). Above
-// these limits the connector returns a `[binary file too large…]` text marker
-// instead of base64 bytes — provider context windows + tool-result caps would
-// otherwise drown. ALL four MIME caps are LIVE platform settings now
-// (`inlineImageMaxMb` / `inlineAudioMaxMb` / `inlinePdfMaxMb` joined
-// `inlineVideoMaxMb` in Inc 5 — same env.ts cap-fn shape, media Inc 3′c
-// pattern). Audio default ~8 min of 128kbps mp3 (media-that-works Inc 7).
-// PDF text-extract cap — `brainPdfTextExcerptBytes` (default 200 KB), LIVE:
-// enough to brief the model without exploding context. Larger PDFs get
-// truncated with a tail marker.
-const pdfTextExcerptBytes = () => getBrainConfigNumber('brainPdfTextExcerptBytes', undefined, 200 * 1024);
-// First-page render output cap — `pdftoppm -r 100` on a typical page comes in
-// well under 4 MB. Opt-in via the `fsReadPdfRender` platform key (env
-// NEURALIS_FS_READ_PDF_RENDER fallback), read LIVE per call (Inc 4).
-const pdfRenderFirstPage = () => getBrainConfigBoolean('fsReadPdfRender', 'NEURALIS_FS_READ_PDF_RENDER', false);
-function formatBytes(n) {
-    if (!Number.isFinite(n) || n <= 0)
-        return '0 B';
-    if (n < 1024)
-        return `${n} B`;
-    if (n < 1024 * 1024)
-        return `${(n / 1024).toFixed(1)} KB`;
-    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
-}
-function inlineCapForMime(mimeType) {
-    if (mimeType === 'application/pdf')
-        return getInlinePdfCapBytes();
-    if (mimeType.startsWith('image/'))
-        return getInlineImageCapBytes();
-    if (mimeType.startsWith('video/'))
-        return getInlineVideoCapBytes();
-    if (mimeType.startsWith('audio/'))
-        return getInlineAudioCapBytes();
-    return null;
-}
-let pdftotextProbed = null;
-let pdftoppmProbed = null;
-/** PATH-only child env — never the host process.env (frameSample pattern):
- *  these are member-reachable spawns (`fs_read`/`fs_search`), and the app
- *  process env carries infra secrets (QDRANT_API_KEY et al.) that no helper
- *  child needs. */
-const CHILD_ENV = { PATH: process.env.PATH ?? '/usr/local/bin:/usr/bin:/bin' };
-async function whichBinary(name) {
-    return new Promise((resolve) => {
-        const child = execFile('which', [name], { env: CHILD_ENV }, (err, stdout) => {
-            if (err)
-                return resolve(false);
-            resolve(typeof stdout === 'string' && stdout.trim().length > 0);
-        });
-        child.on('error', () => resolve(false));
-    });
-}
-async function hasPdftotext() {
-    if (pdftotextProbed === null)
-        pdftotextProbed = await whichBinary('pdftotext');
-    return pdftotextProbed;
-}
-async function hasPdftoppm() {
-    if (pdftoppmProbed === null)
-        pdftoppmProbed = await whichBinary('pdftoppm');
-    return pdftoppmProbed;
-}
-async function pdftotextExcerpt(absPath) {
-    const excerptBytes = pdfTextExcerptBytes();
-    return new Promise((resolve) => {
-        const child = execFile('pdftotext', [absPath, '-'], { timeout: 10_000, maxBuffer: excerptBytes * 4, env: CHILD_ENV }, (err, stdout) => {
-            if (err)
-                return resolve(null);
-            const out = String(stdout ?? '');
-            const trimmed = out.length > excerptBytes
-                ? `${out.slice(0, excerptBytes)}\n\n…(pdftotext output truncated at ${excerptBytes} bytes)`
-                : out;
-            resolve(trimmed);
-        });
-        child.on('error', () => resolve(null));
-    });
-}
-/**
- * THE PDF→PNG renderer (`pdftoppm -r 100`): pages `first..last` of `absPath`
- * (clamped to the document), in page order. One private temp directory per call (`mkdtemp`), removed
- * afterwards — concurrent renders never read each other's output. A failed or
- * timed-out render answers `[]`. Two callers: `read` (the first page, opt-in
- * `fsReadPdfRender`) and the sync's media lane (`renderPdfPages`).
- */
-async function pdftoppmPages(absPath, first, last) {
-    const from = Math.max(1, Math.floor(first));
-    const to = Math.max(from, Math.floor(last));
-    let dir;
-    try {
-        dir = await fs.mkdtemp(path.join(os.tmpdir(), 'neuralis-pdfrender-'));
-    }
-    catch {
-        return [];
-    }
-    try {
-        const ok = await new Promise((resolve) => {
-            const child = execFile('pdftoppm', ['-f', String(from), '-l', String(to), '-r', '100', '-png', absPath, path.join(dir, 'page')], 
-            // 15 s per page, like the single-page render always had.
-            { timeout: 15_000 * (to - from + 1), env: CHILD_ENV }, (err) => resolve(!err));
-            child.on('error', () => resolve(false));
-        });
-        if (!ok)
-            return [];
-        // `page-1.png`, or zero-padded (`page-01.png`) once the document has ≥ 10 pages.
-        const files = (await fs.readdir(dir))
-            .map((name) => ({ name, page: Number(/-(\d+)\.png$/.exec(name)?.[1]) }))
-            .filter((f) => Number.isFinite(f.page))
-            .sort((a, b) => a.page - b.page);
-        const pages = [];
-        for (const f of files)
-            pages.push({ page: f.page, png: await fs.readFile(path.join(dir, f.name)) });
-        return pages;
-    }
-    catch {
-        return [];
-    }
-    finally {
-        await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
-    }
-}
-/**
- * Concrete root-access error thrown by the local-disk connector. Routes +
- * services catch the abstract base (`ConnectorRootAccessError`), not this
- * class specifically — so every future connector that touches a real FS
- * surface can share the same structured-warning pathway.
- */
-export class LocalDiskRootAccessError extends ConnectorRootAccessError {
-    constructor(code, rootPath, uri, cause) {
-        super(code, rootPath, uri, code === 'ROOT_MISSING'
-            ? `Local source root "${rootPath}" does not exist`
-            : `Local source root "${rootPath}" is not readable (permission denied)`, cause);
-        this.name = 'LocalDiskRootAccessError';
-    }
-}
-function isSkippableFsError(error) {
-    const code = error?.code;
-    return code === 'EACCES' || code === 'EPERM' || code === 'ENOENT';
-}
-function compileGlobMatchers(patterns) {
-    const compile = (value) => {
-        const escaped = value.replace(/[.+^${}()|[\]]/g, '\\$&');
-        const regex = escaped
-            .replace(/\*\*/g, '§§')
-            .replace(/\*/g, '[^/]*')
-            .replace(/§§/g, '.*')
-            .replace(/\?/g, '[^/]');
-        return new RegExp(`^${regex}$`);
-    };
-    const out = [];
-    for (const pat of patterns) {
-        const normalized = pat.replace(/\\/g, '/');
-        out.push(compile(normalized));
-        if (normalized.endsWith('/**')) {
-            out.push(compile(normalized.slice(0, -3)));
-        }
-    }
-    return out;
-}
-function matchesAny(relPath, matchers) {
-    const candidate = relPath.replace(/\\/g, '/');
-    for (const m of matchers) {
-        if (m.test(candidate))
-            return true;
-        const parts = candidate.split('/');
-        for (let i = 0; i < parts.length; i++) {
-            const sub = parts.slice(i).join('/');
-            if (m.test(sub))
-                return true;
-        }
-    }
-    return false;
-}
-const SCAN_TIMEOUT_MS = 30_000;
-const SCAN_MAX_BUFFER = 10 * 1024 * 1024;
-const COUNT_CACHE_TTL_MS = 60_000;
-function runBinary(bin, args, cwd, _maxMatches) {
-    // Live `brainScanTimeoutMs` (default SCAN_TIMEOUT_MS) — grep/rg kill timeout.
-    const scanTimeoutMs = getBrainConfigNumber('brainScanTimeoutMs', undefined, SCAN_TIMEOUT_MS);
-    return new Promise((resolve, reject) => {
-        execFile(bin, args, {
-            cwd,
-            timeout: scanTimeoutMs,
-            maxBuffer: SCAN_MAX_BUFFER,
-            env: CHILD_ENV,
-        }, (error, stdout, stderr) => {
-            const code = error && 'code' in error && typeof error.code === 'number' ? error.code : 0;
-            if (error && code !== 1 && code !== 0) {
-                const killed = 'killed' in error && error.killed;
-                if (killed)
-                    return reject(new Error(`Search timed out after ${scanTimeoutMs}ms`));
-                return reject(new Error(`Search binary failed (${bin}): ${String(stderr || error.message)}`));
-            }
-            resolve(String(stdout ?? ''));
-        });
-    });
-}
-function accessErrorCode(error) {
-    const code = error?.code;
-    if (code === 'ENOENT')
-        return 'ROOT_MISSING';
-    if (code === 'EACCES' || code === 'EPERM')
-        return 'ROOT_PERMISSION_DENIED';
-    return null;
-}
-async function resolveAndGuard(basePath, target, options) {
-    const normalizedTarget = path.isAbsolute(target) ? `.${target}` : target;
-    const normalizedBase = path.resolve(basePath);
-    const rootReal = await fs.realpath(normalizedBase).catch(() => normalizedBase);
-    const resolved = path.resolve(normalizedBase, normalizedTarget);
-    const relative = path.relative(normalizedBase, resolved);
-    if (relative.startsWith('..') || path.isAbsolute(relative)) {
-        throw new Error(`Path traversal blocked: "${target}" escapes base "${basePath}"`);
-    }
-    const segments = relative.split(path.sep).filter(Boolean);
-    let current = rootReal;
-    for (let index = 0; index < segments.length; index += 1) {
-        const candidate = path.join(current, segments[index]);
-        try {
-            const stat = await fs.lstat(candidate);
-            if (stat.isSymbolicLink()) {
-                throw new Error(`Symlink traversal blocked: "${target}"`);
-            }
-            const real = await fs.realpath(candidate).catch(() => candidate);
-            if (!real.startsWith(rootReal + path.sep) && real !== rootReal) {
-                throw new Error(`Path traversal blocked: "${target}" escapes base "${basePath}"`);
-            }
-            current = real;
-        }
-        catch (error) {
-            if (error.code === 'ENOENT' && options?.allowMissingTail) {
-                return path.join(current, ...segments.slice(index));
-            }
-            throw error;
-        }
-    }
-    return current;
-}
-/**
- * The capability set the local on-disk connector implements. This MUST stay
- * byte-equal to the `local` connector's `capabilities` array in
- * `package.json#neuralis.connectors` — `SourceLoader.instantiateConnector`
- * fails closed (`ConnectorCapabilityMismatch`) on any divergence, and for a
- * first-party connector `wiring.ts` now re-throws that (boot-fatal) instead of
- * silently degrading the kind. `localDiskCapabilities.test.ts` is the
- * derive-and-verify drift guard that catches a mismatch at TEST time.
- */
-export const LOCAL_DISK_CAPABILITIES = [
-    'list', 'read', 'stat', 'write', 'delete', 'move', 'mkdir', 'rmdir',
-    'scanDelta', 'walk', 'count', 'peekCount', 'scanContent', 'subscribeEvents', 'resolveOsUri',
-    'rawRead',
-];
-/**
- * Structured failure thrown by `LocalDiskConnector.resolveOsUri` when the
- * connector is running inside a Docker container but no host-pair root has
- * been configured. Returning a container-internal path here would corrupt
- * vector payloads + filesystem-node `os_uri` fields with paths that do not
- * exist on the host. Callers (sync runner, the write engine) catch this
- * and either skip the upsert or persist `os_uri: undefined` instead.
- */
-export class OsUriUnresolvableError extends Error {
-    code;
-    source;
-    uri;
-    constructor(params) {
-        super(`os_uri unresolvable for "${params.uri}" on source "${params.source}": ` +
-            `running in Docker, but the source config has no \`hostRoot\` and no ` +
-            `\`NEURALIS_MOUNT_*\` os-mount covers its root` +
-            (params.root ? ` ("${params.root}")` : '') +
-            `. Refusing to emit container-internal paths into vectors/os_uri. ` +
-            `Add the path via \`neuralis mount add\` (which registers the ` +
-            `host-pair env), or set \`hostRoot\` on the source config.`);
-        this.name = 'OsUriUnresolvableError';
-        this.code = 'os_uri_host_pair_missing';
-        this.source = params.source;
-        this.uri = params.uri;
-    }
-}
-/**
- * Connector for local filesystem access — URI-native.
- *
- * Contributed by brain-core via `neuralis.connectors[]` manifest entry
- * `{ kind: 'local', configSchema: { root, hostRoot? } }`. The package loader
- * instantiates it via `createLocalDiskConnector(ctx)` for each source binding.
- */
-export class LocalDiskConnector {
-    kind = 'local';
-    source;
-    portVersion = CONNECTOR_PORT_VERSION;
-    #root;
-    #hostRoot;
-    #isDocker;
-    #capabilities;
-    #countCache = new Map();
-    constructor(root, source, hostRoot, isDocker) {
-        this.#root = path.resolve(root);
-        this.source = source;
-        this.#hostRoot = hostRoot ? path.resolve(hostRoot) : undefined;
-        this.#isDocker = isDocker ?? detectDockerRuntime();
-        this.#capabilities = Object.freeze(new Set(LOCAL_DISK_CAPABILITIES));
-    }
-    capabilities() {
-        return this.#capabilities;
-    }
-    /** Expose the resolved root path for diagnostics / wiring logs. */
-    get root() {
-        return this.#root;
-    }
-    async probeRoot() {
-        try {
-            await fs.access(this.#root, (await import('node:fs')).constants.R_OK);
-            return { rootPath: this.#root, exists: true, readable: true };
-        }
-        catch (error) {
-            const code = accessErrorCode(error);
-            return {
-                rootPath: this.#root,
-                exists: code !== 'ROOT_MISSING',
-                readable: false,
-                error: error instanceof Error ? error.message : String(error),
-            };
-        }
-    }
-    /**
-     * Connector-owned liveness — whether the backing host directory is reachable.
-     * Wraps {@link probeRoot} but maps to the fixed `SourceLiveReason` enum and
-     * DISCARDS the raw `rootPath`/`error` (those carry the absolute host-mount
-     * path — leaking them to a member via the tone-title is a path-disclosure
-     * regression). UI-tone + `<runtime_stack>` signal only; never gates access.
-     */
-    async probeConnection() {
-        const probe = await this.probeRoot();
-        if (probe.exists && probe.readable)
-            return { connected: true };
-        return { connected: false, reason: probe.exists ? 'fs_permission' : 'fs_unreachable' };
-    }
-    #extractPath(uri) {
-        const prefix = `${this.source}://`;
-        if (!uri.startsWith(prefix)) {
-            throw new Error(`URI "${uri}" does not belong to source "${this.source}"`);
-        }
-        return uri.slice(prefix.length) || '/';
-    }
-    #toUri(relativePath) {
-        const clean = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath;
-        return clean ? `${this.source}://${clean}` : `${this.source}://`;
-    }
-    async list(uri) {
-        const dirPath = this.#extractPath(uri);
-        const isRoot = dirPath === '/' || dirPath === '' || dirPath === '.';
-        let absPath;
-        try {
-            absPath = await resolveAndGuard(this.#root, isRoot ? '.' : dirPath);
-        }
-        catch (error) {
-            const code = accessErrorCode(error);
-            if (isRoot && code) {
-                throw new LocalDiskRootAccessError(code, this.#root, uri, error);
-            }
-            if (isSkippableFsError(error))
-                return [];
-            throw error;
-        }
-        let entries;
-        try {
-            entries = await fs.readdir(absPath, { withFileTypes: true });
-        }
-        catch (error) {
-            const code = accessErrorCode(error);
-            if (isRoot && code) {
-                throw new LocalDiskRootAccessError(code, this.#root, uri, error);
-            }
-            if (isSkippableFsError(error))
-                return [];
-            throw error;
-        }
-        const items = [];
-        for (const entry of entries) {
-            if (entry.isSymbolicLink())
-                continue;
-            const entryRelPath = path.join(dirPath === '/' ? '/' : dirPath, entry.name);
-            const entryUri = this.#toUri(entryRelPath);
-            const isDir = entry.isDirectory();
-            let size;
-            let modifiedAt;
-            if (!isDir) {
-                try {
-                    const stat = await fs.stat(path.join(absPath, entry.name));
-                    size = stat.size;
-                    modifiedAt = stat.mtime.toISOString();
-                }
-                catch { /* stat failure is non-fatal for listing */ }
-            }
-            items.push({
-                uri: entryUri,
-                name: entry.name,
-                isDirectory: isDir,
-                ...(size != null ? { size } : {}),
-                ...(modifiedAt ? { modifiedAt } : {}),
-            });
-        }
-        return items.sort((a, b) => {
-            if (a.isDirectory !== b.isDirectory)
-                return a.isDirectory ? -1 : 1;
-            return a.name.localeCompare(b.name);
-        });
-    }
-    /**
-     * Existence + metadata, on the SAME guarded path as `read` and without
-     * transferring a byte of content. `null` = the path resolved but nothing is
-     * there (`ENOENT`, from either the guard's per-segment walk or the `lstat`);
-     * every other failure THROWS exactly as `read` would — a traversal/symlink
-     * refusal, an EACCES, a root-access error — so the caller's existing
-     * "gone vs. could-not-ask" split keeps working unchanged.
-     *
-     * `lstat`, never `stat`: `resolveAndGuard` REFUSES a symlink rather than
-     * resolving through it, so following one here would answer for a target the
-     * read path would never have served.
-     */
-    async stat(uri) {
-        const ref = this.#extractPath(uri);
-        let absPath;
-        try {
-            absPath = await resolveAndGuard(this.#root, ref);
-        }
-        catch (error) {
-            if (error?.code === 'ENOENT')
-                return null;
-            throw error;
-        }
-        let info;
-        try {
-            info = await fs.lstat(absPath);
-        }
-        catch (error) {
-            if (error?.code === 'ENOENT')
-                return null;
-            throw error;
-        }
-        return {
-            isDirectory: info.isDirectory(),
-            size: info.size,
-            modifiedAt: info.mtime.toISOString(),
-        };
-    }
-    /**
-     * The sync media lane's PDF read — NOT a kernel `ConnectorPort` member (only
-     * a connector that holds the file on its own disk can render it; the lane
-     * treats a connector without it as "unavailable"). The raw bytes' sha256
-     * (the point's `content_hash`) and pages `first..last` rendered by the ONE
-     * renderer — none when the hash equals `unlessHash`, so an unchanged PDF is
-     * never re-rendered. `null` when `pdftoppm` is not installed; the same
-     * containment and read cap as `read`.
-     */
-    async renderPdfPages(uri, opts) {
-        const absPath = await resolveAndGuard(this.#root, this.#extractPath(uri));
-        const stat = await fs.stat(absPath);
-        if (stat.isDirectory())
-            throw new Error(`Cannot read directory as file: "${uri}"`);
-        const readCap = maxReadBytes();
-        if (stat.size > readCap)
-            throw new Error(`File too large (${stat.size} bytes, max ${readCap}): "${uri}"`);
-        if (!(await hasPdftoppm()))
-            return null;
-        const contentHash = createHash('sha256').update(await fs.readFile(absPath)).digest('hex');
-        if (opts.unlessHash !== undefined && opts.unlessHash === contentHash)
-            return { contentHash, pages: [] };
-        return { contentHash, pages: await pdftoppmPages(absPath, opts.first, opts.last) };
-    }
-    /**
-     * The byte-exact read. Same guarded resolver as `read`; the cap is
-     * `min(opts.maxBytes, brainMaxReadFileMb)`, checked on the OPENED
-     * descriptor's size before any byte is buffered, and the read itself pulls
-     * at most that size+1 bytes — a file that grew after the size check is
-     * refused (over the cap: the too-large refusal), never cut.
-     */
-    async readRaw(uri, opts) {
-        const absPath = await resolveAndGuard(this.#root, this.#extractPath(uri));
-        const planeCap = maxReadBytes();
-        const cap = Math.max(0, Math.min(Math.floor(opts.maxBytes), planeCap));
-        const tooLarge = (size) => new ConnectorRawReadTooLarge(uri, cap, {
-            ...(size === undefined ? {} : { size }),
-            ...(planeCap < opts.maxBytes ? { planeLimit: planeCap } : {}),
-        });
-        const handle = await fs.open(absPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
-        try {
-            const info = await handle.stat();
-            if (info.isDirectory())
-                throw new Error(`Cannot read directory as file: "${uri}"`);
-            if (!info.isFile())
-                throw new Error(`Not a regular file: "${uri}"`);
-            if (info.size > cap)
-                throw tooLarge(info.size);
-            // Sized by the fstat answer, not the cap; the one extra byte detects growth.
-            const limit = info.size;
-            const buffer = Buffer.allocUnsafe(limit + 1);
-            let filled = 0;
-            while (filled <= limit) {
-                const { bytesRead } = await handle.read(buffer, filled, Math.min(RAW_READ_CHUNK, limit + 1 - filled), filled);
-                if (bytesRead === 0)
-                    break;
-                filled += bytesRead;
-            }
-            if (filled > limit)
-                throw filled > cap ? tooLarge() : new Error(`File changed while reading: "${uri}"`);
-            return {
-                bytes: new Uint8Array(buffer.buffer, buffer.byteOffset, filled),
-                size: filled,
-                mimeType: binaryMimeTypeForPath(absPath) ?? inferMimeTypeFromFilename(absPath),
-            };
-        }
-        finally {
-            await handle.close();
-        }
-    }
-    async read(uri) {
-        const ref = this.#extractPath(uri);
-        const absPath = await resolveAndGuard(this.#root, ref);
-        const stat = await fs.stat(absPath);
-        if (stat.isDirectory()) {
-            throw new Error(`Cannot read directory as file: "${uri}"`);
-        }
-        const readCap = maxReadBytes();
-        if (stat.size > readCap) {
-            throw new Error(`File too large (${stat.size} bytes, max ${readCap}): "${uri}"`);
-        }
-        const binaryMimeType = binaryMimeTypeForPath(absPath);
-        if (binaryMimeType) {
-            // PDFs get a special path: extract text by default (pdftotext), and
-            // optionally render the first page when NEURALIS_FS_READ_PDF_RENDER=1.
-            // The bytes emission for the rendered page goes through the same cap as
-            // images.
-            if (binaryMimeType === 'application/pdf') {
-                const haveText = await hasPdftotext();
-                const textExcerpt = haveText ? await pdftotextExcerpt(absPath) : null;
-                if (pdfRenderFirstPage() && (await hasPdftoppm())) {
-                    const rendered = (await pdftoppmPages(absPath, 1, 1))[0]?.png ?? null;
-                    if (rendered && rendered.length <= getInlineImageCapBytes()) {
-                        return {
-                            text: textExcerpt ?? '',
-                            mimeType: 'image/png',
-                            // Signal the rendered-PDF case: the bytes are a png rendering of
-                            // a .pdf source. The journal must persist these INLINE (re-reading
-                            // the .pdf uri would re-render non-deterministically / 400). dynamic-brook MM2.
-                            sourceMimeType: 'application/pdf',
-                            size: stat.size,
-                            bytes: rendered.toString('base64'),
-                        };
-                    }
-                }
-                if (textExcerpt !== null) {
-                    return { text: textExcerpt, mimeType: binaryMimeType, size: stat.size };
-                }
-                return {
-                    text: `[application/pdf — pdftotext unavailable; install poppler-utils to enable PDF text extraction]`,
-                    mimeType: binaryMimeType,
-                    size: stat.size,
-                };
-            }
-            // Image / video / other binaries — emit base64 when under the per-MIME
-            // inline cap, or a text marker otherwise.
-            const cap = inlineCapForMime(binaryMimeType);
-            if (cap !== null && stat.size <= cap) {
-                const buffer = await fs.readFile(absPath);
-                return {
-                    text: '',
-                    mimeType: binaryMimeType,
-                    size: stat.size,
-                    bytes: buffer.toString('base64'),
-                };
-            }
-            if (cap !== null) {
-                return {
-                    text: `[binary file too large to inline: ${binaryMimeType} ${formatBytes(stat.size)} (cap ${formatBytes(cap)})]`,
-                    mimeType: binaryMimeType,
-                    size: stat.size,
-                };
-            }
-            // Other binaries (zip, exe, font, …) — leave bytes unset, stay
-            // text-empty as before so the use-case downgrades to a marker.
-            return {
-                text: '',
-                mimeType: binaryMimeType,
-                size: stat.size,
-            };
-        }
-        const buffer = await fs.readFile(absPath);
-        try {
-            const text = new TextDecoder('utf-8', { fatal: true }).decode(buffer);
-            if (!looksBinaryContent(text))
-                return { text, size: stat.size };
-        }
-        catch (error) {
-            if (!(error instanceof TypeError))
-                throw error;
-        }
-        return { text: `[binary or invalid UTF-8 @ ${uri}: ${stat.size} bytes]`,
-            mimeType: 'application/octet-stream', size: stat.size };
-    }
-    async write(uri, content) {
-        const filePath = this.#extractPath(uri);
-        const absPath = await resolveAndGuard(this.#root, filePath, { allowMissingTail: true });
-        await fs.mkdir(path.dirname(absPath), { recursive: true });
-        if (typeof content === 'string') {
-            await fs.writeFile(absPath, content, 'utf-8');
-        }
-        else {
-            await fs.writeFile(absPath, Buffer.from(content));
-        }
-        return { uri };
-    }
-    async delete(uri) {
-        const ref = this.#extractPath(uri);
-        const absPath = await resolveAndGuard(this.#root, ref);
-        await fs.unlink(absPath);
-    }
-    async move(fromUri, toUri) {
-        const fromRef = this.#extractPath(fromUri);
-        const toRef = this.#extractPath(toUri);
-        const fromAbs = await resolveAndGuard(this.#root, fromRef);
-        const toAbs = await resolveAndGuard(this.#root, toRef, { allowMissingTail: true });
-        await fs.mkdir(path.dirname(toAbs), { recursive: true });
-        await fs.rename(fromAbs, toAbs);
-        return { uri: toUri, previousUri: fromUri };
-    }
-    async mkdir(uri) {
-        const ref = this.#extractPath(uri);
-        const absPath = await resolveAndGuard(this.#root, ref, { allowMissingTail: true });
-        await fs.mkdir(absPath, { recursive: true });
-    }
-    async rmdir(uri) {
-        const ref = this.#extractPath(uri);
-        const absPath = await resolveAndGuard(this.#root, ref);
-        // Empty-dir removal only — the recursive folder-delete usecase unlinks /
-        // tombstones every contained file first, then drops the empty shells. A
-        // populated dir throws ENOTEMPTY here (fail-safe, never a silent blind erase).
-        await fs.rmdir(absPath);
-    }
-    /**
-     * OS-level change events under `rootUri`, fed by the shared FsWatchHub
-     * (D6: ONE watcher substrate). Catches EVERY background change — shell
-     * writes, host edits, git checkouts, external programs — not just app
-     * writes. URI mapping happens here (the hub only knows absolute paths);
-     * exclude filtering and debounce are the SUBSCRIBER's job. An `overflow`
-     * event means "event delivery can no longer be trusted — full reconcile".
-     */
-    subscribeEvents(rootUri, listener, opts) {
-        const subPath = this.#extractPath(rootUri);
-        const watchRoot = path.resolve(this.#root, subPath === '/' ? '.' : subPath);
-        if (watchRoot !== this.#root && !watchRoot.startsWith(`${this.#root}${path.sep}`)) {
-            throw new Error(`subscribeEvents root "${rootUri}" escapes source "${this.source}".`);
-        }
-        // Push the exclude set down to the watcher: excluded trees never consume
-        // OS watch descriptors (inotify budgets matter on repo-sized sources).
-        const excludeRegexes = compileGlobPatterns(opts?.excludeGlobs ?? []);
-        const ignored = excludeRegexes.length > 0
-            ? (absPath) => {
-                const rel = path.relative(this.#root, absPath);
-                if (!rel || rel.startsWith('..'))
-                    return false;
-                const relPosix = rel.split(path.sep).join('/');
-                return excludeRegexes.some((rx) => rx.test(relPosix));
-            }
-            : undefined;
-        const handle = getFsWatchHub().acquire(watchRoot, (event) => {
-            if (event.kind === 'overflow') {
-                // Carry the hub's classification through 1:1 — a fixed reason class
-                // and an errno NAME, never a path or an error message (invariant 9).
-                // The consumer still ACTS the same way whatever the value (reconcile
-                // the whole source); the cause exists so an incident can be attributed
-                // from a log line instead of being one undifferentiated signal.
-                listener({
-                    kind: 'overflow',
-                    uri: `${this.source}://`,
-                    modifiedAt: event.at,
-                    ...(event.reason ? { reason: event.reason } : {}),
-                    ...(event.code ? { code: event.code } : {}),
-                });
-                return;
-            }
-            const rel = path.relative(this.#root, event.absPath);
-            if (!rel || rel.startsWith('..'))
-                return;
-            listener({
-                kind: event.kind,
-                uri: this.#toUri(rel.split(path.sep).join('/')),
-                modifiedAt: event.at,
-            });
-        }, {
-            ...(ignored ? { ignored } : {}),
-            // Declared per listener: the hub shares one watcher per root and takes
-            // the conservative maximum across everything live on it.
-            recovery: resolveWatchRecovery(),
-        });
-        return {
-            unsubscribe: () => { void handle.release(); },
-        };
-    }
-    async scanDelta(request) {
-        const rootUri = request.rootUri ?? `${this.source}://`;
-        const rootPath = this.#extractPath(rootUri) || '/';
-        // The checkpoint is stamped BEFORE the walk, never after it. A walk of a
-        // repo-sized tree takes seconds to minutes; a file edited AFTER the walk
-        // visited it but BEFORE the walk ended carries an mtime earlier than an
-        // end-stamped cursor, so the next delta would never report it and the edit
-        // would sit unindexed until something else touched the file. Stamping first
-        // makes the overlap conservative: the window re-reports, it never skips.
-        const checkpoint = new Date().toISOString();
-        const { items: files, truncated } = await this.#walkFiles(rootPath, request.signal, request.excludeGlobs, request.maxScanFiles);
-        // An unparseable cursor yields NaN, and every `>=` against NaN is false —
-        // which would report NOTHING changed and silently strand the whole source.
-        // Treat it as "no cursor" and return the full set: this scan re-reports,
-        // it never skips. (HEAD relied on NaN being falsy for the same outcome;
-        // the explicit test survives the `>= 0` boundary the inclusive bound has.)
-        const parsedSince = request.since ? new Date(request.since).getTime() : undefined;
-        const sinceMs = parsedSince !== undefined && Number.isFinite(parsedSince) ? parsedSince : undefined;
-        // INCLUSIVE (`>=`) on purpose. Filesystem mtime resolution is coarser than
-        // the cursor (whole seconds on several filesystems), so a change landing in
-        // the same tick as the previous checkpoint is indistinguishable from the
-        // state that checkpoint described. An exclusive bound drops it silently;
-        // the inclusive one re-reports the boundary file and the content-hash skip
-        // in the sync runner absorbs the repeat at no embedding cost.
-        const changed = sinceMs === undefined ? files : files.filter((item) => {
-            if (!item.modifiedAt)
-                return true;
-            const modifiedAtMs = new Date(item.modifiedAt).getTime();
-            return Number.isFinite(modifiedAtMs) && modifiedAtMs >= sinceMs;
-        });
-        return {
-            files: changed,
-            checkpoint,
-            truncated,
-            // ONE walk answers both questions: `changed` is the delta, `files` is the
-            // complete set the same traversal saw, and `checkpoint`/`truncated`
-            // describe both. Answered only when asked — an unasked inventory would
-            // double the response for every caller that does not need it.
-            ...(request.includeInventory ? { inventory: files } : {}),
-        };
-    }
-    resolveOsUri(uri) {
-        const relativePath = this.#extractPath(uri);
-        const absPath = path.resolve(this.#root, relativePath.startsWith('/') ? `.${relativePath}` : relativePath);
-        if (this.#hostRoot) {
-            return absPath.replace(this.#root, this.#hostRoot);
-        }
-        if (this.#isDocker) {
-            // Running in Docker without a host-pair root → returning the
-            // container-internal absPath would write a path that does not exist
-            // on the host into the vector payload and the filesystem-node
-            // os_uri field. Fail loudly so the caller can skip / null it out.
-            throw new OsUriUnresolvableError({ source: this.source, uri, root: this.#root });
-        }
-        return absPath;
-    }
-    #countCacheKey(rootUri, opts) {
-        // No default excludes — physical count MUST reflect the real filesystem.
-        // Callers that want filtered counts pass opts.excludeGlobs explicitly.
-        const excludes = opts?.excludeGlobs ?? [];
-        const cap = typeof opts?.maxScanFiles === 'number' && opts.maxScanFiles > 0 ? opts.maxScanFiles : DEFAULT_MAX_SCAN_FILES;
-        return `${rootUri}::${excludes.join('|')}::${cap}`;
-    }
-    peekCount(rootUri, opts) {
-        const cached = this.#countCache.get(this.#countCacheKey(rootUri, opts));
-        if (!cached)
-            return undefined;
-        if (Date.now() - cached.ts >= getBrainConfigNumber('brainCountCacheTtlMs', undefined, COUNT_CACHE_TTL_MS))
-            return undefined;
-        return cached.value;
-    }
-    async walk(rootUri, opts) {
-        return (await this.#walk(rootUri, opts, false)).items;
-    }
-    async walkWithStatus(rootUri, opts) {
-        return this.#walk(rootUri, opts, true);
-    }
-    async #walk(rootUri, opts, diagnostic) {
-        // Strip a trailing slash on the walk root so a caller-supplied
-        // `packages://x/` does not seed `current.virtual = "x/"` and produce
-        // mid-URI "//" children via the string-concat below. `list()`/`#walkFiles()`
-        // use `path.join` and are already safe; this keeps `walk()` robust too.
-        const rootPath = (this.#extractPath(rootUri) || '/').replace(/\/+$/, '') || '/';
-        let absRoot;
-        try {
-            absRoot = await resolveAndGuard(this.#root, rootPath === '/' ? '.' : rootPath);
-        }
-        catch (error) {
-            if (diagnostic || isSkippableFsError(error))
-                return { items: [], complete: false, truncated: false };
-            throw error;
-        }
-        const maxItems = typeof opts?.maxItems === 'number' && opts.maxItems > 0
-            ? Math.min(opts.maxItems, DEFAULT_MAX_SCAN_FILES)
-            : diagnostic ? DEFAULT_MAX_SCAN_FILES : 500;
-        const maxEntries = typeof opts?.maxEntries === 'number' && Number.isFinite(opts.maxEntries) && opts.maxEntries > 0
-            ? Math.min(Math.floor(opts.maxEntries), DEFAULT_MAX_SCAN_FILES)
-            : typeof opts?.maxItems === 'number' && Number.isFinite(opts.maxItems) && opts.maxItems > 0
-                ? Math.min(Math.floor(opts.maxItems), DEFAULT_MAX_SCAN_FILES) : 500;
-        let visited = 1; // The traversal root is a visited directory too.
-        let complete = true;
-        let truncated = false;
-        // No default excludes — walk returns the full on-disk tree.
-        const excludes = opts?.excludeGlobs ?? [];
-        const excludeMatchers = compileGlobMatchers(excludes);
-        const items = [];
-        const queue = [
-            { abs: absRoot, virtual: rootPath === '/' ? '/' : rootPath },
-        ];
-        let nextDirectory = 0;
-        while (nextDirectory < queue.length) {
-            if (items.length >= maxItems || (diagnostic && visited >= maxEntries)) {
-                truncated = true;
-                break;
-            }
-            const current = queue[nextDirectory++];
-            let entries;
-            try {
-                if (diagnostic) {
-                    // One-entry native buffer and a charged application buffer: no full
-                    // readdir allocation before the caller's budget has been applied.
-                    const directory = await fs.opendir(current.abs, { bufferSize: 1 });
-                    entries = [];
-                    try {
-                        while (visited < maxEntries) {
-                            const entry = await directory.read();
-                            if (entry === null)
-                                break;
-                            visited += 1;
-                            entries.push(entry);
-                        }
-                        if (visited >= maxEntries)
-                            truncated = true;
-                    }
-                    finally {
-                        await directory.close();
-                    }
-                }
-                else {
-                    entries = await fs.readdir(current.abs, { withFileTypes: true });
-                }
-            }
-            catch (error) {
-                if (diagnostic || isSkippableFsError(error)) {
-                    complete = false;
-                    continue;
-                }
-                throw error;
-            }
-            entries.sort((a, b) => {
-                const aDir = a.isDirectory() ? 0 : 1;
-                const bDir = b.isDirectory() ? 0 : 1;
-                if (aDir !== bDir)
-                    return aDir - bDir;
-                return a.name.localeCompare(b.name);
-            });
-            for (const entry of entries) {
-                if (items.length >= maxItems) {
-                    truncated = true;
-                    break;
-                }
-                if (entry.isSymbolicLink?.()) {
-                    complete = false;
-                    continue;
-                }
-                const entryAbs = path.join(current.abs, entry.name);
-                const relFromRoot = path.relative(absRoot, entryAbs).replace(/\\/g, '/');
-                if (matchesAny(relFromRoot, excludeMatchers)) {
-                    complete = false;
-                    continue;
-                }
-                const virtualPath = current.virtual === '/'
-                    ? `/${entry.name}`
-                    : `${current.virtual.replace(/\/+$/, '')}/${entry.name}`;
-                const isDir = entry.isDirectory();
-                let size;
-                let modifiedAt;
-                if (!isDir) {
-                    try {
-                        const stat = await fs.stat(entryAbs);
-                        size = stat.size;
-                        modifiedAt = stat.mtime.toISOString();
-                    }
-                    catch {
-                        complete = false; /* transient stat failure — emit without metadata */
-                    }
-                }
-                items.push({
-                    uri: this.#toUri(virtualPath),
-                    name: entry.name,
-                    isDirectory: isDir,
-                    ...(size != null ? { size } : {}),
-                    ...(modifiedAt ? { modifiedAt } : {}),
-                });
-                if (isDir)
-                    queue.push({ abs: entryAbs, virtual: virtualPath });
-            }
-        }
-        return { items, complete: complete && !truncated, truncated };
-    }
-    async count(rootUri, opts) {
-        // No default excludes — physical count must match walk() cardinality.
-        const excludes = opts?.excludeGlobs ?? [];
-        const cacheKey = this.#countCacheKey(rootUri, opts);
-        const cached = this.#countCache.get(cacheKey);
-        const now = Date.now();
-        if (cached && now - cached.ts < getBrainConfigNumber('brainCountCacheTtlMs', undefined, COUNT_CACHE_TTL_MS))
-            return cached.value;
-        const rootPath = this.#extractPath(rootUri) || '/';
-        let absRoot;
-        try {
-            absRoot = await resolveAndGuard(this.#root, rootPath === '/' ? '.' : rootPath);
-        }
-        catch (error) {
-            if (isSkippableFsError(error))
-                return 0;
-            throw error;
-        }
-        const excludeMatchers = compileGlobMatchers(excludes);
-        const cap = typeof opts?.maxScanFiles === 'number' && opts.maxScanFiles > 0
-            ? opts.maxScanFiles
-            : DEFAULT_MAX_SCAN_FILES;
-        let total = 0;
-        const stack = [absRoot];
-        while (stack.length > 0) {
-            if (total >= cap)
-                break;
-            const current = stack.pop();
-            let entries;
-            try {
-                entries = await fs.readdir(current, { withFileTypes: true });
-            }
-            catch (error) {
-                if (isSkippableFsError(error))
-                    continue;
-                throw error;
-            }
-            for (const entry of entries) {
-                if (entry.isSymbolicLink?.())
-                    continue;
-                const entryAbs = path.join(current, entry.name);
-                const relFromRoot = path.relative(absRoot, entryAbs);
-                if (matchesAny(relFromRoot, excludeMatchers))
-                    continue;
-                if (entry.isDirectory()) {
-                    stack.push(entryAbs);
-                }
-                else if (entry.isFile()) {
-                    total += 1;
-                    if (total >= cap)
-                        break;
-                }
-            }
-        }
-        this.#countCache.set(cacheKey, { value: total, ts: now });
-        return total;
-    }
-    async scanContent(rootUri, query, opts) {
-        if (!query || query.length === 0)
-            return [];
-        const rootPath = this.#extractPath(rootUri) || '/';
-        let absRoot;
-        try {
-            absRoot = await resolveAndGuard(this.#root, rootPath === '/' ? '.' : rootPath);
-        }
-        catch (error) {
-            if (isSkippableFsError(error))
-                return [];
-            throw error;
-        }
-        const bins = await resolveSearchBinaries();
-        const caseSensitive = opts?.caseSensitive === true;
-        const maxMatches = typeof opts?.maxMatches === 'number' && opts.maxMatches > 0 ? opts.maxMatches : 500;
-        let hasGit = false;
-        try {
-            const s = await fs.stat(path.join(absRoot, '.git'));
-            hasGit = s.isDirectory();
-        }
-        catch { /* no .git — fall through */ }
-        const excludeArgs = [];
-        for (const pattern of opts?.excludeGlobs ?? []) {
-            excludeArgs.push('--exclude-dir', pattern.replace(/\/\*\*$/, '').replace(/^\*\*\//, ''));
-        }
-        // The tool contract (tools/fs_search.json) promises LITERAL fixed-string
-        // grep semantics — every engine branch passes -F so a query with regex
-        // metacharacters (`${`, `[slug]`) neither hard-fails nor varies by which
-        // binary wins the ladder. Fuzzy needs are semantic mode's job.
-        if (hasGit && bins.gitGrep) {
-            const args = ['grep', '-n', '--column', '--no-color', '-F'];
-            if (!caseSensitive)
-                args.push('-i');
-            args.push('-e', query, '--');
-            // Include/exclude ride the pathspec tail. Git pathspecs are
-            // case-SENSITIVE by default (`:(icase)` restores parity with -i), and
-            // plain pathspec `*` crosses `/` (wildmatch without pathname mode) —
-            // semantics differ slightly from rg's gitignore-style globs; documented
-            // best-effort. Before this, the git-grep branch (the primary branch for
-            // repo checkouts) silently ignored every glob option.
-            for (const pat of opts?.includeGlobs ?? []) {
-                args.push(caseSensitive ? pat : `:(icase)${pat}`);
-            }
-            for (const pat of opts?.excludeGlobs ?? []) {
-                args.push(`:(exclude)${pat}`);
-            }
-            return this.#parseGrepOutput(rootUri, absRoot, await runBinary(bins.gitGrep, args, absRoot, maxMatches), maxMatches);
-        }
-        if (bins.rg) {
-            const args = ['-n', '--column', '--no-heading', '--color=never', '-F'];
-            if (!caseSensitive)
-                args.push('-i');
-            for (const pat of opts?.includeGlobs ?? [])
-                args.push('--glob', pat);
-            for (const pat of opts?.excludeGlobs ?? [])
-                args.push('--glob', `!${pat}`);
-            args.push('-e', query, absRoot);
-            return this.#parseGrepOutput(rootUri, absRoot, await runBinary(bins.rg, args, absRoot, maxMatches), maxMatches);
-        }
-        if (bins.grep) {
-            const args = ['-R', '-n', '--color=never', '-F'];
-            if (!caseSensitive)
-                args.push('-i');
-            // GNU grep --include matches the BASENAME only — the narrowest of the
-            // three glob dialects; documented best-effort.
-            for (const pat of opts?.includeGlobs ?? [])
-                args.push(`--include=${pat}`);
-            args.push(...excludeArgs, '-e', query, absRoot);
-            return this.#parseGrepOutput(rootUri, absRoot, await runBinary(bins.grep, args, absRoot, maxMatches), maxMatches);
-        }
-        throw new Error('No text-search binary available on the host (tried rg, git grep, grep)');
-    }
-    #parseGrepOutput(rootUri, absRoot, output, maxMatches) {
-        const lines = output.split('\n');
-        const results = [];
-        const isSourceRoot = rootUri.endsWith('://');
-        const joinBase = isSourceRoot ? rootUri : rootUri.replace(/\/+$/, '');
-        for (const line of lines) {
-            if (results.length >= maxMatches)
-                break;
-            if (!line)
-                continue;
-            const m = line.match(/^(.+?):(\d+)(?::(\d+))?:(.*)$/);
-            if (!m)
-                continue;
-            const filePath = m[1];
-            const lineNo = parseInt(m[2], 10);
-            const col = m[3] ? parseInt(m[3], 10) : undefined;
-            const preview = m[4];
-            const rel = path.relative(absRoot, filePath).replace(/\\/g, '/');
-            const hasRel = rel && rel !== '.' && !rel.startsWith('..');
-            const uri = !hasRel
-                ? (isSourceRoot ? rootUri : joinBase)
-                : isSourceRoot ? `${joinBase}${rel}` : `${joinBase}/${rel}`;
-            results.push({
-                uri,
-                line: lineNo,
-                ...(typeof col === 'number' && Number.isFinite(col) ? { column: col } : {}),
-                preview,
-            });
-        }
-        return results;
-    }
-    async #walkFiles(rootPath, signal, excludeGlobs, maxScanFiles) {
-        const rootAbs = await resolveAndGuard(this.#root, rootPath === '/' ? '.' : rootPath);
-        const stack = [{ abs: rootAbs, virtual: rootPath === '/' ? '/' : rootPath }];
-        const out = [];
-        const cap = typeof maxScanFiles === 'number' && maxScanFiles > 0 ? maxScanFiles : DEFAULT_MAX_SCAN_FILES;
-        // Prune excluded trees DURING the walk — never descend into node_modules /
-        // .git / dist etc. Without this a repo-sized source blows the MAX_SCAN_FILES
-        // cap on excluded files and starves alphabetically-late included trees
-        // (e.g. `.claude`, which sorts first → pushed first → popped LAST in DFS).
-        // A directory is pruned when an exclude matches `<rel>/` (so `node_modules/**`
-        // catches the bare dir); files match their plain relative path.
-        const excludeRegexes = compileGlobPatterns(excludeGlobs ?? []);
-        const relOf = (virtual) => (virtual.startsWith('/') ? virtual.slice(1) : virtual);
-        const isExcludedDir = (virtual) => {
-            const rel = relOf(virtual);
-            return rel.length > 0 && excludeRegexes.some((rx) => rx.test(`${rel}/`));
-        };
-        const isExcludedFile = (virtual) => {
-            const rel = relOf(virtual);
-            return rel.length > 0 && excludeRegexes.some((rx) => rx.test(rel));
-        };
-        while (stack.length > 0) {
-            // Cooperative cancellation per directory pop — a repo-sized walk
-            // (~200k file cap) must stop within one directory of an abort.
-            signal?.throwIfAborted();
-            if (out.length >= cap)
-                break;
-            const current = stack.pop();
-            if (!current)
-                continue;
-            let entries;
-            try {
-                entries = await fs.readdir(current.abs, { withFileTypes: true });
-            }
-            catch (error) {
-                if (isSkippableFsError(error))
-                    continue;
-                throw error;
-            }
-            for (const entry of entries) {
-                if (out.length >= cap)
-                    break;
-                if (entry.isSymbolicLink?.())
-                    continue;
-                const entryAbs = path.join(current.abs, entry.name);
-                const entryVirtual = path.join(current.virtual === '/' ? '/' : current.virtual, entry.name);
-                if (entry.isDirectory()) {
-                    if (!isExcludedDir(entryVirtual))
-                        stack.push({ abs: entryAbs, virtual: entryVirtual });
-                    continue;
-                }
-                if (isExcludedFile(entryVirtual))
-                    continue;
-                try {
-                    const stat = await fs.stat(entryAbs);
-                    out.push({
-                        uri: this.#toUri(entryVirtual),
-                        name: entry.name,
-                        size: stat.size,
-                        modifiedAt: stat.mtime.toISOString(),
-                    });
-                }
-                catch {
-                    /* transient IO errors skip the entry, not the sync */
-                }
-            }
-        }
-        out.sort((a, b) => a.uri.localeCompare(b.uri));
-        return { items: out, truncated: out.length >= cap };
-    }
-}
-/**
- * Factory: builds a LocalDiskConnector instance for a specific source binding.
- *
- * Resolves `config.root` against the current projectRoot
- * (`resolveLocalRoot`): a relative path joins onto `ctx.projectRoot`, an
- * absolute one is the container path as written.
- */
-export function createLocalDiskConnector(ctx) {
-    const cfg = ctx.config;
-    if (typeof cfg.root !== 'string' || cfg.root.length === 0) {
-        throw new Error(`LocalDiskConnector: config.root is required for source "${ctx.source}".`);
-    }
-    const { resolvedRoot } = resolveLocalRoot({
-        configured: cfg.root,
-        projectRoot: ctx.projectRoot ?? '',
-        source: ctx.source,
-    });
-    // Host-pair precedence: explicit config wins; then derive from the
-    // `NEURALIS_MOUNT_*` os-mount table so a UI-added source whose root sits under a `pnpm
-    // neuralis:mount`-created bind (e.g. `/mounts/repo`) resolves its host path
-    // without the user having to hand-edit `hostRoot` into the config.
-    const hostRoot = cfg.hostRoot ??
-        deriveHostRootFromOsMounts(resolvedRoot, discoverOsMounts(process.env));
-    return new LocalDiskConnector(resolvedRoot, ctx.source, hostRoot);
-}
-/**
- * Derive a host-side root for `resolvedRoot` from the os-mount table. Returns
- * the host path for the *longest* matching mount whose `containerPath` is the
- * root itself or a path-boundary-correct ancestor (`/mounts/repo` matches
- * `/mounts/repo` and `/mounts/repo/sub`, but NOT `/mounts/repo2`). Mounts
- * without a `hostPath` (no `NEURALIS_MOUNT_HOST_*` pair) are skipped. Returns
- * `undefined` when nothing matches, so the caller falls through to the
- * fail-loud `OsUriUnresolvableError` path in Docker.
- */
-export function deriveHostRootFromOsMounts(resolvedRoot, mounts) {
-    const target = path.resolve(resolvedRoot);
-    let best;
-    for (const mount of mounts) {
-        if (!mount.hostPath)
-            continue;
-        const container = path.resolve(mount.containerPath);
-        const isMatch = target === container || target.startsWith(`${container}${path.sep}`);
-        if (!isMatch)
-            continue;
-        if (!best || container.length > best.containerPath.length) {
-            const tail = target.slice(container.length); // '' when target === container
-            best = { containerPath: container, hostRoot: path.join(path.resolve(mount.hostPath), tail) };
-        }
-    }
-    return best?.hostRoot;
-}
-/**
- * Canonical container-root resolution for a local source's configured root.
- * Exported so the brain-core API can hand agent-core's shell uri-policy gate
- * the SAME resolved roots the connector itself mounts — the two branches
- * (relative under the project root, absolute as written) are never re-typed.
- */
-export function resolveLocalRoot(params) {
-    const { configured, projectRoot } = params;
-    if (!path.isAbsolute(configured)) {
-        return { resolvedRoot: projectRoot ? path.join(projectRoot, configured) : configured };
-    }
-    // An absolute root is a container path as written — never re-targeted by a
-    // segment of it that happens to spell the project id.
-    return { resolvedRoot: path.resolve(configured) };
-}
-function detectDockerRuntime() {
-    const flag = process.env.NEURALIS_DOCKER;
-    if (flag === 'true' || flag === '1')
-        return true;
-    try {
-        if (existsSync('/.dockerenv'))
-            return true;
-        if (existsSync('/run/.containerenv'))
-            return true;
-    }
-    catch {
-        /* no fs access — assume non-docker */
-    }
-    return false;
-}
-//# sourceMappingURL=LocalDiskConnector.js.map