fix(graph,wiki): read the brain through brainfs (#157, slice 4) (#168)

graphsync, wiki inventory/index read through brainfs; brainfs refuses an in-brain file swapped in behind a symlink (os.SameFile). Gatekeeper round 2 PASS on d90ce66, CI run 9180 green.

Refs #157

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Mathias <mthbqv@gmail.com>

ingestion/internal/brainfs/brainfs.go

@@ -13,7 +13,9 @@ import (
 	"io"
 	"io/fs"
 	"os"
+	"path"
 	"path/filepath"
+	"strings"
 	"syscall"
 )
 
@@ -53,6 +55,55 @@ func (b *Brain) Rel(path string) (string, error) {
 	return filepath.ToSlash(rel), nil
 }
 
+// Lstat stats a brain-relative path through the root without following a
+// final symlink.
+func (b *Brain) Lstat(rel string) (fs.FileInfo, error) {
+	return b.root.Lstat(filepath.ToSlash(rel))
+}
+
+// realDir returns ErrNotRegular unless every component of rel is a real
+// directory. A swap after the check is not caught (accepted residual,
+// hyperguild#157).
+func (b *Brain) realDir(rel string) error {
+	if rel == "." {
+		return nil
+	}
+	prefix := ""
+	for _, part := range strings.Split(rel, "/") {
+		prefix = path.Join(prefix, part)
+		fi, err := b.root.Lstat(prefix)
+		if err != nil {
+			return err
+		}
+		if !fi.IsDir() {
+			return fmt.Errorf("%s: walk root component %s is not a directory: %w", rel, prefix, ErrNotRegular)
+		}
+	}
+	return nil
+}
+
+// ReadDirRegular lists the regular files directly in a brain-relative
+// directory, by name. Every component of relDir must be a real directory
+// (ErrNotRegular otherwise); symlinks, FIFOs, devices and subdirectories in
+// it are left out.
+func (b *Brain) ReadDirRegular(relDir string) ([]string, error) {
+	relDir = filepath.ToSlash(relDir)
+	if err := b.realDir(relDir); err != nil {
+		return nil, err
+	}
+	ents, err := fs.ReadDir(b.root.FS(), relDir)
+	if err != nil {
+		return nil, err
+	}
+	var names []string
+	for _, e := range ents {
+		if e.Type().IsRegular() {
+			names = append(names, e.Name())
+		}
+	}
+	return names, nil
+}
+
 // ReadRegular reads a brain-relative path, refusing anything that is not a
 // regular file, both before the open and on the opened handle.
 func (b *Brain) ReadRegular(rel string) ([]byte, error) {
@@ -63,7 +114,7 @@ func (b *Brain) ReadRegular(rel string) ([]byte, error) {
 	if !fi.Mode().IsRegular() {
 		return nil, fmt.Errorf("%s: %w", rel, ErrNotRegular)
 	}
-	return b.readOpened(rel)
+	return b.readOpenedMax(rel, -1, fi)
 }
 
 // readOpened opens rel non-blocking and reads it only if the OPENED handle is
@@ -77,7 +128,7 @@ func (b *Brain) ReadRegular(rel string) ([]byte, error) {
 // cannot create one; fs.protected_hardlinks=1 and the pod's secrets are on a
 // different filesystem from the brain volume, so a local caller cannot link
 // them in. Refusing Nlink > 1 is the next step if either changes.
-func (b *Brain) readOpened(rel string) ([]byte, error) { return b.readOpenedMax(rel, -1) }
+func (b *Brain) readOpened(rel string) ([]byte, error) { return b.readOpenedMax(rel, -1, nil) }
 
 // ReadRegularMax is ReadRegular with a size limit, checked on the opened
 // handle before reading (max < 0 means no limit).
@@ -89,10 +140,14 @@ func (b *Brain) ReadRegularMax(rel string, max int64) ([]byte, error) {
 	if !fi.Mode().IsRegular() {
 		return nil, fmt.Errorf("%s: %w", rel, ErrNotRegular)
 	}
-	return b.readOpenedMax(rel, max)
+	return b.readOpenedMax(rel, max, fi)
 }
 
-func (b *Brain) readOpenedMax(rel string, max int64) ([]byte, error) {
+// readOpenedMax opens rel and reads it if the opened handle is a regular file
+// and, when lfi is set, the same file the caller Lstat-ed: os.Root follows an
+// in-root final symlink even with O_NOFOLLOW, so a symlink to another brain
+// file swapped in between the Lstat and the open is refused only here.
+func (b *Brain) readOpenedMax(rel string, max int64, lfi fs.FileInfo) ([]byte, error) {
 	f, err := b.root.OpenFile(rel, os.O_RDONLY|syscall.O_NONBLOCK, 0)
 	if err != nil {
 		return nil, err
@@ -105,6 +160,9 @@ func (b *Brain) readOpenedMax(rel string, max int64) ([]byte, error) {
 	if !hfi.Mode().IsRegular() {
 		return nil, fmt.Errorf("%s: %w", rel, ErrNotRegular)
 	}
+	if lfi != nil && !os.SameFile(lfi, hfi) {
+		return nil, fmt.Errorf("%s: changed while opening: %w", rel, ErrNotRegular)
+	}
 	if max >= 0 && hfi.Size() > max {
 		return nil, fmt.Errorf("%s is %d bytes (limit %d): %w", rel, hfi.Size(), max, ErrTooLarge)
 	}
@@ -127,15 +185,34 @@ func (b *Brain) readOpenedMax(rel string, max int64) ([]byte, error) {
 }
 
 // wrapAfterStat is a test seam: it runs between the size check and the read,
-// and wraps the reader the read consumes.
+// and wraps the reader the read consumes. A package global: brainfs tests
+// must not use t.Parallel.
 var wrapAfterStat func(io.Reader) io.Reader
 
 // WalkRegular walks a brain-relative directory through the root and calls fn
-// for each regular file (directories are descended; symlinks, FIFOs and
-// devices are skipped, never followed). An entry error is passed to onErr and
-// the walk continues; a nil onErr ignores it.
+// for each regular file. Directories are descended; symlinks, FIFOs and
+// devices found by the walk are skipped. A walk root with any component that
+// is not a real directory goes to onErr as ErrNotRegular and nothing is
+// yielded. An entry error is passed to onErr and the walk continues; a nil
+// onErr ignores it.
+//
+// Accepted residual (hyperguild#157): a directory swapped for a symlink
+// between the listing and the read is followed. os.Root still keeps the read
+// inside the brain, but not inside relDir.
 func (b *Brain) WalkRegular(relDir string, fn func(rel string) error, onErr func(rel string, err error)) error {
-	return fs.WalkDir(b.root.FS(), filepath.ToSlash(relDir), func(p string, d fs.DirEntry, err error) error {
+	relDir = filepath.ToSlash(relDir)
+	// fs.WalkDir stats its root with a follow, and os.Root allows a symlink
+	// that stays inside the brain: knowledge -> . would alias the whole
+	// brain. Require every component of the root to be a real directory
+	// (Lstat checks only the last one).
+	err := b.realDir(relDir)
+	if err != nil {
+		if onErr != nil {
+			onErr(relDir, err)
+		}
+		return nil
+	}
+	return fs.WalkDir(b.root.FS(), relDir, func(p string, d fs.DirEntry, err error) error {
 		if err != nil {
 			if onErr != nil {
 				onErr(p, err)

ingestion/internal/brainfs/brainfs_test.go

@@ -3,8 +3,11 @@ package brainfs
 import (
 	"errors"
 	"io"
+	"io/fs"
 	"os"
 	"path/filepath"
+	"sync"
+	"sync/atomic"
 	"syscall"
 	"testing"
 	"time"
@@ -139,3 +142,123 @@ func (c *countingReader) Read(p []byte) (int, error) {
 	c.n += n
 	return n, err
 }
+
+func TestLstatDoesNotFollowSymlinksAndRefusesEscapes(t *testing.T) {
+	dir := t.TempDir()
+	outside := filepath.Join(t.TempDir(), "o.md")
+	require.NoError(t, os.WriteFile(outside, []byte("o"), 0o644))
+	require.NoError(t, os.Symlink(outside, filepath.Join(dir, "l.md")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+	fi, err := b.Lstat("l.md")
+	require.NoError(t, err)
+	assert.Equal(t, fs.ModeSymlink, fi.Mode().Type())
+	_, err = b.Lstat("../" + filepath.Base(filepath.Dir(outside)) + "/o.md")
+	assert.Error(t, err)
+}
+
+func TestWalkRegularReportsASymlinkedWalkRootAndYieldsNothing(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "real"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "real", "n.md"), []byte("n"), 0o644))
+	require.NoError(t, os.Symlink("real", filepath.Join(dir, "alias")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+	var got []string
+	var errs []error
+	require.NoError(t, b.WalkRegular("alias", func(rel string) error { got = append(got, rel); return nil },
+		func(_ string, err error) { errs = append(errs, err) }))
+	assert.Empty(t, got)
+	require.Len(t, errs, 1)
+	assert.ErrorIs(t, errs[0], ErrNotRegular)
+}
+
+func TestWalkRegularReportsASymlinkedIntermediateComponentOfTheWalkRoot(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "real", "sub"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "real", "sub", "n.md"), []byte("n"), 0o644))
+	require.NoError(t, os.Symlink("real", filepath.Join(dir, "alias")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+	var got []string
+	var errs []error
+	require.NoError(t, b.WalkRegular("alias/sub", func(rel string) error { got = append(got, rel); return nil },
+		func(_ string, err error) { errs = append(errs, err) }))
+	assert.Empty(t, got)
+	require.Len(t, errs, 1)
+	assert.ErrorIs(t, errs[0], ErrNotRegular)
+}
+
+func TestReadDirRegularListsOnlyRegularFilesAndRefusesSymlinkedComponents(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "a", "b", "sub"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "a", "b", "n.md"), []byte("n"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "other.md"), []byte("o"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "other.md"), filepath.Join(dir, "a", "b", "l.md")))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(dir, "a", "b", "f.md"), 0o644))
+	require.NoError(t, os.Symlink("a", filepath.Join(dir, "alias")))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "x"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "a"), filepath.Join(dir, "x", "mid")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	names, err := b.ReadDirRegular("a/b")
+	require.NoError(t, err)
+	assert.Equal(t, []string{"n.md"}, names)
+	for _, rel := range []string{"alias/b", "x/mid/b"} {
+		_, err := b.ReadDirRegular(rel)
+		assert.ErrorIs(t, err, ErrNotRegular, rel)
+	}
+}
+
+// A final component swapped for a symlink to another regular file in the
+// brain between the Lstat and the open: os.Root follows in-root links, so
+// only comparing the two (os.SameFile) refuses it.
+func TestReadRegularNeverReturnsAnInBrainFileSwappedInBehindASymlink(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "s.md"), []byte("zqsamefilesentinel"), 0o644))
+	p := filepath.Join(dir, "r.md")
+	require.NoError(t, os.WriteFile(p, []byte("inside"), 0o644))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	var stop atomic.Bool
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		tmp := p + ".swap"
+		for i := 0; !stop.Load(); i++ {
+			_ = os.Remove(tmp)
+			if i%2 == 0 {
+				_ = os.WriteFile(tmp, []byte("inside"), 0o644)
+			} else {
+				_ = os.Symlink("s.md", tmp)
+			}
+			_ = os.Rename(tmp, p)
+		}
+	}()
+	leaks, ok := 0, 0
+	for deadline := time.Now().Add(1500 * time.Millisecond); time.Now().Before(deadline); {
+		got, err := b.ReadRegular("r.md")
+		if err == nil {
+			ok++
+		}
+		if string(got) == "zqsamefilesentinel" {
+			leaks++
+		}
+		got, _ = b.ReadRegularMax("r.md", 1<<20)
+		if string(got) == "zqsamefilesentinel" {
+			leaks++
+		}
+	}
+	stop.Store(true)
+	wg.Wait()
+	assert.Zero(t, leaks)
+	assert.Positive(t, ok, "positive control: the regular file is read")
+}

ingestion/internal/brainfs/brainfstest/brainfstest.go

@@ -7,6 +7,7 @@
 package brainfstest
 
 import (
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
@@ -20,16 +21,23 @@ import (
 // Sentinel marks the outside file's contents.
 const Sentinel = "zqbrainfssentinelonefiftyseven"
 
+// outsideContent carries Sentinel in every field a reader might extract: the
+// frontmatter title and aliases, a heading, a wikilink and the body.
+const outsideContent = "---\ntitle: " + Sentinel + "\naliases:\n  - " + Sentinel + "\n---\n# " + Sentinel +
+	"\n\n" + Sentinel + " [[" + Sentinel + "]]\n"
+
 // Outside writes a file outside any brain dir containing Sentinel.
 func Outside(t *testing.T) string {
 	t.Helper()
 	p := filepath.Join(t.TempDir(), "secret.md")
-	if err := os.WriteFile(p, []byte("# secret\n\n"+Sentinel), 0o644); err != nil {
+	if err := os.WriteFile(p, []byte(outsideContent), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	return p
 }
 
+var swapSeq atomic.Int64
+
 // StartSwap renames, in a loop, a regular note (content inside) and either
 // a symlink to outside or a FIFO into path, until the test ends. FIFOs get a
 // writer held open until the swapper exits, so a reader that skips the
@@ -42,7 +50,15 @@ func StartSwap(t *testing.T, path, inside, outside string, fifo bool) {
 	wg.Add(1)
 	go func() {
 		defer wg.Done()
-		tmp := path + ".swap"
+		// A name of its own: swappers on one path share a test, and one
+		// opening another's FIFO for write would block forever.
+		tmp := fmt.Sprintf("%s.swap%d", path, swapSeq.Add(1))
+		// A relative link: os.Root refuses every absolute link on its own, so
+		// an absolute in-brain target would test nothing.
+		link := outside
+		if rel, err := filepath.Rel(filepath.Dir(path), outside); err == nil {
+			link = rel
+		}
 		var writers []*os.File
 		defer func() {
 			for _, w := range writers {
@@ -61,7 +77,7 @@ func StartSwap(t *testing.T, path, inside, outside string, fifo bool) {
 					}
 				}
 			default:
-				_ = os.Symlink(outside, tmp)
+				_ = os.Symlink(link, tmp)
 			}
 			_ = os.Rename(tmp, path)
 		}
@@ -69,11 +85,33 @@ func StartSwap(t *testing.T, path, inside, outside string, fifo bool) {
 	t.Cleanup(func() { stop.Store(true); wg.Wait() })
 }
 
+// WriteSentinelAt writes a file carrying Sentinel at p (creating its
+// directory), for an in-brain symlink target.
+func WriteSentinelAt(t *testing.T, p string) string {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(p, []byte(outsideContent), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return p
+}
+
 // AssertNoLeak loops read for d while a symlink swapper runs on path, and
-// fails if any output contains Sentinel.
+// fails if any output contains Sentinel. The symlink points outside the
+// brain; os.Root refuses that on its own, so pair it with AssertNoLeakFrom
+// and an in-brain target.
 func AssertNoLeak(t *testing.T, path, inside string, d time.Duration, read func() string) {
 	t.Helper()
-	StartSwap(t, path, inside, Outside(t), false)
+	AssertNoLeakFrom(t, path, inside, Outside(t), d, read)
+}
+
+// AssertNoLeakFrom is AssertNoLeak with the symlink pointing at target, e.g.
+// a file elsewhere in the brain written with WriteSentinelAt.
+func AssertNoLeakFrom(t *testing.T, path, inside, target string, d time.Duration, read func() string) {
+	t.Helper()
+	StartSwap(t, path, inside, target, false)
 	leaks, iters := 0, 0
 	for deadline := time.Now().Add(d); time.Now().Before(deadline); iters++ {
 		leaks += strings.Count(read(), Sentinel)

ingestion/internal/graphsync/graphsync.go

@@ -12,10 +12,14 @@ package graphsync
 
 import (
 	"context"
+	"errors"
 	"fmt"
-	"os"
+	"io/fs"
+	"path"
 	"path/filepath"
+	"strings"
 
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/graph"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/graphstore"
 )
@@ -46,8 +50,25 @@ func IndexDoc(ctx context.Context, store Store, brainDir, relPath string) error
 	if relPath == "" {
 		return nil
 	}
-	abs := filepath.Join(brainDir, filepath.FromSlash(relPath))
-	content, err := os.ReadFile(abs)
+	// Callers pass caller-supplied paths (brain_tunnel, brain_update): index
+	// only a clean path under wiki/ or knowledge/.
+	if path.Clean(relPath) != relPath || !filepath.IsLocal(relPath) ||
+		(!strings.HasPrefix(relPath, "wiki/") && !strings.HasPrefix(relPath, "knowledge/")) {
+		return fmt.Errorf("index %q: not a clean wiki/ or knowledge/ path", relPath)
+	}
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	return indexDoc(ctx, store, bfs, relPath)
+}
+
+// indexDoc reads relPath through the brain root, regular files only
+// (hyperguild#157): the brain is a Syncthing folder, and os.ReadFile
+// followed a synced symlink into the graph and blocked on a FIFO.
+func indexDoc(ctx context.Context, store Store, bfs *brainfs.Brain, relPath string) error {
+	content, err := bfs.ReadRegular(relPath)
 	if err != nil {
 		return fmt.Errorf("read %q: %w", relPath, err)
 	}
@@ -77,33 +98,34 @@ func BackfillFromBrainDir(ctx context.Context, store Store, brainDir string) (in
 	if store == nil {
 		return 0, nil
 	}
-	roots := []string{"wiki", "knowledge"}
-	for _, root := range roots {
-		base := filepath.Join(brainDir, root)
-		if _, err := os.Stat(base); os.IsNotExist(err) {
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return 0, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	for _, root := range []string{"wiki", "knowledge"} {
+		if _, err := bfs.Lstat(root); errors.Is(err, fs.ErrNotExist) {
 			continue
 		}
-		err := filepath.WalkDir(base, func(path string, d os.DirEntry, walkErr error) error {
-			if walkErr != nil {
-				return walkErr
-			}
-			if d.IsDir() {
+		// Any walk error, including a root that is a symlink, aborts.
+		var walkErr error
+		err := bfs.WalkRegular(root, func(rel string) error {
+			if path.Ext(rel) != ".md" {
 				return nil
 			}
-			if filepath.Ext(path) != ".md" {
-				return nil
-			}
-			rel, relErr := filepath.Rel(brainDir, path)
-			if relErr != nil {
-				return fmt.Errorf("rel %q: %w", path, relErr)
-			}
-			rel = filepath.ToSlash(rel)
-			if err := IndexDoc(ctx, store, brainDir, rel); err != nil {
+			if err := indexDoc(ctx, store, bfs, rel); err != nil {
 				return fmt.Errorf("index %q: %w", rel, err)
 			}
 			indexed++
 			return nil
+		}, func(rel string, err error) {
+			if walkErr == nil {
+				walkErr = fmt.Errorf("%s: %w", rel, err)
+			}
 		})
+		if err == nil {
+			err = walkErr
+		}
 		if err != nil {
 			return indexed, fmt.Errorf("walk %s: %w", root, err)
 		}

ingestion/internal/graphsync/graphsync_root_test.go

@@ -0,0 +1,92 @@
+package graphsync
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest"
+)
+
+func (f *fakeStore) dump() string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return fmt.Sprintf("%+v %+v", f.upserts, f.replaces)
+}
+
+// hyperguild#157 slice 4: IndexDoc and BackfillFromBrainDir read notes with
+// os.ReadFile, so a symlinked note put the target's title and wikilinks into
+// the graph, and a FIFO hung the read.
+func TestIndexDocRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) {
+	brain := t.TempDir()
+	facts := filepath.Join(brain, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(facts, "ok.md"), []byte("---\ntitle: zqinside\n---\nbody [[other]]\n"), 0o644))
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(facts, "leak.md")))
+
+	store := newFakeStore()
+	require.NoError(t, IndexDoc(context.Background(), store, brain, "wiki/w/facts/ok.md"))
+	assert.Contains(t, store.dump(), "zqinside", "positive control: a regular note is indexed")
+	assert.Error(t, IndexDoc(context.Background(), store, brain, "wiki/w/facts/leak.md"))
+	// A link to a file elsewhere in the brain: os.Root allows it, only the
+	// regular-file check refuses it.
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md")))
+	assert.Error(t, IndexDoc(context.Background(), store, brain, "wiki/w/facts/inlink.md"))
+	assert.NotContains(t, store.dump(), brainfstest.Sentinel)
+
+	p := filepath.Join(facts, "r.md")
+	read := func() string {
+		s := newFakeStore()
+		_ = IndexDoc(context.Background(), s, brain, "wiki/w/facts/r.md")
+		return s.dump()
+	}
+	brainfstest.AssertNoLeak(t, p, "---\ntitle: zqinside\n---\n", 1500*time.Millisecond, read)
+	brainfstest.AssertNoLeakFrom(t, p, "---\ntitle: zqinside\n---\n", inBrain, 1500*time.Millisecond, read)
+	brainfstest.AssertNoHang(t, p, "---\ntitle: zqinside\n---\n", 1500*time.Millisecond, 6*time.Second, func() { _ = read() })
+}
+
+func TestBackfillSkipsSymlinkedNotesAndAbortsOnASymlinkedRoot(t *testing.T) {
+	brain := t.TempDir()
+	facts := filepath.Join(brain, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(facts, "ok.md"), []byte("---\ntitle: zqinside\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(facts, "leak.md")))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "raw"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "raw", "r.md"), []byte("---\ntitle: zqrawonly\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "r.md"), filepath.Join(facts, "inlink.md")))
+	require.NoError(t, os.Symlink(".", filepath.Join(brain, "knowledge")))
+
+	store := newFakeStore()
+	_, err := BackfillFromBrainDir(context.Background(), store, brain)
+	assert.Error(t, err, "a symlinked root aborts the backfill")
+	assert.NotContains(t, store.dump(), brainfstest.Sentinel)
+	assert.NotContains(t, store.dump(), "zqrawonly")
+
+	require.NoError(t, os.Remove(filepath.Join(brain, "knowledge")))
+	store = newFakeStore()
+	n, err := BackfillFromBrainDir(context.Background(), store, brain)
+	require.NoError(t, err)
+	assert.Equal(t, 1, n, "only the regular note is indexed")
+	assert.Contains(t, store.dump(), "zqinside")
+	assert.NotContains(t, store.dump(), brainfstest.Sentinel)
+}
+
+// IndexDoc gets caller-supplied paths (brain_tunnel, brain_update): only a
+// clean path under wiki/ or knowledge/ is indexed.
+func TestIndexDocRefusesPathsOutsideWikiAndKnowledgeAndUncleanPaths(t *testing.T) {
+	brain := t.TempDir()
+	brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "secret.md"))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki", "w"), 0o755))
+	for _, p := range []string{"raw/secret.md", "wiki/w/../../raw/secret.md", "./raw/secret.md", "/raw/secret.md"} {
+		store := newFakeStore()
+		assert.Error(t, IndexDoc(context.Background(), store, brain, p), p)
+		assert.NotContains(t, store.dump(), brainfstest.Sentinel, p)
+	}
+}

ingestion/internal/search/brainroot_test.go

@@ -61,6 +61,31 @@ func TestQueryDoesNotFollowASymlinkedDirectory(t *testing.T) {
 	assert.Zero(t, leaked(rs))
 }
 
+// A search root that is a symlink staying inside the brain (wiki/<w> -> ..)
+// was followed by fs.WalkDir, aliasing raw/ and root files into results
+// (PR #166 review). The root is now Lstat-checked and skipped.
+func TestQueryDoesNotFollowASymlinkedWingRootInsideTheBrain(t *testing.T) {
+	brain, _, _ := searchBrain(t)
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "raw"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "raw", "r.md"), []byte("# r\n\nzqrawonly"), 0o644))
+	require.NoError(t, os.Symlink("..", filepath.Join(brain, "wiki", "alias")))
+	rs, err := Query(brain, QueryOptions{Query: "zqrawonly", Wing: "alias", Limit: 10})
+	require.NoError(t, err)
+	assert.Empty(t, rs)
+}
+
+// With a hall the search root is wiki/<wing>/<hall>; a symlinked <wing> with
+// a real <hall> directory under its target was followed (PR #166 round 2).
+func TestQueryDoesNotFollowASymlinkedWingUnderAWingAndHallRoot(t *testing.T) {
+	brain, _, _ := searchBrain(t)
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "raw", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "raw", "facts", "r.md"), []byte("# r\n\nzqrawhall"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(brain, "wiki", "alias")))
+	rs, err := Query(brain, QueryOptions{Query: "zqrawhall", Wing: "alias", Hall: "facts", Limit: 10})
+	require.NoError(t, err)
+	assert.Empty(t, rs)
+}
+
 // swapInto keeps renaming a regular note, and either a symlink to outside or
 // a FIFO, into path. Each FIFO has a writer held open (as any local process
 // can): a FIFO with no writer reads EOF at once, which would let a reader

ingestion/internal/vectorstore/sync.go

@@ -2,12 +2,15 @@ package vectorstore
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"io/fs"
 	"log/slog"
-	"os"
-	"path/filepath"
+	"path"
 	"strings"
 	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 )
 
 // Embedder produces dense vectors. The embed package's Client satisfies
@@ -90,31 +93,38 @@ func Sync(ctx context.Context, brainDir string, store Store, embedder Embedder)
 	}
 	seenParents := make(map[string]struct{})
 
+	// Through the brain root, regular files only (hyperguild#157): the brain
+	// is a Syncthing folder, and os.ReadFile followed a synced symlink into
+	// the embeddings and blocked on a FIFO.
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return res, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+
 	for _, sub := range scanDirs {
-		root := filepath.Join(brainDir, sub)
-		if _, err := os.Stat(root); os.IsNotExist(err) {
+		if _, err := bfs.Lstat(sub); errors.Is(err, fs.ErrNotExist) {
 			continue
 		}
-
-		err = filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
-			if err != nil {
-				return err
+		// Any other walk error, including a scan root that is a symlink,
+		// aborts the run below.
+		var walkErr error
+		onErr := func(rel string, err error) {
+			if walkErr == nil {
+				walkErr = fmt.Errorf("%s: %w", rel, err)
 			}
-			if d.IsDir() || !strings.HasSuffix(path, ".md") || d.Name() == "_index.md" {
+		}
+		err = bfs.WalkRegular(sub, func(relSlash string) error {
+			if !strings.HasSuffix(relSlash, ".md") || path.Base(relSlash) == "_index.md" {
 				return nil
 			}
-			rel, err := filepath.Rel(brainDir, path)
-			if err != nil {
-				return err
-			}
-			relSlash := filepath.ToSlash(rel)
 			seenParents[relSlash] = struct{}{}
 
 			if ps, ok := parents[relSlash]; ok {
 				// File already has chunks in the store. Re-embed only when
 				// the file has been edited since the oldest chunk was
 				// written. Tolerate clock skew with a sub-second grace.
-				info, statErr := d.Info()
+				info, statErr := bfs.Lstat(relSlash)
 				if statErr != nil {
 					res.Errors = append(res.Errors, fmt.Errorf("stat %s: %w", relSlash, statErr))
 					return nil
@@ -132,7 +142,7 @@ func Sync(ctx context.Context, brainDir string, store Store, embedder Embedder)
 				}
 			}
 
-			content, readErr := os.ReadFile(path)
+			content, readErr := bfs.ReadRegular(relSlash)
 			if readErr != nil {
 				res.Errors = append(res.Errors, fmt.Errorf("read %s: %w", relSlash, readErr))
 				return nil
@@ -151,7 +161,12 @@ func Sync(ctx context.Context, brainDir string, store Store, embedder Embedder)
 				res.Added++
 			}
 			return nil
-		})
+		}, onErr)
+		if err == nil {
+			err = walkErr
+		}
+		// Abort before the delete pass: an incomplete walk would leave
+		// seenParents short and delete chunks of files that still exist.
 		if err != nil {
 			return res, fmt.Errorf("walk %s: %w", sub, err)
 		}

ingestion/internal/vectorstore/sync_root_test.go

@@ -0,0 +1,126 @@
+package vectorstore_test
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/vectorstore"
+)
+
+// recordingEmbedder keeps every text it was asked to embed.
+type recordingEmbedder struct {
+	mu    sync.Mutex
+	texts []string
+}
+
+func (e *recordingEmbedder) Embed(_ context.Context, text string) ([]float32, error) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	e.texts = append(e.texts, text)
+	return []float32{1}, nil
+}
+
+func (e *recordingEmbedder) all() string {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	return strings.Join(e.texts, "\n")
+}
+
+// hyperguild#157 slice 3: Sync walked wiki/ and knowledge/ and read each .md
+// with os.ReadFile, so a symlinked note had its target embedded and served by
+// semantic search, and a FIFO stalled the sync.
+func TestSyncRefusesSymlinkedNotesAndSurvivesSwapRaces(t *testing.T) {
+	brain := t.TempDir()
+	writeNote(t, brain, "wiki/w/facts/ok.md", "inside note")
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(brain, "wiki", "w", "facts", "leak.md")))
+
+	emb := &recordingEmbedder{}
+	store := &stubStore{}
+	_, err := vectorstore.Sync(context.Background(), brain, store, emb)
+	require.NoError(t, err)
+	assert.Contains(t, emb.all(), "inside note", "positive control: the regular note is embedded")
+	assert.NotContains(t, emb.all(), brainfstest.Sentinel)
+	for p := range store.upserts {
+		assert.NotContains(t, p, "leak.md")
+	}
+
+	p := filepath.Join(brain, "knowledge", "r.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(p), 0o755))
+	sync := func() string {
+		e := &recordingEmbedder{}
+		_, _ = vectorstore.Sync(context.Background(), brain, &stubStore{}, e)
+		return e.all()
+	}
+	brainfstest.AssertNoLeak(t, p, "inside", 1500*time.Millisecond, sync)
+	brainfstest.AssertNoHang(t, p, "inside", 1500*time.Millisecond, 6*time.Second, func() { _ = sync() })
+}
+
+// Chunks embedded from a symlinked note before this fix are deleted: the
+// note is no longer seen, so the delete pass drops its rows.
+func TestSyncDeletesChunksOfASymlinkedNote(t *testing.T) {
+	brain := t.TempDir()
+	writeNote(t, brain, "wiki/w/facts/ok.md", "inside note")
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(brain, "wiki", "w", "facts", "leak.md")))
+	store := &stubStore{known: map[string]time.Time{
+		"wiki/w/facts/leak.md#0001": {},
+		"wiki/w/facts/ok.md#0001":   {},
+	}}
+	_, err := vectorstore.Sync(context.Background(), brain, store, &recordingEmbedder{})
+	require.NoError(t, err)
+	assert.Equal(t, []string{"wiki/w/facts/leak.md#0001"}, store.deletes)
+}
+
+// A walk error aborts Sync before the delete pass, so chunks of files the
+// walk could not see are kept.
+func TestSyncAbortsBeforeDeletingWhenASubdirIsUnreadable(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root ignores directory permissions")
+	}
+	brain := t.TempDir()
+	writeNote(t, brain, "wiki/w/facts/ok.md", "inside note")
+	locked := filepath.Join(brain, "wiki", "w")
+	require.NoError(t, os.Chmod(locked, 0o000))
+	t.Cleanup(func() { _ = os.Chmod(locked, 0o755) })
+	store := &stubStore{known: map[string]time.Time{"wiki/w/facts/ok.md#0001": {}}}
+	_, err := vectorstore.Sync(context.Background(), brain, store, &recordingEmbedder{})
+	assert.Error(t, err)
+	assert.Empty(t, store.deletes)
+}
+
+// A scan root that is a symlink inside the brain (knowledge -> .) was
+// followed by fs.WalkDir, aliasing raw/, sessions/ and root files into the
+// index. Sync now aborts on it, before embedding or deleting anything.
+func TestSyncAbortsOnASymlinkedScanRoot(t *testing.T) {
+	brain := t.TempDir()
+	writeNote(t, brain, "wiki/w/a.md", "wiki note")
+	writeNote(t, brain, "sessions/s1.md", "session note")
+	require.NoError(t, os.Symlink(".", filepath.Join(brain, "knowledge")))
+	emb := &recordingEmbedder{}
+	store := &stubStore{known: map[string]time.Time{"wiki/w/a.md#0001": {}}}
+	_, err := vectorstore.Sync(context.Background(), brain, store, emb)
+	assert.Error(t, err)
+	assert.NotContains(t, emb.all(), "session note")
+	for p := range store.upserts {
+		assert.False(t, strings.HasPrefix(p, "knowledge/"), "upserted %s", p)
+	}
+	assert.Empty(t, store.deletes)
+}
+
+// A missing scan root is skipped; the other root still syncs.
+func TestSyncSkipsAMissingScanRoot(t *testing.T) {
+	brain := t.TempDir()
+	writeNote(t, brain, "wiki/w/a.md", "wiki note")
+	emb := &recordingEmbedder{}
+	_, err := vectorstore.Sync(context.Background(), brain, &stubStore{}, emb)
+	require.NoError(t, err)
+	assert.Contains(t, emb.all(), "wiki note")
+}

ingestion/internal/wiki/index.go

@@ -7,6 +7,7 @@ import (
 	"path/filepath"
 	"strings"
 
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/textutil"
 )
 
@@ -16,6 +17,11 @@ func RebuildIndex(brainDir, date string) error {
 	if err != nil {
 		return fmt.Errorf("load inventory: %w", err)
 	}
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
 
 	total := len(inv[PageTypeConcept]) + len(inv[PageTypeEntity]) + len(inv[PageTypeSource])
 	var sb strings.Builder
@@ -34,7 +40,7 @@ func RebuildIndex(brainDir, date string) error {
 		label := strings.ToUpper(string(pt)[:1]) + string(pt)[1:]
 		fmt.Fprintf(&sb, "## %s\n\n", label)
 		for _, e := range entries {
-			summary := pageFirstSentence(brainDir, e)
+			summary := pageFirstSentence(bfs, e)
 			if summary != "" {
 				fmt.Fprintf(&sb, "- [[%s|%s]] — %s\n", e.Slug, e.Title, summary)
 			} else {
@@ -48,9 +54,10 @@ func RebuildIndex(brainDir, date string) error {
 	return os.WriteFile(dest, []byte(sb.String()), 0o644)
 }
 
-func pageFirstSentence(brainDir string, e Entry) string {
-	path := filepath.Join(brainDir, "wiki", string(e.Type), e.Slug+".md")
-	content, err := os.ReadFile(path)
+// pageFirstSentence reads the page through the brain root, regular files
+// only (hyperguild#157).
+func pageFirstSentence(bfs *brainfs.Brain, e Entry) string {
+	content, err := bfs.ReadRegular("wiki/" + string(e.Type) + "/" + e.Slug + ".md")
 	if err != nil {
 		return ""
 	}

ingestion/internal/wiki/inventory.go

@@ -3,36 +3,45 @@ package wiki
 
 import (
 	"bufio"
+	"bytes"
+	"errors"
 	"fmt"
-	"os"
-	"path/filepath"
+	"io/fs"
 	"strings"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 )
 
 // LoadInventory walks brain/wiki/ and returns all pages grouped by type.
-// Missing subdirectories are silently skipped.
+// Missing subdirectories are silently skipped. Pages are listed and read
+// through the brain root, regular files only (hyperguild#157); a type
+// directory that is a symlink is an error.
 func LoadInventory(brainDir string) (map[PageType][]Entry, error) {
 	result := map[PageType][]Entry{
 		PageTypeConcept: {},
 		PageTypeEntity:  {},
 		PageTypeSource:  {},
 	}
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return nil, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
 	for pt := range result {
-		dir := filepath.Join(brainDir, "wiki", string(pt))
-		entries, err := os.ReadDir(dir)
-		if os.IsNotExist(err) {
+		dir := "wiki/" + string(pt)
+		names, err := bfs.ReadDirRegular(dir)
+		if errors.Is(err, fs.ErrNotExist) {
 			continue
 		}
 		if err != nil {
 			return nil, fmt.Errorf("read dir %s: %w", dir, err)
 		}
-		for _, e := range entries {
-			if e.IsDir() || !strings.HasSuffix(e.Name(), ".md") {
+		for _, name := range names {
+			if !strings.HasSuffix(name, ".md") {
 				continue
 			}
-			slug := strings.TrimSuffix(e.Name(), ".md")
-			path := filepath.Join(dir, e.Name())
-			title, aliases := readFrontmatter(path, slug)
+			slug := strings.TrimSuffix(name, ".md")
+			title, aliases := readFrontmatter(bfs, dir+"/"+name, slug)
 			result[pt] = append(result[pt], Entry{Slug: slug, Title: title, Aliases: aliases, Type: pt})
 		}
 	}
@@ -41,15 +50,14 @@ func LoadInventory(brainDir string) (map[PageType][]Entry, error) {
 
 // readFrontmatter extracts title and aliases from YAML frontmatter.
 // Falls back to slug for title and empty aliases on any error.
-func readFrontmatter(path, fallbackSlug string) (title string, aliases []string) {
+func readFrontmatter(bfs *brainfs.Brain, rel, fallbackSlug string) (title string, aliases []string) {
 	title = fallbackSlug
-	f, err := os.Open(path)
+	content, err := bfs.ReadRegular(rel)
 	if err != nil {
 		return
 	}
-	defer f.Close() //nolint:errcheck
 
-	scanner := bufio.NewScanner(f)
+	scanner := bufio.NewScanner(bytes.NewReader(content))
 	inFM := false
 	inAliases := false
 	for scanner.Scan() {

ingestion/internal/wiki/root_test.go

@@ -0,0 +1,79 @@
+package wiki
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest"
+)
+
+// hyperguild#157 slice 4: LoadInventory listed wiki/<type>/ with os.ReadDir
+// and opened each .md by path, so a symlinked page put the target's title and
+// aliases into the inventory (and the LLM prompts built from it), and a FIFO
+// hung it. RebuildIndex read first sentences the same way.
+func TestLoadInventoryRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) {
+	brain := t.TempDir()
+	dir := filepath.Join(brain, "wiki", "concepts")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "ok.md"), []byte("---\ntitle: zqinside\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(dir, "leak.md")))
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "s.md"), filepath.Join(dir, "inlink.md")))
+
+	inv, err := LoadInventory(brain)
+	require.NoError(t, err)
+	got := fmt.Sprintf("%+v", inv)
+	assert.Contains(t, got, "zqinside", "positive control")
+	assert.NotContains(t, got, brainfstest.Sentinel)
+	assert.NotContains(t, got, "leak", "a symlinked page is not listed")
+	assert.NotContains(t, got, "inlink", "a page linked to another brain file is not listed")
+
+	p := filepath.Join(dir, "r.md")
+	read := func() string {
+		inv, _ := LoadInventory(brain)
+		return fmt.Sprintf("%+v", inv)
+	}
+	brainfstest.AssertNoLeak(t, p, "---\ntitle: zqinside\n---\n", 1500*time.Millisecond, read)
+	brainfstest.AssertNoLeakFrom(t, p, "---\ntitle: zqinside\n---\n", inBrain, 1500*time.Millisecond, read)
+	brainfstest.AssertNoHang(t, p, "---\ntitle: zqinside\n---\n", 1500*time.Millisecond, 6*time.Second, func() { _ = read() })
+}
+
+func TestLoadInventoryReturnsErrNotRegularForASymlinkedTypeDir(t *testing.T) {
+	brain := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "raw"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "raw", "r.md"), []byte("---\ntitle: zqrawonly\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(brain, "wiki", "concepts")))
+	inv, err := LoadInventory(brain)
+	require.ErrorIs(t, err, brainfs.ErrNotRegular)
+	assert.NotContains(t, fmt.Sprintf("%+v", inv), "zqrawonly")
+}
+
+func TestRebuildIndexDoesNotReadAPageSwappedForASymlink(t *testing.T) {
+	brain := t.TempDir()
+	dir := filepath.Join(brain, "wiki", "concepts")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	p := filepath.Join(dir, "r.md")
+	require.NoError(t, os.WriteFile(p, []byte("---\ntitle: R\n---\nzqinside sentence.\n"), 0o644))
+	require.NoError(t, RebuildIndex(brain, "2026-10-04"))
+	idx, err := os.ReadFile(filepath.Join(brain, "wiki", "index.md"))
+	require.NoError(t, err)
+	require.Contains(t, string(idx), "zqinside", "positive control: the summary is read")
+
+	read := func() string {
+		_ = RebuildIndex(brain, "2026-10-04")
+		b, _ := os.ReadFile(filepath.Join(brain, "wiki", "index.md"))
+		return string(b)
+	}
+	brainfstest.AssertNoLeak(t, p, "---\ntitle: R\n---\nzqinside sentence.\n", 1500*time.Millisecond, read)
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	brainfstest.AssertNoLeakFrom(t, p, "---\ntitle: R\n---\nzqinside sentence.\n", inBrain, 1500*time.Millisecond, read)
+	brainfstest.AssertNoHang(t, p, "---\ntitle: R\n---\nzqinside sentence.\n", 1500*time.Millisecond, 6*time.Second, func() { _ = read() })
+}