fix: pipeline, backfill, watcher and archive writes go through the brain root (#158 part B)

The remaining writers created or rewrote brain files by path:
- pipeline buildAndWrite: os.MkdirAll + os.WriteFile of every page.
- BackfillRefs: os.WriteFile of each concept page; a page swapped for a
  symlink after the read was written through (the race test overwrote an
  in-brain target before this change).
- watcher: the raw/processed and raw/failed archive copies (os.Create),
  the .processed/.failed markers and the log.md entry (os.OpenFile).
- cmd/server: the claude-session archive.

All now go through brainfs PutRegular/AppendRegular (new package-level
PutFile/AppendFile for one-off writers: the watcher's call-site lint bans
.Open calls in that file so raw/ reads stay on OpenRegular).

Stacked on #189 (needs PutRegular/AppendRegular).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

ingestion/cmd/server/main.go

@@ -17,6 +17,7 @@ import (
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/audit"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/capturehttp"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
@@ -89,11 +90,15 @@ func (s *claudeSink) Ingest(ctx context.Context, b claudewatcher.Batch) error {
 		sb.WriteString("\n\n")
 	}
 	slug := "session-" + b.Host + "-" + b.SessionID
-	dest := filepath.Join(s.brainDir, "archive", "claude-sessions", b.Host, slug+".md")
-	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
-		return fmt.Errorf("create claude-sessions archive dir: %w", err)
+	dest := "archive/claude-sessions/" + b.Host + "/" + slug + ".md"
+	// Written through the brain root, never through a symlinked directory
+	// or file (hyperguild#158).
+	bfs, err := brainfs.Open(s.brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
 	}
-	if err := os.WriteFile(dest, []byte(sb.String()), 0o644); err != nil {
+	defer func() { _ = bfs.Close() }()
+	if err := bfs.PutRegular(dest, []byte(sb.String())); err != nil {
 		return fmt.Errorf("write claude session archive: %w", err)
 	}
 	s.logger.Debug("claude session archived (non-indexed)", "path", dest)

ingestion/go.mod

@@ -68,7 +68,7 @@ require (
 	github.com/segmentio/asm v1.2.0 // indirect
 	golang.org/x/crypto v0.51.0 // indirect
 	golang.org/x/sync v0.21.0 // indirect
-	golang.org/x/sys v0.45.0 // indirect
+	golang.org/x/sys v0.45.0
 	golang.org/x/text v0.39.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1
 )

ingestion/internal/api/handler.go

@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/claim"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/search"
@@ -227,14 +228,22 @@ func writeHallNote(brainDir string, opts WriteNoteOptions) (string, error) {
 	// The directory is created only once the note is known to be writable:
 	// a refused write leaves nothing behind, not even an empty hall dir
 	// (brain#21; provenance refusal joins the envelope refusal here).
-	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
-		return "", fmt.Errorf("create hall dir: %w", err)
+	// Created through the brain root, never through a symlinked wing or
+	// hall directory (hyperguild#188).
+	rel, err := filepath.Rel(brainDir, dest)
+	if err != nil {
+		return "", fmt.Errorf("note path: %w", err)
 	}
-	if err := os.WriteFile(dest, []byte(final), 0o644); err != nil {
+	rel = filepath.ToSlash(rel)
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return "", fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	if err := bfs.PutRegular(rel, []byte(final)); err != nil {
 		return "", fmt.Errorf("write: %w", err)
 	}
-	rel, _ := filepath.Rel(brainDir, dest)
-	return filepath.ToSlash(rel), nil
+	return rel, nil
 }
 
 // scalarValues flattens frontmatter fields to key -> scalar value for

ingestion/internal/api/promote.go

@@ -127,18 +127,16 @@ func PromoteNote(brainDir string, opts PromoteOptions) (string, error) {
 	}
 	fm.set("promoted_at", now)
 
-	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
-		return "", fmt.Errorf("create wing dir: %w", err)
-	}
-	// Write-then-delete: the source survives any write failure.
+	// Write-then-delete: the source survives any write failure. Both go
+	// through the brain root (hyperguild#188).
 	promoted, err := StampProvenance(fm.render()+body, opts.Origin, opts.WrittenBy)
 	if err != nil {
 		return "", err
 	}
-	if err := os.WriteFile(dest, []byte(promoted), 0o644); err != nil {
+	if _, err := putBrainFile(brainDir, dest, []byte(promoted)); err != nil {
 		return "", fmt.Errorf("write promoted note: %w", err)
 	}
-	if err := os.Remove(src); err != nil {
+	if err := removeBrainFile(brainDir, src); err != nil {
 		return "", fmt.Errorf("promoted note written but source removal failed: %w", err)
 	}
 
@@ -196,14 +194,12 @@ func RejectNote(brainDir string, opts RejectOptions) (string, error) {
 		fm.set("reject_reason", opts.Reason)
 	}
 
-	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
-		return "", fmt.Errorf("create rejected dir: %w", err)
-	}
-	// Write-then-delete: the source survives any write failure.
-	if err := os.WriteFile(dest, []byte(fm.render()+body), 0o644); err != nil {
+	// Write-then-delete: the source survives any write failure. Both go
+	// through the brain root (hyperguild#188).
+	if _, err := putBrainFile(brainDir, dest, []byte(fm.render()+body)); err != nil {
 		return "", fmt.Errorf("write rejected note: %w", err)
 	}
-	if err := os.Remove(src); err != nil {
+	if err := removeBrainFile(brainDir, src); err != nil {
 		return "", fmt.Errorf("rejected note written but source removal failed: %w", err)
 	}
 

ingestion/internal/api/promote_redirect_test.go

@@ -0,0 +1,60 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// hyperguild#188: promote and reject wrote the destination with
+// os.MkdirAll + os.WriteFile by path, so a symlinked wing (promote) or a
+// symlinked raw/rejected (reject) redirected the note; the raw source was
+// then removed.
+func TestPromoteAndRejectRefuseASymlinkedDestinationDirectory(t *testing.T) {
+	brain := t.TempDir()
+	outside := t.TempDir()
+	raw := filepath.Join(brain, "raw")
+	require.NoError(t, os.MkdirAll(raw, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(raw, "2026-10-05-n.md"), []byte("---\ntitle: n\n---\nbody\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(outside, filepath.Join(brain, "wiki", "lw")))
+	require.NoError(t, os.Symlink(outside, filepath.Join(raw, "rejected")))
+
+	_, err := api.PromoteNote(brain, api.PromoteOptions{Filename: "2026-10-05-n.md", Wing: "lw", Hall: "facts"})
+	assert.Error(t, err)
+	_, err = api.RejectNote(brain, api.RejectOptions{Filename: "2026-10-05-n.md"})
+	assert.Error(t, err)
+	ents, _ := os.ReadDir(outside)
+	assert.Empty(t, ents, "a note was written outside the brain")
+	_, err = os.Stat(filepath.Join(raw, "2026-10-05-n.md"))
+	assert.NoError(t, err, "the raw source is kept when the write is refused")
+
+	require.NoError(t, os.Remove(filepath.Join(raw, "rejected")))
+	_, err = api.PromoteNote(brain, api.PromoteOptions{Filename: "2026-10-05-n.md", Wing: "w", Hall: "facts"})
+	require.NoError(t, err, "positive control: promote into a real wing")
+}
+
+// StampProvenanceFile read and rewrote the note by path (provenance.ApplyFile).
+func TestStampProvenanceFileRefusesANoteBehindASymlinkedDirectory(t *testing.T) {
+	brain := t.TempDir()
+	victim := filepath.Join(brain, "raw", "facts", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("---\ntitle: v\n---\nuntouched\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki", "w"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "facts"), filepath.Join(brain, "wiki", "w", "alias")))
+	assert.Error(t, api.StampProvenanceFile(brain, "wiki/w/alias/v.md", "static", "x"))
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "---\ntitle: v\n---\nuntouched\n", string(got))
+
+	real := filepath.Join(brain, "wiki", "w", "facts", "r.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(real), 0o755))
+	require.NoError(t, os.WriteFile(real, []byte("---\ntitle: r\n---\nbody\n"), 0o644))
+	require.NoError(t, api.StampProvenanceFile(brain, "wiki/w/facts/r.md", "static", "x"), "positive control")
+	got, _ = os.ReadFile(real)
+	assert.Contains(t, string(got), "written_by: x")
+}

ingestion/internal/api/provenance.go

@@ -1,6 +1,10 @@
 package api
 
 import (
+	"fmt"
+	"path/filepath"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/provenance"
 )
 
@@ -11,11 +15,62 @@ func StampProvenance(content, origin, writtenBy string) (string, error) {
 	return provenance.Apply(content, provenance.Stamp{Origin: origin, WrittenBy: writtenBy})
 }
 
-// StampProvenanceFile applies StampProvenance to a brain-relative note path.
+// StampProvenanceFile applies StampProvenance to a brain-relative note path,
+// read and rewritten through the brain root (hyperguild#158).
 func StampProvenanceFile(brainDir, relPath, origin, writtenBy string) error {
-	_, abs, err := resolveWithin(brainDir, relPath)
+	rel, _, err := resolveWithin(brainDir, relPath)
 	if err != nil {
 		return err
 	}
-	return provenance.ApplyFile(abs, provenance.Stamp{Origin: origin, WrittenBy: writtenBy})
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	b, err := bfs.ReadRegular(rel)
+	if err != nil {
+		return fmt.Errorf("read for provenance: %w", err)
+	}
+	out, err := provenance.Apply(string(b), provenance.Stamp{Origin: origin, WrittenBy: writtenBy})
+	if err != nil {
+		return err
+	}
+	if out == string(b) {
+		return nil
+	}
+	if err := bfs.WriteRegular(rel, []byte(out)); err != nil {
+		return fmt.Errorf("write provenance: %w", err)
+	}
+	return nil
+}
+
+// putBrainFile creates or replaces the file at abs (inside brainDir) through
+// the brain root, never through a symlinked directory or file (#188).
+func putBrainFile(brainDir, abs string, data []byte) (string, error) {
+	rel, err := filepath.Rel(brainDir, abs)
+	if err != nil {
+		return "", err
+	}
+	rel = filepath.ToSlash(rel)
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return "", fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	return rel, bfs.PutRegular(rel, data)
+}
+
+// removeBrainFile removes the file at abs (inside brainDir) through the
+// brain root.
+func removeBrainFile(brainDir, abs string) error {
+	rel, err := filepath.Rel(brainDir, abs)
+	if err != nil {
+		return err
+	}
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	return bfs.Remove(filepath.ToSlash(rel))
 }

ingestion/internal/api/readnote_root_test.go

@@ -23,6 +23,13 @@ func TestReadNoteRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) {
 	_, body, _, err := api.ReadNote(brain, "wiki/w/facts/leak.md")
 	assert.Error(t, err)
 	assert.NotContains(t, body, brainfstest.Sentinel)
+	// A link to a file elsewhere in the brain: os.Root allows it, only the
+	// regular-file check refuses it (hyperguild#171).
+	brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md")))
+	_, body, _, err = api.ReadNote(brain, "wiki/w/facts/inlink.md")
+	assert.Error(t, err)
+	assert.NotContains(t, body, brainfstest.Sentinel)
 
 	p := filepath.Join(facts, "r.md")
 	require.NoError(t, os.WriteFile(p, []byte("---\nx: y\n---\ninside"), 0o644))
@@ -39,5 +46,7 @@ func TestReadNoteRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) {
 		return s
 	}
 	brainfstest.AssertNoLeak(t, p, "---\nx: y\n---\ninside", 1500*time.Millisecond, read)
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	brainfstest.AssertNoLeakFrom(t, p, "---\nx: y\n---\ninside", inBrain, 1500*time.Millisecond, read)
 	brainfstest.AssertNoHang(t, p, "---\nx: y\n---\ninside", 1500*time.Millisecond, 6*time.Second, func() { _ = read() })
 }

ingestion/internal/api/update_redirect_test.go

@@ -0,0 +1,36 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+)
+
+// hyperguild#173: a directory symlink inside wiki/ that points elsewhere in
+// the brain redirected brain_update's write (os.Root follows in-root
+// intermediate symlinks). Every directory above the note must be real.
+func TestUpdateNoteRefusesANoteBehindASymlinkedDirectory(t *testing.T) {
+	brain := t.TempDir()
+	victim := filepath.Join(brain, "raw", "facts", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("---\ntitle: v\n---\nuntouched\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki", "w"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "facts"), filepath.Join(brain, "wiki", "w", "alias")))
+
+	_, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: "wiki/w/alias/v.md", Content: "replaced"})
+	assert.ErrorIs(t, err, brainfs.ErrNotRegular)
+	got, _ := os.ReadFile(victim)
+	assert.Contains(t, string(got), "untouched")
+
+	real := filepath.Join(brain, "wiki", "w", "facts", "r.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(real), 0o755))
+	require.NoError(t, os.WriteFile(real, []byte("---\ntitle: r\n---\nold\n"), 0o644))
+	_, _, _, err = api.UpdateNote(brain, api.UpdateNoteOptions{Path: "wiki/w/facts/r.md", Content: "new"})
+	require.NoError(t, err, "positive control: a note in a real directory is updated")
+}

ingestion/internal/api/write_redirect_test.go

@@ -0,0 +1,43 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// hyperguild#188: brain_write created a new note with os.MkdirAll +
+// os.WriteFile by path, so a symlinked wing directory redirected the note
+// elsewhere in the brain or outside it.
+func TestWriteNoteRefusesASymlinkedWing(t *testing.T) {
+	for name, target := range map[string]func(t *testing.T, brain string) string{
+		"in-brain": func(t *testing.T, brain string) string {
+			require.NoError(t, os.MkdirAll(filepath.Join(brain, "raw"), 0o755))
+			return filepath.Join("..", "raw")
+		},
+		"outside": func(t *testing.T, _ string) string { return t.TempDir() },
+	} {
+		t.Run(name, func(t *testing.T) {
+			brain := t.TempDir()
+			require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki"), 0o755))
+			link := target(t, brain)
+			require.NoError(t, os.Symlink(link, filepath.Join(brain, "wiki", "lw")))
+			_, err := api.WriteNote(brain, api.WriteNoteOptions{Wing: "lw", Hall: "facts", Filename: "n", Content: "learning"})
+			assert.Error(t, err)
+			resolved := link
+			if !filepath.IsAbs(resolved) {
+				resolved = filepath.Join(brain, "wiki", link)
+			}
+			_, serr := os.Stat(filepath.Join(resolved, "facts"))
+			assert.True(t, os.IsNotExist(serr), "a hall was created at the link's target")
+
+			_, err = api.WriteNote(brain, api.WriteNoteOptions{Wing: "w", Hall: "facts", Filename: "n", Content: "learning"})
+			require.NoError(t, err, "positive control: a real wing is written")
+		})
+	}
+}

ingestion/internal/brain/index.go

@@ -7,7 +7,6 @@ import (
 	"fmt"
 	"io"
 	"io/fs"
-	"os"
 	"path/filepath"
 	"sort"
 	"strings"
@@ -63,8 +62,10 @@ func BuildWingIndex(brainDir, wing string) error {
 		fmt.Fprintf(&b, "| %s | [%s](%s/%s.md) | %s |\n", e.Hall, e.Title, e.Hall, e.Slug, e.Created)
 	}
 
-	dest := filepath.Join(wingDir, "_index.md")
-	return os.WriteFile(dest, []byte(b.String()), 0o644)
+	// Written through the brain root, never through a symlinked _index.md
+	// (hyperguild#158).
+	_ = wingDir
+	return bfs.PutRegular("wiki/"+w+"/_index.md", []byte(b.String()))
 }
 
 // BuildAllWingIndexes regenerates _index.md for every wing under brain/wiki/.

ingestion/internal/brain/tunnel.go

@@ -5,7 +5,6 @@ import (
 	"errors"
 	"fmt"
 	"io/fs"
-	"os"
 	"path"
 	"path/filepath"
 	"strings"
@@ -176,35 +175,23 @@ func logFuzzyCandidates(brainDir, sourcePath string, cs []TunnelCandidate) error
 	if len(cs) == 0 {
 		return nil
 	}
-	rawDir := filepath.Join(brainDir, "raw")
-	if err := os.MkdirAll(rawDir, 0o755); err != nil {
-		return err
-	}
-	stamp := time.Now().UTC().Format("2006-01-02")
-	path := filepath.Join(rawDir, "tunnel-candidates-"+stamp+".md")
-	existed := fileExists(path)
-	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
+	// Appended through the brain root, never through a symlinked raw/ or
+	// log file (hyperguild#158).
+	bfs, err := brainfs.Open(brainDir)
 	if err != nil {
-		return err
-	}
-	defer func() { _ = f.Close() }()
-	if !existed {
-		if _, err := f.WriteString("# Tunnel candidates " + stamp + "\n\nFuzzy cross-wing matches surfaced by AutoTunnel. Review and promote to a tunnel via `brain_tunnel` if relevant.\n\n"); err != nil {
-			return err
+		return fmt.Errorf("open brain: %w", err)
 	}
+	defer func() { _ = bfs.Close() }()
+	stamp := time.Now().UTC().Format("2006-01-02")
+	rel := "raw/tunnel-candidates-" + stamp + ".md"
+	var buf strings.Builder
+	if _, err := bfs.Lstat(rel); errors.Is(err, fs.ErrNotExist) {
+		buf.WriteString("# Tunnel candidates " + stamp + "\n\nFuzzy cross-wing matches surfaced by AutoTunnel. Review and promote to a tunnel via `brain_tunnel` if relevant.\n\n")
 	}
 	for _, c := range cs {
-		line := fmt.Sprintf("- `%s` ↔ `%s` (term: %q)\n", sourcePath, c.TargetPath, c.MatchedTerm)
-		if _, err := f.WriteString(line); err != nil {
-			return err
+		fmt.Fprintf(&buf, "- `%s` ↔ `%s` (term: %q)\n", sourcePath, c.TargetPath, c.MatchedTerm)
 	}
-	}
-	return nil
-}
-
-func fileExists(p string) bool {
-	_, err := os.Stat(p)
-	return err == nil
+	return bfs.AppendRegular(rel, []byte(buf.String()))
 }
 
 // WriteTunnel appends a bidirectional wikilink between sourcePath and

ingestion/internal/brain/tunnel_redirect_test.go

@@ -0,0 +1,38 @@
+package brain_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+)
+
+// hyperguild#173: brain_tunnel's write followed a directory symlink inside
+// wiki/ that points elsewhere in the brain.
+func TestWriteTunnelRefusesATargetBehindASymlinkedDirectory(t *testing.T) {
+	b := t.TempDir()
+	src := filepath.Join(b, "wiki", "a", "facts", "s.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(src), 0o755))
+	require.NoError(t, os.WriteFile(src, []byte("x\n"), 0o644))
+	victim := filepath.Join(b, "raw", "facts", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "b"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "facts"), filepath.Join(b, "wiki", "b", "facts")))
+
+	assert.ErrorIs(t, brain.WriteTunnel(b, "wiki/a/facts/s.md", "wiki/b/facts/v.md"), brainfs.ErrNotRegular)
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched\n", string(got))
+	got, _ = os.ReadFile(src)
+	assert.Equal(t, "x\n", string(got), "the source is not rewritten either")
+
+	real := filepath.Join(b, "wiki", "c", "facts", "t.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(real), 0o755))
+	require.NoError(t, os.WriteFile(real, []byte("t\n"), 0o644))
+	require.NoError(t, brain.WriteTunnel(b, "wiki/a/facts/s.md", "wiki/c/facts/t.md"), "positive control: a tunnel between real directories is written")
+}

ingestion/internal/brain/writers_redirect_test.go

@@ -0,0 +1,52 @@
+package brain_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+)
+
+// hyperguild#158: BuildWingIndex wrote wiki/<wing>/_index.md with
+// os.WriteFile, so a symlinked _index.md was written through.
+func TestBuildWingIndexDoesNotWriteThroughASymlinkedIndex(t *testing.T) {
+	b := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "w", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(b, "wiki", "w", "facts", "n.md"), []byte("---\ntitle: zqn\n---\n"), 0o644))
+	victim := filepath.Join(b, "raw", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "v.md"), filepath.Join(b, "wiki", "w", "_index.md")))
+	assert.Error(t, brain.BuildWingIndex(b, "w"))
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched", string(got))
+
+	require.NoError(t, os.Remove(filepath.Join(b, "wiki", "w", "_index.md")))
+	require.NoError(t, brain.BuildWingIndex(b, "w"), "positive control")
+	idx, _ := os.ReadFile(filepath.Join(b, "wiki", "w", "_index.md"))
+	assert.Contains(t, string(idx), "zqn")
+}
+
+// AutoTunnel's fuzzy-candidate log appended to raw/tunnel-candidates-*.md
+// with os.OpenFile, so a symlinked raw/ (or log file) was written through.
+func TestAutoTunnelDoesNotAppendTheCandidateLogThroughASymlinkedRaw(t *testing.T) {
+	b := t.TempDir()
+	outside := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "a", "facts"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "b", "facts"), 0o755))
+	// "zq widget" matches as a substring of "zq widgets", a fuzzy candidate.
+	require.NoError(t, os.WriteFile(filepath.Join(b, "wiki", "b", "facts", "t.md"), []byte("---\ntitle: Zq Widget\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(outside, filepath.Join(b, "raw")))
+	_ = brain.AutoTunnel(b, "wiki/a/facts/s.md", "about zq widgets")
+	ents, _ := os.ReadDir(outside)
+	assert.Empty(t, ents, "the candidate log was written outside the brain")
+
+	require.NoError(t, os.Remove(filepath.Join(b, "raw")))
+	require.NoError(t, brain.AutoTunnel(b, "wiki/a/facts/s.md", "about zq widgets"))
+	logs, _ := filepath.Glob(filepath.Join(b, "raw", "tunnel-candidates-*.md"))
+	assert.Len(t, logs, 1, "positive control: the fuzzy candidate is logged in the real raw/")
+}

ingestion/internal/brainfs/brainfs.go

@@ -104,6 +104,17 @@ func (b *Brain) ReadDirRegular(relDir string) ([]string, error) {
 	return names, nil
 }
 
+// cleanRel refuses a path that is not clean and local. realDir checks the
+// cleaned parent, so the I/O must use that same path: os.Root resolves ".."
+// after following a symlink, and a ".." after a symlinked directory would
+// otherwise pass the check and redirect the read or write.
+func cleanRel(rel string) error {
+	if rel == "" || path.Clean(rel) != rel || !filepath.IsLocal(rel) || strings.Contains(rel, "\\") {
+		return fmt.Errorf("%q: not a clean brain-relative path: %w", rel, ErrNotRegular)
+	}
+	return nil
+}
+
 // ReadDirDirs lists the real subdirectories directly in a brain-relative
 // directory, by name. Every component of relDir must be a real directory
 // (ErrNotRegular otherwise); symlinks to directories are left out.
@@ -125,9 +136,151 @@ func (b *Brain) ReadDirDirs(relDir string) ([]string, error) {
 	return names, nil
 }
 
+// PutRegular creates or replaces a regular file at a brain-relative path,
+// for creating writes (hyperguild#188, #158). Missing parent directories are
+// created one component at a time through the root, and every existing
+// component must be a real directory, so a symlinked directory cannot
+// redirect the write elsewhere in the brain or outside it. An existing file
+// is replaced only if it is regular (WriteRegular's checks); a new file is
+// created with O_EXCL and confirmed to be the file that was opened. A
+// directory swapped in after the checks is the #167 residual.
+func (b *Brain) PutRegular(rel string, data []byte) error {
+	if err := cleanRel(rel); err != nil {
+		return err
+	}
+	if err := b.mkdirReal(path.Dir(rel)); err != nil {
+		return err
+	}
+	if _, err := b.root.Lstat(rel); err == nil {
+		return b.WriteRegular(rel, data)
+	} else if !errors.Is(err, fs.ErrNotExist) {
+		return err
+	}
+	f, err := b.root.OpenFile(rel, os.O_WRONLY|os.O_CREATE|os.O_EXCL|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0o644)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = f.Close() }()
+	hfi, herr := f.Stat()
+	lfi, lerr := b.root.Lstat(rel)
+	if herr != nil || lerr != nil || !lfi.Mode().IsRegular() || !os.SameFile(lfi, hfi) {
+		return fmt.Errorf("%s: changed while creating: %w", rel, ErrNotRegular)
+	}
+	if _, err := f.Write(data); err != nil {
+		return err
+	}
+	return f.Close()
+}
+
+// AppendRegular appends data to a regular file at a brain-relative path,
+// creating it (and missing parent directories, as PutRegular does) if it is
+// absent. It writes only after confirming the path is the regular file it
+// opened, so a final symlink or special file, or one swapped in, is refused.
+func (b *Brain) AppendRegular(rel string, data []byte) error {
+	if err := cleanRel(rel); err != nil {
+		return err
+	}
+	if err := b.mkdirReal(path.Dir(rel)); err != nil {
+		return err
+	}
+	if fi, err := b.root.Lstat(rel); err == nil && !fi.Mode().IsRegular() {
+		return fmt.Errorf("%s: %w", rel, ErrNotRegular)
+	} else if err != nil && !errors.Is(err, fs.ErrNotExist) {
+		return err
+	}
+	f, err := b.root.OpenFile(rel, os.O_WRONLY|os.O_APPEND|os.O_CREATE|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0o644)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = f.Close() }()
+	hfi, herr := f.Stat()
+	lfi, lerr := b.root.Lstat(rel)
+	if herr != nil || lerr != nil || !lfi.Mode().IsRegular() || !os.SameFile(lfi, hfi) {
+		return fmt.Errorf("%s: changed while opening: %w", rel, ErrNotRegular)
+	}
+	if _, err := f.Write(data); err != nil {
+		return err
+	}
+	return f.Close()
+}
+
+// Remove removes the file at a clean brain-relative path through the root,
+// refusing a path behind a symlinked directory. A final symlink is removed
+// itself, never its target.
+func (b *Brain) Remove(rel string) error {
+	if err := b.RealParent(rel); err != nil {
+		return err
+	}
+	return b.root.Remove(rel)
+}
+
+// RealParent returns ErrNotRegular unless rel is clean and every directory
+// above it is a real directory, for writers that do their own I/O (an atomic
+// rename) but must not be redirected by a symlinked directory.
+func (b *Brain) RealParent(rel string) error {
+	if err := cleanRel(rel); err != nil {
+		return err
+	}
+	return b.realDir(path.Dir(rel))
+}
+
+// PutFile opens the brain dir as a root and calls PutRegular, for one-off
+// writers that hold no Brain.
+func PutFile(brainDir, rel string, data []byte) error {
+	b, err := Open(brainDir)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = b.Close() }()
+	return b.PutRegular(rel, data)
+}
+
+// AppendFile opens the brain dir as a root and calls AppendRegular.
+func AppendFile(brainDir, rel string, data []byte) error {
+	b, err := Open(brainDir)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = b.Close() }()
+	return b.AppendRegular(rel, data)
+}
+
+// mkdirReal makes sure every component of rel exists as a real directory,
+// creating missing ones through the root; an existing component that is
+// not a real directory is ErrNotRegular.
+func (b *Brain) mkdirReal(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 errors.Is(err, fs.ErrNotExist) {
+			if err := b.root.Mkdir(prefix, 0o755); err != nil && !errors.Is(err, fs.ErrExist) {
+				return err
+			}
+			fi, err = b.root.Lstat(prefix)
+		}
+		if err != nil {
+			return err
+		}
+		if !fi.IsDir() {
+			return fmt.Errorf("%s: component %s is not a directory: %w", rel, prefix, ErrNotRegular)
+		}
+	}
+	return 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) {
+	if err := cleanRel(rel); err != nil {
+		return nil, err
+	}
+	if err := b.realDir(path.Dir(rel)); err != nil {
+		return nil, err
+	}
 	fi, err := b.root.Lstat(rel)
 	if err != nil {
 		return nil, err
@@ -154,6 +307,12 @@ func (b *Brain) readOpened(rel string) ([]byte, error) { return b.readOpenedMax(
 // ReadRegularMax is ReadRegular with a size limit, checked on the opened
 // handle before reading (max < 0 means no limit).
 func (b *Brain) ReadRegularMax(rel string, max int64) ([]byte, error) {
+	if err := cleanRel(rel); err != nil {
+		return nil, err
+	}
+	if err := b.realDir(path.Dir(rel)); err != nil {
+		return nil, err
+	}
 	fi, err := b.root.Lstat(rel)
 	if err != nil {
 		return nil, err
@@ -256,10 +415,20 @@ func (b *Brain) WalkRegular(relDir string, fn func(rel string) error, onErr func
 // O_NOFOLLOW (verified on go1.27), so the path is Lstat-ed through the root
 // first and the opened handle must be that same file (os.SameFile), which
 // also catches a swap between the two. O_NONBLOCK keeps a FIFO from blocking
-// the open. Intermediate in-brain symlinks are still followed (os.Root keeps
-// the write inside the brain; hyperguild#167).
+// the open. Every directory above the file must be a real directory
+// (hyperguild#173); a directory swapped in after that check is the #167
+// residual.
 func (b *Brain) WriteRegular(rel string, data []byte) error {
-	rel = filepath.ToSlash(rel)
+	if err := cleanRel(rel); err != nil {
+		return err
+	}
+	// Every directory above the file must be real: os.Root follows an
+	// in-brain intermediate symlink, which would redirect the write
+	// elsewhere in the brain (hyperguild#173). A swap after this check is
+	// the #167 residual.
+	if err := b.realDir(path.Dir(rel)); err != nil {
+		return err
+	}
 	lfi, err := b.root.Lstat(rel)
 	if err != nil {
 		return err

ingestion/internal/brainfs/brainfs_test.go

@@ -218,7 +218,7 @@ func TestReadDirRegularListsOnlyRegularFilesAndRefusesSymlinkedComponents(t *tes
 // 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) {
+func TestReadRegularDoesNotReturnAnInBrainFileSwappedInBehindASymlink(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")
@@ -326,3 +326,130 @@ func TestReadDirDirsListsOnlyRealSubdirsAndRefusesSymlinkedComponents(t *testing
 	_, err = b.ReadDirDirs("alias")
 	assert.ErrorIs(t, err, ErrNotRegular)
 }
+
+// hyperguild#173: a file reached through a symlinked directory inside the
+// brain is refused for reads and writes, so a caller-supplied path cannot be
+// redirected to another part of the brain.
+func TestReadAndWriteRegularRefuseAFileBehindASymlinkedDirectory(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "raw", "v.md"), []byte("untouched"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(dir, "wiki", "alias")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	_, err = b.ReadRegular("wiki/alias/v.md")
+	assert.ErrorIs(t, err, ErrNotRegular)
+	_, err = b.ReadRegularMax("wiki/alias/v.md", 100)
+	assert.ErrorIs(t, err, ErrNotRegular)
+	assert.ErrorIs(t, b.WriteRegular("wiki/alias/v.md", []byte("x")), ErrNotRegular)
+	got, _ := os.ReadFile(filepath.Join(dir, "raw", "v.md"))
+	assert.Equal(t, "untouched", string(got))
+	got, err = b.ReadRegular("raw/v.md")
+	require.NoError(t, err, "positive control: the real path still reads")
+	assert.Equal(t, "untouched", string(got))
+}
+
+// realDir checks the cleaned parent, so the I/O must use that same clean
+// path: os.Root resolves ".." after following a symlink, and a ".." placed
+// after a symlinked directory would otherwise pass the check and redirect.
+func TestReadAndWriteRegularRefuseAPathThatIsNotClean(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "raw", "v.md"), []byte("untouched"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw", "facts"), filepath.Join(dir, "wiki", "alias")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	for _, rel := range []string{"wiki/alias/../v.md", "./raw/v.md", "raw//v.md", "/raw/v.md"} {
+		got, err := b.ReadRegular(rel)
+		assert.ErrorIs(t, err, ErrNotRegular, rel)
+		assert.NotContains(t, string(got), "untouched", rel)
+		_, err = b.ReadRegularMax(rel, 100)
+		assert.ErrorIs(t, err, ErrNotRegular, rel)
+		assert.ErrorIs(t, b.WriteRegular(rel, []byte("OVERWRITTEN")), ErrNotRegular, rel)
+	}
+	got, _ := os.ReadFile(filepath.Join(dir, "raw", "v.md"))
+	assert.Equal(t, "untouched", string(got))
+}
+
+// hyperguild#188: PutRegular creates or replaces a regular file through the
+// root. Missing parent directories are created; an existing component that
+// is not a real directory, a final symlink or special file, and an unclean
+// path are refused, and nothing is created at a link's target.
+func TestPutRegularCreatesOrReplacesOnlyThroughRealDirectories(t *testing.T) {
+	dir := t.TempDir()
+	outside := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(dir, "wiki", "inwing")))
+	require.NoError(t, os.Symlink(outside, filepath.Join(dir, "wiki", "outwing")))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "raw", "v.md"), []byte("untouched"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki", "w"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "v.md"), filepath.Join(dir, "wiki", "w", "link.md")))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(dir, "wiki", "w", "f.md"), 0o644))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	for _, rel := range []string{"wiki/inwing/facts/n.md", "wiki/outwing/facts/n.md", "wiki/w/link.md", "wiki/w/f.md", "wiki/w/../../raw/v.md", "/abs.md"} {
+		assert.ErrorIs(t, b.PutRegular(rel, []byte("x")), ErrNotRegular, rel)
+	}
+	ents, _ := os.ReadDir(outside)
+	assert.Empty(t, ents, "nothing created outside the brain")
+	_, err = os.Stat(filepath.Join(dir, "raw", "facts"))
+	assert.True(t, os.IsNotExist(err), "nothing created through the in-brain link")
+	got, _ := os.ReadFile(filepath.Join(dir, "raw", "v.md"))
+	assert.Equal(t, "untouched", string(got))
+
+	require.NoError(t, b.PutRegular("wiki/new/facts/n.md", []byte("one")), "positive control: create with missing parents")
+	got, _ = os.ReadFile(filepath.Join(dir, "wiki", "new", "facts", "n.md"))
+	assert.Equal(t, "one", string(got))
+	require.NoError(t, b.PutRegular("wiki/new/facts/n.md", []byte("two")), "positive control: replace")
+	got, _ = os.ReadFile(filepath.Join(dir, "wiki", "new", "facts", "n.md"))
+	assert.Equal(t, "two", string(got))
+}
+
+func TestAppendRegularCreatesOrAppendsOnlyThroughRealDirectories(t *testing.T) {
+	dir := t.TempDir()
+	outside := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "raw", "v.md"), []byte("untouched"), 0o644))
+	require.NoError(t, os.Symlink(outside, filepath.Join(dir, "outdir")))
+	require.NoError(t, os.Symlink("raw", filepath.Join(dir, "indir")))
+	require.NoError(t, os.Symlink(filepath.Join("raw", "v.md"), filepath.Join(dir, "log.md")))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(dir, "f.md"), 0o644))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	for _, rel := range []string{"outdir/l.md", "indir/v.md", "log.md", "f.md", "raw/../log.md"} {
+		assert.ErrorIs(t, b.AppendRegular(rel, []byte("x")), ErrNotRegular, rel)
+	}
+	ents, _ := os.ReadDir(outside)
+	assert.Empty(t, ents)
+	got, _ := os.ReadFile(filepath.Join(dir, "raw", "v.md"))
+	assert.Equal(t, "untouched", string(got))
+
+	require.NoError(t, b.AppendRegular("logs/a.md", []byte("one\n")), "positive control: create")
+	require.NoError(t, b.AppendRegular("logs/a.md", []byte("two\n")), "positive control: append")
+	got, _ = os.ReadFile(filepath.Join(dir, "logs", "a.md"))
+	assert.Equal(t, "one\ntwo\n", string(got))
+}
+
+func TestRealParentRefusesASymlinkedDirectoryOrUncleanPath(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(dir, "wiki", "alias")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+	assert.ErrorIs(t, b.RealParent("wiki/alias/x.md"), ErrNotRegular)
+	assert.ErrorIs(t, b.RealParent("wiki/../raw/x.md"), ErrNotRegular)
+	assert.NoError(t, b.RealParent("wiki/x.md"), "positive control")
+}

ingestion/internal/brainfs/brainfstest/brainfstest.go

@@ -1,8 +1,10 @@
 // Package brainfstest is the shared harness for hyperguild#157's swap-race
-// tests: it keeps swapping a regular note, a symlink to an outside file, or a
-// FIFO (with a writer held open) into a path while a reader under test loops.
-// It observes two things: no sentinel byte from the outside file reaches the
-// reader's output, and the reader returns within a timeout. It does not cover
+// tests: it keeps swapping a regular note, a symlink to a sentinel target file
+// (outside the brain, or inside it for hyperguild#171), or a FIFO (with a
+// writer held open) into a path while a reader under test loops.
+// It observes two things, over a sampled window only: no sentinel byte from
+// the target reaches the reader's output, and the reader returns within a
+// timeout. It does not cover
 // hard links, other paths into the reader, or races it does not generate.
 package brainfstest
 
@@ -18,7 +20,7 @@ import (
 	"time"
 )
 
-// Sentinel marks the outside file's contents.
+// Sentinel marks the target file's contents.
 const Sentinel = "zqbrainfssentinelonefiftyseven"
 
 // outsideContent carries Sentinel in every field a reader might extract: the
@@ -141,7 +143,7 @@ func AssertNoLeakFrom(t testing.TB, path, inside, target string, d time.Duration
 		}
 	}
 	if leaks > 0 {
-		t.Fatalf("outside file leaked %d times in %d iterations", leaks, iters)
+		t.Fatalf("symlink target %s leaked %d times in %d iterations", target, leaks, iters)
 	}
 	if n := swaps.Load(); n == 0 {
 		t.Fatalf("no symlink was swapped into %s in %d iterations: the race did not run", path, iters)

ingestion/internal/classification/classification.go

@@ -16,9 +16,10 @@
 package classification
 
 import (
+	"errors"
 	"fmt"
-	"os"
-	"path/filepath"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+	"io/fs"
 	"strings"
 
 	"gopkg.in/yaml.v3"
@@ -110,9 +111,20 @@ type rawConfig struct {
 func Load(brainDir string) (*Config, error) {
 	cfg := &Config{wings: map[string]Level{}, repos: map[string]Level{}}
 
-	data, err := os.ReadFile(filepath.Join(brainDir, "classification.yaml"))
+	// Read through the brain root, regular files only (hyperguild#157): a
+	// symlinked or special file is not trusted as the config, which is a hard
+	// error like a malformed one.
+	bfs, err := brainfs.Open(brainDir)
+	if errors.Is(err, fs.ErrNotExist) {
+		return cfg, nil
+	}
 	if err != nil {
-		if os.IsNotExist(err) {
+		return nil, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	data, err := bfs.ReadRegular("classification.yaml")
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
 			return cfg, nil
 		}
 		return nil, fmt.Errorf("read classification.yaml: %w", err)

ingestion/internal/classification/root_test.go

@@ -0,0 +1,46 @@
+package classification
+
+import (
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// hyperguild#157 slice 6: Load read classification.yaml with os.ReadFile. It
+// sets the I1 sovereignty levels; a symlinked file must not be trusted as the
+// config (a hard error, as for a malformed file), and a FIFO must not hang
+// startup.
+func TestLoadRefusesASymlinkedOrFIFOClassificationFile(t *testing.T) {
+	ok := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(ok, "classification.yaml"), []byte("wings:\n  w: confidential\n"), 0o644))
+	_, err := Load(ok)
+	require.NoError(t, err, "positive control")
+
+	linked := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(linked, "real.yaml"), []byte("wings:\n  w: public\n"), 0o644))
+	require.NoError(t, os.Symlink("real.yaml", filepath.Join(linked, "classification.yaml")))
+	_, err = Load(linked)
+	assert.Error(t, err, "an in-brain symlink is not trusted as the config")
+
+	fifo := t.TempDir()
+	require.NoError(t, syscall.Mkfifo(filepath.Join(fifo, "classification.yaml"), 0o644))
+	w, err := os.OpenFile(filepath.Join(fifo, "classification.yaml"), os.O_RDWR, 0)
+	require.NoError(t, err)
+	defer func() { _ = w.Close() }()
+	done := make(chan error, 1)
+	go func() { _, err := Load(fifo); done <- err }()
+	select {
+	case err := <-done:
+		assert.Error(t, err)
+	case <-time.After(3 * time.Second):
+		t.Fatal("Load hung on a FIFO")
+	}
+
+	_, err = Load(t.TempDir())
+	assert.NoError(t, err, "an absent file is still not an error")
+}

ingestion/internal/mcp/readexcerpt_root_test.go

@@ -21,6 +21,11 @@ func TestReadExcerptRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) {
 	require.NoError(t, os.MkdirAll(facts, 0o755))
 	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(facts, "leak.md")))
 	assert.NotContains(t, readExcerpt(brain, "wiki/w/facts/leak.md", 500), brainfstest.Sentinel)
+	// A link to a file elsewhere in the brain: os.Root allows it, only the
+	// regular-file check refuses it (hyperguild#171).
+	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.NotContains(t, readExcerpt(brain, "wiki/w/facts/inlink.md", 500), brainfstest.Sentinel)
 
 	p := filepath.Join(facts, "r.md")
 	require.NoError(t, os.WriteFile(p, []byte("---\nx: y\n---\ninside"), 0o644))
@@ -28,6 +33,9 @@ func TestReadExcerptRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) {
 	brainfstest.AssertNoLeak(t, p, "---\nx: y\n---\ninside", 1500*time.Millisecond, func() string {
 		return readExcerpt(brain, "wiki/w/facts/r.md", 500)
 	})
+	brainfstest.AssertNoLeakFrom(t, p, "---\nx: y\n---\ninside", inBrain, 1500*time.Millisecond, func() string {
+		return readExcerpt(brain, "wiki/w/facts/r.md", 500)
+	})
 	brainfstest.AssertNoHang(t, p, "---\nx: y\n---\ninside", 1500*time.Millisecond, 6*time.Second, func() {
 		_ = readExcerpt(brain, "wiki/w/facts/r.md", 500)
 	})

ingestion/internal/notes/edit_redirect_test.go

@@ -0,0 +1,25 @@
+package notes
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// hyperguild#188/#173: brain_edit's atomic rename must not be redirected by
+// a symlinked directory inside the brain.
+func TestEditRefusesANoteBehindASymlinkedDirectory(t *testing.T) {
+	b := t.TempDir()
+	victim := filepath.Join(b, "raw", "facts", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("old text\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "w"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "facts"), filepath.Join(b, "wiki", "w", "alias")))
+	_, err := Edit(b, "wiki/w/alias/v.md", "old text", "new text", ScopeNotes)
+	assert.Error(t, err)
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "old text\n", string(got))
+}

ingestion/internal/notes/read_root_test.go

@@ -38,3 +38,31 @@ func TestReadScopedRefusesANoteOverMaxNoteBytes(t *testing.T) {
 	_, err := ReadScoped(brain, "wiki/w/facts/big.md", ScopeNotes)
 	assert.ErrorIs(t, err, ErrTooLarge)
 }
+
+// hyperguild#171 (review of #172, finding 1): os.Root alone refuses links that
+// leave the brain, so the outside-target race above stays green for a reader
+// that skips brainfs's Lstat and SameFile checks. An in-brain target (raw/,
+// outside ScopeNotes) is what tells them apart.
+func TestReadScopedDoesNotReturnAnInBrainSymlinkTargetStaticallyOrDuringASampledSwapRace(t *testing.T) {
+	brain := t.TempDir()
+	facts := filepath.Join(brain, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	target := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md")))
+	b, err := ReadScoped(brain, "wiki/w/facts/inlink.md", ScopeNotes)
+	assert.Error(t, err, "static in-brain link")
+	assert.NotContains(t, string(b), brainfstest.Sentinel, "static in-brain link")
+
+	p := filepath.Join(facts, "r.md")
+	require.NoError(t, os.WriteFile(p, []byte("inside"), 0o644))
+	b, err = ReadScoped(brain, "wiki/w/facts/r.md", ScopeNotes)
+	require.NoError(t, err)
+	assert.Equal(t, "inside", string(b), "positive control: a regular note reads")
+
+	read := func() string {
+		b, _ := ReadScoped(brain, "wiki/w/facts/r.md", ScopeNotes)
+		return string(b)
+	}
+	brainfstest.AssertNoLeakFrom(t, p, "inside", target, 1500*time.Millisecond, read)
+}

ingestion/internal/pipeline/backfill.go

@@ -3,9 +3,10 @@ package pipeline
 
 import (
 	"context"
+	"errors"
 	"fmt"
-	"os"
-	"path/filepath"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+	"io/fs"
 	"strings"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/wiki"
@@ -23,10 +24,16 @@ func BackfillRefs(ctx context.Context, brainDir string) (int, error) {
 		return 0, fmt.Errorf("load inventory: %w", err)
 	}
 
-	sourcesDir := filepath.Join(brainDir, "wiki", "sources")
-	entries, err := os.ReadDir(sourcesDir)
+	// Listed and read through the brain root, regular files only
+	// (hyperguild#157).
+	bfs, err := brainfs.Open(brainDir)
 	if err != nil {
-		if os.IsNotExist(err) {
+		return 0, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	names, err := bfs.ReadDirRegular("wiki/sources")
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
 			return 0, nil
 		}
 		return 0, fmt.Errorf("read sources dir: %w", err)
@@ -37,20 +44,20 @@ func BackfillRefs(ctx context.Context, brainDir string) (int, error) {
 	// get both refs merged before a single write.
 	pending := make(map[string]wiki.Page)
 
-	for _, e := range entries {
+	for _, name := range names {
 		if ctx.Err() != nil {
 			return 0, ctx.Err()
 		}
-		if e.IsDir() || !strings.HasSuffix(e.Name(), ".md") {
+		if !strings.HasSuffix(name, ".md") {
 			continue
 		}
 
-		b, err := os.ReadFile(filepath.Join(sourcesDir, e.Name()))
+		b, err := bfs.ReadRegular("wiki/sources/" + name)
 		if err != nil {
 			continue
 		}
 		sourceContent := string(b)
-		sourceSlug := strings.TrimSuffix(e.Name(), ".md")
+		sourceSlug := strings.TrimSuffix(name, ".md")
 		sourceTitle := extractTitle(sourceContent)
 		if sourceTitle == "" {
 			sourceTitle = sourceSlug
@@ -70,7 +77,7 @@ func BackfillRefs(ctx context.Context, brainDir string) (int, error) {
 			// Start from already-accumulated version if we've seen this page.
 			page, seen := pending[relPath]
 			if !seen {
-				raw, err := os.ReadFile(filepath.Join(brainDir, filepath.FromSlash(relPath)))
+				raw, err := bfs.ReadRegular(relPath)
 				if err != nil {
 					continue
 				}
@@ -81,8 +88,7 @@ func BackfillRefs(ctx context.Context, brainDir string) (int, error) {
 	}
 
 	for relPath, page := range pending {
-		dest := filepath.Join(brainDir, filepath.FromSlash(relPath))
-		if err := os.WriteFile(dest, []byte(page.Content), 0o644); err != nil {
+		if err := bfs.PutRegular(relPath, []byte(page.Content)); err != nil {
 			return 0, fmt.Errorf("write %s: %w", relPath, err)
 		}
 	}

ingestion/internal/pipeline/pipeline.go

@@ -5,9 +5,10 @@ import (
 	"context"
 	"crypto/sha256"
 	"encoding/hex"
+	"errors"
 	"fmt"
-	"os"
-	"path/filepath"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+	"io/fs"
 	"strings"
 	"time"
 
@@ -125,11 +126,7 @@ func buildAndWrite(ctx context.Context, rawPages []RawPage, sourceSlug, date, br
 	var written []string
 	for _, page := range merged {
 		if !dryRun {
-			dest := filepath.Join(brainDir, filepath.FromSlash(page.Path))
-			if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
-				return Result{}, fmt.Errorf("mkdir for %s: %w", page.Path, err)
-			}
-			content, conflicts, err := reviseOrCreate(dest, page)
+			content, conflicts, err := reviseOrCreate(brainDir, page)
 			if err != nil {
 				return Result{}, err
 			}
@@ -147,7 +144,9 @@ func buildAndWrite(ctx context.Context, rawPages []RawPage, sourceSlug, date, br
 			if err != nil {
 				return Result{}, fmt.Errorf("stamp %s: %w", page.Path, err)
 			}
-			if err := os.WriteFile(dest, []byte(stamped), 0o644); err != nil {
+			// Written through the brain root, never through a symlinked
+			// directory or page (hyperguild#158).
+			if err := writeBrainFile(brainDir, page.Path, []byte(stamped)); err != nil {
 				return Result{}, fmt.Errorf("write %s: %w", page.Path, err)
 			}
 		}
@@ -188,14 +187,38 @@ func hashBody(content string) string {
 
 // readSourcePage returns the full on-disk content of the source page at
 // wiki/sources/<sourceSlug>.md, or "" when it doesn't exist yet.
+// It reads through the brain root, regular files only (hyperguild#157): the
+// content goes into the LLM prompt.
 func readSourcePage(brainDir, sourceSlug string) string {
-	raw, err := os.ReadFile(filepath.Join(brainDir, "wiki", "sources", sourceSlug+".md"))
+	raw, err := readBrainFile(brainDir, "wiki/sources/"+sourceSlug+".md")
 	if err != nil {
 		return ""
 	}
 	return string(raw)
 }
 
+// writeBrainFile creates or replaces one brain-relative file through the
+// brain root (hyperguild#158).
+func writeBrainFile(brainDir, rel string, data []byte) error {
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = bfs.Close() }()
+	return bfs.PutRegular(rel, data)
+}
+
+// readBrainFile reads one brain-relative file through the brain root,
+// regular files only (hyperguild#157).
+func readBrainFile(brainDir, rel string) ([]byte, error) {
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = bfs.Close() }()
+	return bfs.ReadRegular(rel)
+}
+
 // storedSourceHash reads source_hash from the source page a previous ingest
 // wrote, or "" when there is no such page or no such field.
 //
@@ -230,10 +253,10 @@ func storedSourceHash(brainDir, sourceSlug string) string {
 // its first-ingest date on a revised page. Left deliberately — the alternative
 // is this function editing frontmatter it does not own, and no lint reads that
 // field today.
-func reviseOrCreate(dest string, page wiki.Page) (string, []string, error) {
-	existing, err := os.ReadFile(dest)
+func reviseOrCreate(brainDir string, page wiki.Page) (string, []string, error) {
+	existing, err := readBrainFile(brainDir, page.Path)
 	switch {
-	case os.IsNotExist(err):
+	case errors.Is(err, fs.ErrNotExist):
 		return page.Content, nil, nil
 	case err != nil:
 		return "", nil, fmt.Errorf("read existing %s: %w", page.Path, err)
@@ -267,7 +290,7 @@ See brain/schema.md for the full schema.
 `
 
 func loadSchema(brainDir string) string {
-	b, err := os.ReadFile(filepath.Join(brainDir, "schema.md"))
+	b, err := readBrainFile(brainDir, "schema.md")
 	if err != nil {
 		return defaultSchema
 	}

ingestion/internal/pipeline/refs.go

@@ -2,7 +2,6 @@
 package pipeline
 
 import (
-	"os"
 	"path/filepath"
 	"regexp"
 	"strings"
@@ -53,8 +52,7 @@ func injectSourceRefs(pages []wiki.Page, inventory map[wiki.PageType][]wiki.Entr
 		if !ok {
 			continue
 		}
-		diskPath := filepath.Join(brainDir, "wiki", string(pt), slug+".md")
-		b, err := os.ReadFile(diskPath)
+		b, err := readBrainFile(brainDir, "wiki/"+string(pt)+"/"+slug+".md")
 		if err != nil {
 			continue
 		}

ingestion/internal/pipeline/root_test.go

@@ -0,0 +1,192 @@
+package pipeline
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"syscall"
+	"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/wiki"
+)
+
+// hyperguild#157 slice 6: the pipeline read the source page, schema.md, the
+// pages it revises and the pages it adds source refs to with os.ReadFile, so
+// a symlinked file's content reached the LLM prompt and the written pages,
+// and a FIFO hung the ingest.
+
+func mkdirs(t *testing.T, brain string, dirs ...string) {
+	t.Helper()
+	for _, d := range dirs {
+		require.NoError(t, os.MkdirAll(filepath.Join(brain, filepath.FromSlash(d)), 0o755))
+	}
+}
+
+func TestReadSourcePageAndSchemaRefuseSymlinksAndSurviveSwapRaces(t *testing.T) {
+	brain := t.TempDir()
+	mkdirs(t, brain, "wiki/sources")
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "sources", "ok.md"), []byte("zqinside source"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "schema.md"), []byte("zqinside schema"), 0o644))
+	assert.Equal(t, "zqinside source", readSourcePage(brain, "ok"), "positive control")
+	assert.Equal(t, "zqinside schema", loadSchema(brain), "positive control")
+
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(brain, "wiki", "sources", "out.md")))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "s.md"), filepath.Join(brain, "wiki", "sources", "in.md")))
+	assert.NotContains(t, readSourcePage(brain, "out"), brainfstest.Sentinel)
+	assert.NotContains(t, readSourcePage(brain, "in"), brainfstest.Sentinel)
+	assert.NotContains(t, storedSourceHash(brain, "in"), brainfstest.Sentinel)
+
+	src := filepath.Join(brain, "wiki", "sources", "r.md")
+	read := func() string { return readSourcePage(brain, "r") }
+	brainfstest.AssertNoLeak(t, src, "zqinside", 1500*time.Millisecond, read)
+	brainfstest.AssertNoLeakFrom(t, src, "zqinside", inBrain, 1500*time.Millisecond, read)
+	brainfstest.AssertNoHang(t, src, "zqinside", 1500*time.Millisecond, 6*time.Second, func() { _ = read() })
+
+	schema := filepath.Join(brain, "schema.md")
+	rs := func() string { return loadSchema(brain) }
+	brainfstest.AssertNoLeakFrom(t, schema, "zqinside schema", inBrain, 1500*time.Millisecond, rs)
+	brainfstest.AssertNoHang(t, schema, "zqinside schema", 1500*time.Millisecond, 6*time.Second, func() { _ = rs() })
+}
+
+func TestReviseOrCreateRefusesASymlinkedExistingPage(t *testing.T) {
+	brain := t.TempDir()
+	mkdirs(t, brain, "wiki/concepts")
+	brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "s.md"), filepath.Join(brain, "wiki", "concepts", "c.md")))
+	page := wiki.Page{Path: "wiki/concepts/c.md", Content: "---\ntitle: C\n---\nnew\n"}
+	out, _, err := reviseOrCreate(brain, page)
+	assert.Error(t, err)
+	assert.NotContains(t, out, brainfstest.Sentinel)
+
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "concepts", "d.md"), []byte("---\ntitle: D\n---\nzqold\n"), 0o644))
+	out, _, err = reviseOrCreate(brain, wiki.Page{Path: "wiki/concepts/d.md", Content: "---\ntitle: D\n---\nnew\n"})
+	require.NoError(t, err)
+	assert.Contains(t, out, "zqold", "positive control: the existing page is read")
+	out, _, err = reviseOrCreate(brain, wiki.Page{Path: "wiki/concepts/new.md", Content: "fresh"})
+	require.NoError(t, err)
+	assert.Equal(t, "fresh", out, "positive control: a missing page is created")
+}
+
+func TestInjectSourceRefsDoesNotReadASymlinkedPage(t *testing.T) {
+	brain := t.TempDir()
+	mkdirs(t, brain, "wiki/concepts")
+	brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "s.md"), filepath.Join(brain, "wiki", "concepts", "c.md")))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "concepts", "d.md"), []byte("zqinside d"), 0o644))
+	inv := map[wiki.PageType][]wiki.Entry{wiki.PageTypeConcept: {
+		{Slug: "c", Type: wiki.PageTypeConcept}, {Slug: "d", Type: wiki.PageTypeConcept},
+	}}
+	src := wiki.Page{Path: "wiki/sources/src.md", Content: "---\ntitle: Src\n---\nsee [[c|C]] and [[d|D]]\n"}
+	out := injectSourceRefs([]wiki.Page{src}, inv, brain)
+	got := fmt.Sprintf("%+v", out)
+	assert.Contains(t, got, "zqinside d", "positive control")
+	assert.NotContains(t, got, brainfstest.Sentinel)
+}
+
+func TestBackfillRefsSkipsSymlinkedSourcesAndPages(t *testing.T) {
+	brain := t.TempDir()
+	mkdirs(t, brain, "wiki/sources", "wiki/concepts", "raw")
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "concepts", "real.md"), []byte("---\ntitle: R\n---\nbody\n"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "sources", "ok.md"), []byte("---\ntitle: zqinside\n---\n[[real|R]]\n"), 0o644))
+	// A source elsewhere in the brain whose title is the sentinel and which
+	// links the real concept with the [[slug|title]] form the pipeline follows.
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "raw", "src.md"),
+		[]byte("---\ntitle: "+brainfstest.Sentinel+"\n---\n[[real|R]]\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "src.md"), filepath.Join(brain, "wiki", "sources", "in.md")))
+	// A concept page linked by the regular source that is itself a symlink.
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "sources", "ok2.md"), []byte("---\ntitle: Two\n---\n[[lnk|L]]\n"), 0o644))
+	brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "page.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "page.md"), filepath.Join(brain, "wiki", "concepts", "lnk.md")))
+
+	_, err := BackfillRefs(context.Background(), brain)
+	require.NoError(t, err)
+	b, _ := os.ReadFile(filepath.Join(brain, "wiki", "concepts", "real.md"))
+	assert.Contains(t, string(b), "zqinside", "positive control: the regular source's ref is added")
+	assert.NotContains(t, string(b), brainfstest.Sentinel, "a symlinked source's title was written as a ref")
+	raw, _ := os.ReadFile(filepath.Join(brain, "raw", "page.md"))
+	assert.NotContains(t, string(raw), "[[ok2", "the symlinked concept page's target was rewritten")
+}
+
+// A source swapped between a regular file and a symlink to an in-brain source
+// whose title is the sentinel: the read refuses the swapped-in link, so the
+// sentinel never lands in the concept page as a ref.
+func TestBackfillRefsDoesNotWriteARefFromASourceSwappedInBehindASymlink(t *testing.T) {
+	brain := t.TempDir()
+	mkdirs(t, brain, "wiki/sources", "wiki/concepts", "raw")
+	realPage := filepath.Join(brain, "wiki", "concepts", "real.md")
+	target := filepath.Join(brain, "raw", "src.md")
+	require.NoError(t, os.WriteFile(target, []byte("---\ntitle: "+brainfstest.Sentinel+"\n---\n[[real|R]]\n"), 0o644))
+	src := filepath.Join(brain, "wiki", "sources", "r.md")
+	inside := "---\ntitle: zqinside\n---\n[[real|R]]\n"
+	read := func() string {
+		_ = os.WriteFile(realPage, []byte("---\ntitle: R\n---\nbody\n"), 0o644)
+		_, _ = BackfillRefs(context.Background(), brain)
+		b, _ := os.ReadFile(realPage)
+		return string(b)
+	}
+	require.NoError(t, os.WriteFile(src, []byte(inside), 0o644))
+	require.Contains(t, read(), "zqinside", "positive control")
+	brainfstest.AssertNoLeakFrom(t, src, inside, target, 1500*time.Millisecond, read)
+}
+
+// A concept page that is regular when the inventory lists it, then swapped
+// for a symlink to an in-brain file before BackfillRefs reads it: only the
+// page read's own check refuses it (a static symlink never gets this far,
+// because LoadInventory does not list it).
+func TestBackfillRefsDoesNotCopyAPageSwappedInBehindASymlink(t *testing.T) {
+	brain := t.TempDir()
+	mkdirs(t, brain, "wiki/sources", "wiki/concepts", "raw")
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "sources", "s.md"), []byte("---\ntitle: S\n---\n[[c|C]]\n"), 0o644))
+	page := filepath.Join(brain, "wiki", "concepts", "c.md")
+	target := filepath.Join(brain, "raw", "secret.md")
+	inside := "---\ntitle: C\n---\nzqinside\n"
+	read := func() string {
+		// The write path still follows a swapped-in link (#158) and can
+		// overwrite the target, so restore it each round.
+		_ = os.WriteFile(target, []byte("---\ntitle: X\n---\n"+brainfstest.Sentinel+"\n"), 0o644)
+		_, _ = BackfillRefs(context.Background(), brain)
+		f, err := os.OpenFile(page, os.O_RDONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0)
+		if err != nil {
+			return ""
+		}
+		defer func() { _ = f.Close() }()
+		b, _ := io.ReadAll(f)
+		return string(b)
+	}
+	require.NoError(t, os.WriteFile(page, []byte(inside), 0o644))
+	require.Contains(t, read(), "[[s|S]]", "positive control: the regular page gets the source ref")
+	brainfstest.AssertNoLeakFrom(t, page, inside, target, 3*time.Second, read)
+}
+
+// hyperguild#158: BackfillRefs read a regular concept page, a symlink could
+// be swapped in, and os.WriteFile then followed it and overwrote the link's
+// target. The target is not restored between rounds here, so any
+// write-through shows.
+func TestBackfillRefsNeverWritesThroughAPageSwappedForASymlink(t *testing.T) {
+	brain := t.TempDir()
+	mkdirs(t, brain, "wiki/sources", "wiki/concepts", "raw")
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "sources", "s.md"), []byte("---\ntitle: S\n---\n[[c|C]]\n"), 0o644))
+	page := filepath.Join(brain, "wiki", "concepts", "c.md")
+	target := filepath.Join(brain, "raw", "secret.md")
+	require.NoError(t, os.WriteFile(target, []byte("untouched"), 0o644))
+	inside := "---\ntitle: C\n---\nbody\n"
+	require.NoError(t, os.WriteFile(page, []byte(inside), 0o644))
+	brainfstest.StartSwap(t, page, inside, target, false)
+	ok := 0
+	for deadline := time.Now().Add(2 * time.Second); time.Now().Before(deadline); {
+		if _, err := BackfillRefs(context.Background(), brain); err == nil {
+			ok++
+		}
+	}
+	got, _ := os.ReadFile(target)
+	assert.Equal(t, "untouched", string(got), "BackfillRefs wrote through a swapped-in symlink")
+	assert.Positive(t, ok, "positive control: some backfills ran")
+}

ingestion/internal/provenance/provenance.go

@@ -28,7 +28,6 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"os"
 	"regexp"
 	"strings"
 
@@ -102,24 +101,6 @@ func Apply(content string, s Stamp) (string, error) {
 	return out, nil
 }
 
-// ApplyFile applies the stamp to the note at absPath in place.
-func ApplyFile(absPath string, s Stamp) error {
-	b, err := os.ReadFile(absPath)
-	if err != nil {
-		return fmt.Errorf("read for provenance: %w", err)
-	}
-	out, err := Apply(string(b), s)
-	if err != nil {
-		return err
-	}
-	if out == string(b) {
-		return nil
-	}
-	if err := os.WriteFile(absPath, []byte(out), 0o644); err != nil {
-		return fmt.Errorf("write provenance: %w", err)
-	}
-	return nil
-}
 
 // plainGroups keeps the provably plain key groups of a frontmatter block.
 func plainGroups(block string) string {

ingestion/internal/search/brainroot_test.go

@@ -12,6 +12,8 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest"
 )
 
 // hyperguild#157 option 1: search walked and read the brain by path, so a
@@ -189,3 +191,49 @@ func TestHydrateRefusesASymlink(t *testing.T) {
 	assert.Error(t, err)
 	assert.NotContains(t, r.Excerpt, sentinel157)
 }
+
+// hyperguild#171: os.Root refuses links that leave the brain on its own, so
+// the outside-target cases above would stay green for a caller that read
+// without brainfs's Lstat and SameFile checks. These targets are inside the
+// brain (raw/, which is not a search root).
+func inBrainTarget(t *testing.T, brain string) string {
+	t.Helper()
+	return brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+}
+
+func TestQueryDoesNotReturnAnInBrainSymlinkTargetDuringASampledSwapRace(t *testing.T) {
+	brain, facts, _ := searchBrain(t)
+	target := inBrainTarget(t, brain)
+	read := func() string {
+		// Both terms, so the regular note is a possible hit: a reader that
+		// never returns the inside note would pass vacuously (#177 floor).
+		rs, _ := Query(brain, QueryOptions{Query: brainfstest.Sentinel + " zqinside", Limit: 10})
+		s := ""
+		for _, r := range rs {
+			s += r.Title + r.Excerpt
+		}
+		return s
+	}
+	brainfstest.AssertNoLeakFrom(t, filepath.Join(facts, "r.md"), "# r\n\nzqinside", target, 1500*time.Millisecond, read)
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md")))
+	assert.NotContains(t, read(), brainfstest.Sentinel, "static in-brain link")
+}
+
+func TestHydrateRefusesAnInBrainSymlinkAndDoesNotReturnItsTargetDuringASampledSwapRace(t *testing.T) {
+	brain, facts, _ := searchBrain(t)
+	target := inBrainTarget(t, brain)
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md")))
+	r, err := hydrate(brain, "wiki/w/facts/inlink.md")
+	assert.Error(t, err)
+	assert.NotContains(t, r.Excerpt+r.Title, brainfstest.Sentinel)
+
+	p := filepath.Join(facts, "r.md")
+	require.NoError(t, os.WriteFile(p, []byte("# r\n\nzqinside"), 0o644))
+	r, err = hydrate(brain, "wiki/w/facts/r.md")
+	require.NoError(t, err)
+	assert.Contains(t, r.Excerpt, "zqinside", "positive control: a regular note hydrates")
+	brainfstest.AssertNoLeakFrom(t, p, "# r\n\nzqinside", target, 1500*time.Millisecond, func() string {
+		r, _ := hydrate(brain, "wiki/w/facts/r.md")
+		return r.Title + r.Excerpt
+	})
+}

ingestion/internal/session/id_test.go

@@ -2,14 +2,17 @@ package session
 
 import (
 	"errors"
+	"fmt"
 	"os"
 	"path/filepath"
+	"sync/atomic"
 	"syscall"
 	"testing"
 	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"golang.org/x/sys/unix"
 )
 
 // session_log passed the caller's session_id straight into
@@ -90,3 +93,85 @@ func TestAppendReturnsPromptlyOnAFIFOLogWithNoReader(t *testing.T) {
 		t.Fatal("Append blocked on a FIFO log with no reader")
 	}
 }
+
+// hyperguild#173: session_log followed a symlinked sessions dir.
+func TestAppendRefusesASymlinkedSessionsDir(t *testing.T) {
+	root := t.TempDir()
+	elsewhere := filepath.Join(root, "elsewhere")
+	require.NoError(t, os.MkdirAll(elsewhere, 0o755))
+	dir := filepath.Join(root, "sessions")
+	require.NoError(t, os.Symlink("elsewhere", dir))
+	assert.Error(t, Append(dir, "s", Entry{SessionID: "s"}))
+	ents, _ := os.ReadDir(elsewhere)
+	assert.Empty(t, ents, "a log was created through the symlinked dir")
+}
+
+// The sessions dir is swapped (RENAME_EXCHANGE) with a symlink to a
+// directory outside the brain while Append runs. Append opens through an
+// os.Root on the sessions dir's parent, so a swap can redirect it only
+// inside that parent (the #167 residual), never outside it.
+func TestAppendNeverCreatesALogOutsideTheParentUnderADirSwapRace(t *testing.T) {
+	brain := t.TempDir()
+	outside := t.TempDir()
+	dir := filepath.Join(brain, "sessions")
+	other := filepath.Join(brain, "sessions.link")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	require.NoError(t, os.Symlink(outside, other))
+	var stop atomic.Bool
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		for !stop.Load() {
+			_ = unix.Renameat2(unix.AT_FDCWD, dir, unix.AT_FDCWD, other, unix.RENAME_EXCHANGE)
+		}
+	}()
+	ok := 0
+	for i := 0; i < 20000; i++ {
+		if Append(dir, fmt.Sprintf("s%d", i), Entry{SessionID: "s"}) == nil {
+			ok++
+		}
+	}
+	stop.Store(true)
+	<-done
+	ents, _ := os.ReadDir(outside)
+	assert.Empty(t, ents, "logs were created outside the brain")
+	assert.Positive(t, ok, "positive control: appends to the real dir succeed")
+}
+
+// The log file is swapped between a regular file and a symlink to another
+// file in the brain while Append runs: Append writes only after confirming
+// the path is the regular file it opened, so the other file never grows.
+func TestAppendNeverWritesThroughALogSwappedForASymlink(t *testing.T) {
+	brain := t.TempDir()
+	dir := filepath.Join(brain, "sessions")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	victim := filepath.Join(brain, "victim.md")
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	log := filepath.Join(dir, "s.jsonl")
+	var stop atomic.Bool
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		tmp := log + ".swap"
+		for i := 0; !stop.Load(); i++ {
+			_ = os.Remove(tmp)
+			if i%2 == 0 {
+				_ = os.WriteFile(tmp, nil, 0o644)
+			} else {
+				_ = os.Symlink(filepath.Join("..", "victim.md"), tmp)
+			}
+			_ = os.Rename(tmp, log)
+		}
+	}()
+	ok := 0
+	for i := 0; i < 20000; i++ {
+		if Append(dir, "s", Entry{SessionID: "s"}) == nil {
+			ok++
+		}
+	}
+	stop.Store(true)
+	<-done
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched\n", string(got), "a log line was written through the swapped-in symlink")
+	assert.Positive(t, ok, "positive control: appends to the regular log succeed")
+}

ingestion/internal/session/session.go

@@ -65,14 +65,42 @@ func Append(sessionsDir, sessionID string, entry Entry) error {
 	if err := checkID(sessionID); err != nil {
 		return err
 	}
-	if err := os.MkdirAll(sessionsDir, 0o755); err != nil {
+	// Opened through an os.Root on the sessions dir's parent (the brain dir),
+	// so a sessions dir swapped for a symlink after the check below can
+	// redirect the log only inside that parent, never outside it (#173; the
+	// in-brain swap is the #167 residual).
+	parentDir, name := filepath.Dir(sessionsDir), filepath.Base(sessionsDir)
+	if err := os.MkdirAll(parentDir, 0o755); err != nil {
+		return fmt.Errorf("create sessions parent: %w", err)
+	}
+	root, err := os.OpenRoot(parentDir)
+	if err != nil {
+		return fmt.Errorf("open sessions parent: %w", err)
+	}
+	defer func() { _ = root.Close() }()
+	if err := root.Mkdir(name, 0o755); err != nil && !errors.Is(err, fs.ErrExist) {
 		return fmt.Errorf("create sessions dir: %w", err)
 	}
-	path := filepath.Join(sessionsDir, sessionID+".jsonl")
-	f, err := os.OpenFile(path, os.O_CREATE|os.O_APPEND|os.O_WRONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0o644)
+	// The sessions dir itself must be a real directory, not a symlink that
+	// redirects the log elsewhere (hyperguild#173).
+	if fi, err := root.Lstat(name); err != nil {
+		return fmt.Errorf("stat sessions dir: %w", err)
+	} else if !fi.IsDir() {
+		return fmt.Errorf("sessions dir %s is not a real directory", sessionsDir)
+	}
+	logRel := name + "/" + sessionID + ".jsonl"
+	f, err := root.OpenFile(logRel, os.O_CREATE|os.O_APPEND|os.O_WRONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0o644)
 	if err != nil {
 		return fmt.Errorf("open session log: %w", err)
 	}
+	// os.Root follows an in-root final symlink even with O_NOFOLLOW, so
+	// confirm, before writing, that the path is the regular file we opened.
+	hfi, herr := f.Stat()
+	lfi, lerr := root.Lstat(logRel)
+	if herr != nil || lerr != nil || !lfi.Mode().IsRegular() || !os.SameFile(lfi, hfi) {
+		_ = f.Close()
+		return fmt.Errorf("session log %s is not a regular file", logRel)
+	}
 
 	line, err := json.Marshal(entry)
 	if err != nil {

ingestion/internal/vectorstore/sync_root_test.go

@@ -42,6 +42,11 @@ 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")))
+	// A link to a file elsewhere in the brain: os.Root allows it, only the
+	// regular-file checks refuse it (hyperguild#171). raw/ is not a scan root,
+	// so its sentinel can only arrive through the link.
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(brain, "wiki", "w", "facts", "inlink.md")))
 
 	emb := &recordingEmbedder{}
 	store := &stubStore{}
@@ -51,6 +56,7 @@ func TestSyncRefusesSymlinkedNotesAndSurvivesSwapRaces(t *testing.T) {
 	assert.NotContains(t, emb.all(), brainfstest.Sentinel)
 	for p := range store.upserts {
 		assert.NotContains(t, p, "leak.md")
+		assert.NotContains(t, p, "inlink.md")
 	}
 
 	p := filepath.Join(brain, "knowledge", "r.md")
@@ -61,6 +67,7 @@ func TestSyncRefusesSymlinkedNotesAndSurvivesSwapRaces(t *testing.T) {
 		return e.all()
 	}
 	brainfstest.AssertNoLeak(t, p, "inside", 1500*time.Millisecond, sync)
+	brainfstest.AssertNoLeakFrom(t, p, "inside", inBrain, 1500*time.Millisecond, sync)
 	brainfstest.AssertNoHang(t, p, "inside", 1500*time.Millisecond, 6*time.Second, func() { _ = sync() })
 }
 

ingestion/internal/watcher/watcher.go

@@ -12,6 +12,7 @@ import (
 	"time"
 	"unicode"
 
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/extract"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 )
@@ -145,16 +146,12 @@ func processFile(ctx context.Context, cfg Config, root *os.Root, rawDir, path, d
 
 	_, runErr := pipeline.Run(ctx, cfg.Pipeline, cfg.BrainDir, content, source, false)
 	if runErr != nil {
-		// Copy to failed/ and leave a .failed marker so we don't retry.
-		failedDir := filepath.Join(cfg.BrainDir, "raw", "failed")
-		if mkErr := os.MkdirAll(failedDir, 0o755); mkErr != nil {
-			return fmt.Errorf("mkdir failed dir: %w", mkErr)
-		}
-		dest := filepath.Join(failedDir, filename)
-		if cpErr := copyFromRoot(root, rel, dest); cpErr != nil {
+		// Copy to failed/ and leave a .failed marker so we don't retry. Both
+		// written through the brain root (hyperguild#158).
+		if cpErr := copyFromRoot(root, rel, cfg.BrainDir, "raw/failed/"+filename); cpErr != nil {
 			return fmt.Errorf("copy to failed: %w", cpErr)
 		}
-		if mkErr := os.WriteFile(path+".failed", []byte(runErr.Error()), 0o644); mkErr != nil {
+		if mkErr := putBrainFile(cfg.BrainDir, "raw/"+filepath.ToSlash(rel)+".failed", []byte(runErr.Error())); mkErr != nil {
 			slog.Error("watcher: failed to write .failed marker", "error", mkErr)
 		}
 
@@ -168,21 +165,18 @@ func processFile(ctx context.Context, cfg Config, root *os.Root, rawDir, path, d
 	}
 
 	// Copy to processed/YYYY-MM-DD/ and leave a .processed marker so we don't re-ingest.
-	processedDir := filepath.Join(cfg.BrainDir, "raw", "processed", date)
-	if err := os.MkdirAll(processedDir, 0o755); err != nil {
-		return fmt.Errorf("mkdir processed dir: %w", err)
-	}
-	dest := filepath.Join(processedDir, filename)
-	if _, err := os.Stat(dest); err == nil {
+	// Written through the brain root (hyperguild#158).
+	dest := "raw/processed/" + date + "/" + filename
+	if _, err := os.Lstat(filepath.Join(cfg.BrainDir, filepath.FromSlash(dest))); err == nil {
 		// Archive copy already exists; append timestamp to avoid overwriting.
 		ext := filepath.Ext(filename)
 		base := strings.TrimSuffix(filename, ext)
-		dest = filepath.Join(processedDir, base+"-"+time.Now().UTC().Format("150405")+ext)
+		dest = "raw/processed/" + date + "/" + base + "-" + time.Now().UTC().Format("150405") + ext
 	}
-	if err := copyFromRoot(root, rel, dest); err != nil {
+	if err := copyFromRoot(root, rel, cfg.BrainDir, dest); err != nil {
 		return fmt.Errorf("copy to processed: %w", err)
 	}
-	if err := os.WriteFile(path+".processed", []byte(date), 0o644); err != nil {
+	if err := putBrainFile(cfg.BrainDir, "raw/"+filepath.ToSlash(rel)+".processed", []byte(date)); err != nil {
 		slog.Error("watcher: failed to write .processed marker", "error", err)
 	}
 
@@ -214,23 +208,22 @@ func appendWatcherLog(brainDir, filename string, runErr error, date string) erro
 	entry := fmt.Sprintf("## %s — watcher error\n\n- **File:** %s\n- **Error:** %s\n\n",
 		date, filename, runErr.Error())
 
-	logPath := filepath.Join(brainDir, "log.md")
-	f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
-	if err != nil {
-		return fmt.Errorf("open log: %w", err)
-	}
-
-	if _, err = f.WriteString(entry); err != nil {
-		f.Close() //nolint:errcheck
+	if err := brainfs.AppendFile(brainDir, "log.md", []byte(entry)); err != nil {
 		return fmt.Errorf("write log: %w", err)
 	}
-	return f.Close()
+	return nil
+}
+
+// putBrainFile creates or replaces a brain-relative file through the brain
+// root, never through a symlinked directory or file (hyperguild#158).
+func putBrainFile(brainDir, rel string, data []byte) error {
+	return brainfs.PutFile(brainDir, rel, data)
 }
 
 // copyFromRoot archives a raw/ file read through the root, refusing anything
 // that is not a regular file, so a swapped-in symlink cannot copy an outside
 // file into raw/processed/ or raw/failed/ (hyperguild#153).
-func copyFromRoot(root *os.Root, rel, dst string) error {
+func copyFromRoot(root *os.Root, rel, brainDir, dstRel string) error {
 	fi, err := root.Lstat(rel)
 	if err != nil {
 		return err
@@ -243,13 +236,9 @@ func copyFromRoot(root *os.Root, rel, dst string) error {
 		return err
 	}
 	defer func() { _ = in.Close() }()
-	out, err := os.Create(dst)
+	data, err := io.ReadAll(in)
 	if err != nil {
 		return err
 	}
-	if _, err := io.Copy(out, in); err != nil {
-		_ = out.Close()
-		return err
-	}
-	return out.Close()
+	return putBrainFile(brainDir, dstRel, data)
 }

ingestion/internal/watcher/writes_redirect_test.go

@@ -0,0 +1,66 @@
+package watcher
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
+)
+
+func okPipeline() pipeline.Config {
+	return pipeline.Config{Complete: func(context.Context, string, string) (string, error) {
+		b, _ := json.Marshal([]pipeline.RawPage{{Title: "X", Type: "source", Subtype: "article", Content: "## S\n\nx\n"}})
+		return string(b), nil
+	}, Schema: "# Schema"}
+}
+
+func failingPipeline() pipeline.Config {
+	return pipeline.Config{Complete: func(context.Context, string, string) (string, error) {
+		return "", errors.New("model down")
+	}, Schema: "# Schema"}
+}
+
+// hyperguild#158: the watcher wrote the archive copy under raw/processed or
+// raw/failed, and its log.md entry, by path, so a symlinked archive
+// directory or log redirected the write elsewhere in the brain or outside
+// it. (A pre-planted marker symlink makes the watcher skip the note, so the
+// marker write itself is reachable only by a race.)
+func TestProcessDirDoesNotWriteThroughASymlinkedArchiveDirOrLog(t *testing.T) {
+	for name, pcfg := range map[string]pipeline.Config{"processed": okPipeline(), "failed": failingPipeline()} {
+		t.Run(name, func(t *testing.T) {
+			brainDir := setupBrainDir(t)
+			outside := t.TempDir()
+			victim := filepath.Join(brainDir, "wiki", "concepts", "v.md")
+			require.NoError(t, os.WriteFile(victim, []byte("untouched"), 0o644))
+			require.NoError(t, os.WriteFile(filepath.Join(brainDir, "raw", "n.md"), []byte("note"), 0o644))
+			require.NoError(t, os.Symlink(outside, filepath.Join(brainDir, "raw", name)))
+			if name == "failed" {
+				require.NoError(t, os.Symlink(filepath.Join("wiki", "concepts", "v.md"), filepath.Join(brainDir, "log.md")))
+			}
+			_ = processDir(context.Background(), Config{BrainDir: brainDir, Interval: time.Hour, Pipeline: pcfg}, "2026-10-05")
+			got, _ := os.ReadFile(victim)
+			assert.Equal(t, "untouched", string(got), "the log was written through a symlink")
+			ents, _ := os.ReadDir(outside)
+			assert.Empty(t, ents, "the archive copy was written outside the brain")
+		})
+	}
+}
+
+func TestProcessDirWritesMarkersAndArchiveInRealDirectories(t *testing.T) {
+	brainDir := setupBrainDir(t)
+	require.NoError(t, os.WriteFile(filepath.Join(brainDir, "raw", "n.md"), []byte("note"), 0o644))
+	errs := processDir(context.Background(), Config{BrainDir: brainDir, Interval: time.Hour, Pipeline: okPipeline()}, "2026-10-05")
+	assert.Empty(t, errs)
+	_, err := os.Stat(filepath.Join(brainDir, "raw", "n.md.processed"))
+	assert.NoError(t, err, "positive control: marker written")
+	_, err = os.Stat(filepath.Join(brainDir, "raw", "processed", "2026-10-05", "n.md"))
+	assert.NoError(t, err, "positive control: archive copy written")
+}

ingestion/internal/wiki/index.go

@@ -3,8 +3,6 @@ package wiki
 
 import (
 	"fmt"
-	"os"
-	"path/filepath"
 	"strings"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
@@ -50,8 +48,8 @@ func RebuildIndex(brainDir, date string) error {
 		sb.WriteString("\n")
 	}
 
-	dest := filepath.Join(brainDir, "wiki", "index.md")
-	return os.WriteFile(dest, []byte(sb.String()), 0o644)
+	// Written through the brain root, never through a symlink (#158).
+	return bfs.PutRegular("wiki/index.md", []byte(sb.String()))
 }
 
 // pageFirstSentence reads the page through the brain root, regular files

ingestion/internal/wiki/log.go

@@ -3,8 +3,7 @@ package wiki
 
 import (
 	"fmt"
-	"os"
-	"path/filepath"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"strings"
 )
 
@@ -27,14 +26,14 @@ func AppendLog(brainDir, source string, pages, warnings []string, date string) e
 	}
 	sb.WriteString("\n")
 
-	logPath := filepath.Join(brainDir, "log.md")
-	f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
+	// Appended through the brain root, never through a symlink (#158).
+	bfs, err := brainfs.Open(brainDir)
 	if err != nil {
-		return fmt.Errorf("open log: %w", err)
+		return fmt.Errorf("open brain: %w", err)
 	}
-	if _, err = f.WriteString(sb.String()); err != nil {
-		f.Close() //nolint:errcheck
+	defer func() { _ = bfs.Close() }()
+	if err := bfs.AppendRegular("log.md", []byte(sb.String())); err != nil {
 		return fmt.Errorf("write log: %w", err)
 	}
-	return f.Close()
+	return nil
 }

ingestion/internal/wiki/writers_redirect_test.go

@@ -0,0 +1,35 @@
+package wiki
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// hyperguild#158: RebuildIndex wrote wiki/index.md and AppendLog appended
+// log.md with os.WriteFile / os.OpenFile, so a symlinked file was written
+// through.
+func TestRebuildIndexAndAppendLogDoNotWriteThroughSymlinks(t *testing.T) {
+	b := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "concepts"), 0o755))
+	victim := filepath.Join(b, "raw", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw", "v.md"), filepath.Join(b, "wiki", "index.md")))
+	require.NoError(t, os.Symlink(filepath.Join("raw", "v.md"), filepath.Join(b, "log.md")))
+
+	assert.Error(t, RebuildIndex(b, "2026-10-05"))
+	assert.Error(t, AppendLog(b, "src", []string{"p"}, nil, "2026-10-05"))
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched", string(got))
+
+	require.NoError(t, os.Remove(filepath.Join(b, "wiki", "index.md")))
+	require.NoError(t, os.Remove(filepath.Join(b, "log.md")))
+	require.NoError(t, RebuildIndex(b, "2026-10-05"), "positive control")
+	require.NoError(t, AppendLog(b, "src", []string{"p"}, nil, "2026-10-05"), "positive control")
+	l, _ := os.ReadFile(filepath.Join(b, "log.md"))
+	assert.Contains(t, string(l), "src")
+}