test(symlinkguard): an unremovable special file must not be reported as removed (#179)

Review round 2 on PR #190: swallowing root.Remove's error in
removeSpecial left every test green (the false 'removed' alert also named
the file). The test now asserts no message says 'removed'; red under that
flip.

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

ingestion/cmd/server/main.go

@@ -17,7 +17,6 @@ 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"
@@ -90,15 +89,11 @@ func (s *claudeSink) Ingest(ctx context.Context, b claudewatcher.Batch) error {
 		sb.WriteString("\n\n")
 	}
 	slug := "session-" + b.Host + "-" + b.SessionID
-	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)
+	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)
 	}
-	defer func() { _ = bfs.Close() }()
-	if err := bfs.PutRegular(dest, []byte(sb.String())); err != nil {
+	if err := os.WriteFile(dest, []byte(sb.String()), 0o644); err != nil {
 		return fmt.Errorf("write claude session archive: %w", err)
 	}
 	s.logger.Debug("claude session archived (non-indexed)", "path", dest)

ingestion/cmd/server/symlink_check_test.go

@@ -4,6 +4,7 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"syscall"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -63,3 +64,13 @@ func TestStartupSymlinkCheckRefusesAnUnlistableBrainRoot(t *testing.T) {
 	t.Cleanup(func() { _ = os.Chmod(brain, 0o755) })
 	assert.Error(t, startupSymlinkCheck(brain))
 }
+
+// hyperguild#179: a FIFO in the brain is refused at startup with a clear
+// message, instead of hanging or exiting later in a reader.
+func TestStartupSymlinkCheckRefusesABrainWithAFIFO(t *testing.T) {
+	brain := t.TempDir()
+	require.NoError(t, syscall.Mkfifo(filepath.Join(brain, "classification.yaml"), 0o644))
+	err := startupSymlinkCheck(brain)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "classification.yaml")
+}

ingestion/internal/api/handler.go

@@ -12,7 +12,6 @@ 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"
@@ -228,22 +227,14 @@ 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).
-	// 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.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+		return "", fmt.Errorf("create hall dir: %w", err)
 	}
-	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 {
+	if err := os.WriteFile(dest, []byte(final), 0o644); err != nil {
 		return "", fmt.Errorf("write: %w", err)
 	}
-	return rel, nil
+	rel, _ := filepath.Rel(brainDir, dest)
+	return filepath.ToSlash(rel), nil
 }
 
 // scalarValues flattens frontmatter fields to key -> scalar value for

ingestion/internal/api/promote.go

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

ingestion/internal/api/promote_redirect_test.go

@@ -1,60 +0,0 @@
-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,10 +1,6 @@
 package api
 
 import (
-	"fmt"
-	"path/filepath"
-
-	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/provenance"
 )
 
@@ -15,62 +11,11 @@ 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,
-// read and rewritten through the brain root (hyperguild#158).
+// StampProvenanceFile applies StampProvenance to a brain-relative note path.
 func StampProvenanceFile(brainDir, relPath, origin, writtenBy string) error {
-	rel, _, err := resolveWithin(brainDir, relPath)
+	_, abs, err := resolveWithin(brainDir, relPath)
 	if err != nil {
 		return err
 	}
-	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))
+	return provenance.ApplyFile(abs, provenance.Stamp{Origin: origin, WrittenBy: writtenBy})
 }

ingestion/internal/api/write_redirect_test.go

@@ -1,43 +0,0 @@
-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,6 +7,7 @@ import (
 	"fmt"
 	"io"
 	"io/fs"
+	"os"
 	"path/filepath"
 	"sort"
 	"strings"
@@ -62,10 +63,8 @@ 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)
 	}
 
-	// Written through the brain root, never through a symlinked _index.md
-	// (hyperguild#158).
-	_ = wingDir
-	return bfs.PutRegular("wiki/"+w+"/_index.md", []byte(b.String()))
+	dest := filepath.Join(wingDir, "_index.md")
+	return os.WriteFile(dest, []byte(b.String()), 0o644)
 }
 
 // BuildAllWingIndexes regenerates _index.md for every wing under brain/wiki/.

ingestion/internal/brain/tunnel.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"io/fs"
+	"os"
 	"path"
 	"path/filepath"
 	"strings"
@@ -175,23 +176,35 @@ func logFuzzyCandidates(brainDir, sourcePath string, cs []TunnelCandidate) error
 	if len(cs) == 0 {
 		return nil
 	}
-	// Appended through the brain root, never through a symlinked raw/ or
-	// log file (hyperguild#158).
-	bfs, err := brainfs.Open(brainDir)
-	if err != nil {
-		return fmt.Errorf("open brain: %w", err)
+	rawDir := filepath.Join(brainDir, "raw")
+	if err := os.MkdirAll(rawDir, 0o755); err != nil {
+		return 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")
+	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)
+	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
+		}
 	}
 	for _, c := range cs {
-		fmt.Fprintf(&buf, "- `%s` ↔ `%s` (term: %q)\n", sourcePath, c.TargetPath, c.MatchedTerm)
+		line := fmt.Sprintf("- `%s` ↔ `%s` (term: %q)\n", sourcePath, c.TargetPath, c.MatchedTerm)
+		if _, err := f.WriteString(line); err != nil {
+			return err
 		}
-	return bfs.AppendRegular(rel, []byte(buf.String()))
+	}
+	return nil
+}
+
+func fileExists(p string) bool {
+	_, err := os.Stat(p)
+	return err == nil
 }
 
 // WriteTunnel appends a bidirectional wikilink between sourcePath and

ingestion/internal/brain/writers_redirect_test.go

@@ -1,52 +0,0 @@
-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

@@ -136,142 +136,6 @@ 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) {

ingestion/internal/brainfs/brainfs_test.go

@@ -376,80 +376,3 @@ func TestReadAndWriteRegularRefuseAPathThatIsNotClean(t *testing.T) {
 	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/notes/edit_redirect_test.go

@@ -1,25 +0,0 @@
-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/pipeline/backfill.go

@@ -7,6 +7,8 @@ import (
 	"fmt"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"io/fs"
+	"os"
+	"path/filepath"
 	"strings"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/wiki"
@@ -88,7 +90,8 @@ func BackfillRefs(ctx context.Context, brainDir string) (int, error) {
 	}
 
 	for relPath, page := range pending {
-		if err := bfs.PutRegular(relPath, []byte(page.Content)); err != nil {
+		dest := filepath.Join(brainDir, filepath.FromSlash(relPath))
+		if err := os.WriteFile(dest, []byte(page.Content), 0o644); err != nil {
 			return 0, fmt.Errorf("write %s: %w", relPath, err)
 		}
 	}

ingestion/internal/pipeline/pipeline.go

@@ -9,6 +9,8 @@ import (
 	"fmt"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"io/fs"
+	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -126,6 +128,10 @@ 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(brainDir, page)
 			if err != nil {
 				return Result{}, err
@@ -144,9 +150,7 @@ func buildAndWrite(ctx context.Context, rawPages []RawPage, sourceSlug, date, br
 			if err != nil {
 				return Result{}, fmt.Errorf("stamp %s: %w", page.Path, err)
 			}
-			// Written through the brain root, never through a symlinked
-			// directory or page (hyperguild#158).
-			if err := writeBrainFile(brainDir, page.Path, []byte(stamped)); err != nil {
+			if err := os.WriteFile(dest, []byte(stamped), 0o644); err != nil {
 				return Result{}, fmt.Errorf("write %s: %w", page.Path, err)
 			}
 		}
@@ -197,17 +201,6 @@ func readSourcePage(brainDir, sourceSlug string) string {
 	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) {

ingestion/internal/pipeline/root_test.go

@@ -165,28 +165,3 @@ func TestBackfillRefsDoesNotCopyAPageSwappedInBehindASymlink(t *testing.T) {
 	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,6 +28,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"os"
 	"regexp"
 	"strings"
 
@@ -101,6 +102,24 @@ 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/symlinkguard/special_test.go

@@ -0,0 +1,104 @@
+package symlinkguard
+
+import (
+	"context"
+	"net"
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// hyperguild#179: the tripwire looked only for symlinks, so a FIFO (or
+// socket) in the brain passed it. A FIFO at classification.yaml then made
+// startup exit; at a note path it could hang readers that skip the handle
+// check.
+func TestScanReportsFIFOsAndSocketsAsSpecialFiles(t *testing.T) {
+	brain := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki", "w"), 0o755))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(brain, "classification.yaml"), 0o644))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(brain, "wiki", "w", "f.md"), 0o644))
+	l, err := net.Listen("unix", filepath.Join(brain, "s.sock"))
+	require.NoError(t, err)
+	defer func() { _ = l.Close() }()
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "w", "n.md"), []byte("n"), 0o644))
+
+	r, err := Scan(brain)
+	require.NoError(t, err)
+	assert.Equal(t, []string{"classification.yaml", "s.sock", "wiki/w/f.md"}, r.Special)
+	assert.False(t, r.Clean())
+	assert.Contains(t, r.String(), "special file")
+}
+
+// Watch removes a FIFO as it removes symlinks, and leaves a regular file
+// (which Scan never reports) alone.
+func TestWatchRemovesAFIFOAndLeavesAnUnreportedRegularFile(t *testing.T) {
+	brain := t.TempDir()
+	fifo := filepath.Join(brain, "f.md")
+	require.NoError(t, syscall.Mkfifo(fifo, 0o644))
+	regular := filepath.Join(brain, "n.md")
+	require.NoError(t, os.WriteFile(regular, []byte("n"), 0o644))
+	n := &recNotifier{}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go Watch(ctx, brain, 10*time.Millisecond, n)
+	require.Eventually(t, func() bool {
+		_, err := os.Lstat(fifo)
+		return os.IsNotExist(err)
+	}, 2*time.Second, 10*time.Millisecond, "the FIFO is removed")
+	require.Eventually(t, func() bool { return n.count() >= 1 }, 2*time.Second, 10*time.Millisecond)
+	b, err := os.ReadFile(regular)
+	require.NoError(t, err)
+	assert.Equal(t, "n", string(b))
+	n.mu.Lock()
+	defer n.mu.Unlock()
+	assert.Contains(t, n.msgs[0], "f.md")
+}
+
+// removeSpecial re-checks the type: a path that is a regular file or a
+// directory at the re-check is not removed. (A swap between the re-check and
+// the unlink can still remove one; Linux has no conditional unlink. The same
+// window exists in removeSymlinks.)
+func TestRemoveSpecialRefusesRegularFilesAndDirectories(t *testing.T) {
+	brain := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "n.md"), []byte("n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "d"), 0o755))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(brain, "f.md"), 0o644))
+	removed, failed := removeSpecial(brain, []string{"n.md", "d", "f.md"})
+	assert.Equal(t, []string{"f.md"}, removed)
+	assert.Equal(t, []string{"n.md", "d"}, failed)
+	_, err := os.Stat(filepath.Join(brain, "n.md"))
+	assert.NoError(t, err)
+}
+
+// A special file Watch cannot remove (its directory is read-only) stays
+// reported: the persistent-finding alert names it.
+func TestWatchReportsASpecialFileItCannotRemove(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root ignores directory permissions")
+	}
+	brain := t.TempDir()
+	ro := filepath.Join(brain, "ro")
+	require.NoError(t, os.MkdirAll(ro, 0o755))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(ro, "f.md"), 0o644))
+	require.NoError(t, os.Chmod(ro, 0o555))
+	t.Cleanup(func() { _ = os.Chmod(ro, 0o755) })
+	n := &recNotifier{}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go Watch(ctx, brain, 10*time.Millisecond, n)
+	require.Eventually(t, func() bool { return n.count() >= 1 }, 2*time.Second, 10*time.Millisecond)
+	_, err := os.Lstat(filepath.Join(ro, "f.md"))
+	require.NoError(t, err, "the FIFO could not be removed")
+	n.mu.Lock()
+	defer n.mu.Unlock()
+	assert.Contains(t, n.msgs[0], "ro/f.md")
+	assert.Contains(t, n.msgs[0], "special file")
+	for _, m := range n.msgs {
+		assert.NotContains(t, m, "removed", "a file it could not remove was reported as removed")
+	}
+}

ingestion/internal/symlinkguard/symlinkguard.go

@@ -46,10 +46,16 @@ type Notifier interface {
 type Result struct {
 	Symlinks   []string
 	Unreadable []string
+	// Special holds FIFOs, sockets and devices (hyperguild#179): a reader
+	// that opens one by path can hang, and a FIFO at classification.yaml
+	// stops startup.
+	Special []string
 }
 
 // Clean reports whether the scan found nothing to act on.
-func (r Result) Clean() bool { return len(r.Symlinks) == 0 && len(r.Unreadable) == 0 }
+func (r Result) Clean() bool {
+	return len(r.Symlinks) == 0 && len(r.Unreadable) == 0 && len(r.Special) == 0
+}
 
 // String describes the findings for a log line or alert. Paths are quoted, so
 // a name containing a newline cannot blur two findings together.
@@ -59,6 +65,9 @@ func (r Result) String() string {
 	if len(r.Symlinks) > 0 {
 		parts = append(parts, fmt.Sprintf("%d symlink(s): %s", len(r.Symlinks), q(r.Symlinks)))
 	}
+	if len(r.Special) > 0 {
+		parts = append(parts, fmt.Sprintf("%d special file(s) (FIFO, socket or device; delete them): %s", len(r.Special), q(r.Special)))
+	}
 	if len(r.Unreadable) > 0 {
 		parts = append(parts, fmt.Sprintf("%d unreadable dir(s): %s", len(r.Unreadable), q(r.Unreadable)))
 	}
@@ -113,12 +122,16 @@ func Scan(brainDir string) (Result, error) {
 		if d.IsDir() && p == rootGit {
 			return filepath.SkipDir
 		}
-		if d.Type()&os.ModeSymlink != 0 {
+		switch {
+		case d.Type()&os.ModeSymlink != 0:
 			r.Symlinks = append(r.Symlinks, rel)
+		case !d.IsDir() && !d.Type().IsRegular():
+			r.Special = append(r.Special, rel)
 		}
 		return nil
 	})
 	sort.Strings(r.Symlinks)
+	sort.Strings(r.Special)
 	sort.Strings(r.Unreadable)
 	if walkErr != nil {
 		// Only the root's own error reaches here (deeper errors are recorded
@@ -182,14 +195,20 @@ func Watch(ctx context.Context, brainDir string, interval time.Duration, n Notif
 				q.push(fmt.Sprintf("brain symlink tripwire (hyperguild#157): removed %d symlink(s) from the brain dir: %s",
 					len(removed), Result{}.quoted(removed)))
 			}
-			key = Result{Symlinks: failed, Unreadable: r.Unreadable}.String()
+			sRemoved, sFailed := removeSpecial(brainDir, r.Special)
+			if len(sRemoved) > 0 {
+				slog.Error("brain symlink tripwire removed special files", "count", len(sRemoved))
+				q.push(fmt.Sprintf("brain symlink tripwire (hyperguild#179): removed %d special file(s) (FIFO, socket or device) from the brain dir: %s",
+					len(sRemoved), Result{}.quoted(sRemoved)))
+			}
+			key = Result{Symlinks: failed, Unreadable: r.Unreadable, Special: sFailed}.String()
 		}
 		if key != reported {
 			reported = key
 			if key != "" {
 				slog.Error("brain symlink tripwire", "finding", key)
-				q.push("brain symlink tripwire (hyperguild#157): " + key +
-					". Readers may follow symlinks out of the brain; fix them.")
+				q.push("brain symlink tripwire (hyperguild#157, #179): " + key +
+					". Symlinks can lead readers out of the brain and special files can hang them; remove them.")
 			}
 		}
 	}
@@ -322,6 +341,40 @@ func permanent(err error) bool {
 	return errors.As(err, &p) && p.Permanent()
 }
 
+// removeSpecial unlinks each brain-relative FIFO, socket or device through
+// an os.Root on the brain dir, after re-checking that it is still one: a
+// path that is a regular file, a directory or a symlink at the re-check is
+// left alone and reported as failed. The re-check narrows, but cannot close,
+// the window before the unlink (Linux has no conditional unlink); the same
+// window exists in removeSymlinks, and only a local writer can use it.
+func removeSpecial(brainDir string, rels []string) (removed, failed []string) {
+	if len(rels) == 0 {
+		return nil, nil
+	}
+	resolved, err := filepath.EvalSymlinks(brainDir)
+	if err != nil {
+		return nil, rels
+	}
+	root, err := os.OpenRoot(resolved)
+	if err != nil {
+		return nil, rels
+	}
+	defer func() { _ = root.Close() }()
+	for _, rel := range rels {
+		fi, err := root.Lstat(rel)
+		if err != nil || fi.IsDir() || fi.Mode().IsRegular() || fi.Mode()&os.ModeSymlink != 0 {
+			failed = append(failed, rel)
+			continue
+		}
+		if err := root.Remove(rel); err != nil {
+			failed = append(failed, rel)
+			continue
+		}
+		removed = append(removed, rel)
+	}
+	return removed, failed
+}
+
 // removeSymlinks unlinks each brain-relative symlink through an os.Root on
 // the brain dir, after re-checking it is still a symlink. Removing a symlink
 // never touches its target. It returns what was removed and what was not.

ingestion/internal/watcher/watcher.go

@@ -12,7 +12,6 @@ import (
 	"time"
 	"unicode"
 
-	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/extract"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 )
@@ -146,12 +145,16 @@ 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. Both
-		// written through the brain root (hyperguild#158).
-		if cpErr := copyFromRoot(root, rel, cfg.BrainDir, "raw/failed/"+filename); cpErr != 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 {
 			return fmt.Errorf("copy to failed: %w", cpErr)
 		}
-		if mkErr := putBrainFile(cfg.BrainDir, "raw/"+filepath.ToSlash(rel)+".failed", []byte(runErr.Error())); mkErr != nil {
+		if mkErr := os.WriteFile(path+".failed", []byte(runErr.Error()), 0o644); mkErr != nil {
 			slog.Error("watcher: failed to write .failed marker", "error", mkErr)
 		}
 
@@ -165,18 +168,21 @@ 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.
-	// 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 {
+	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 {
 		// Archive copy already exists; append timestamp to avoid overwriting.
 		ext := filepath.Ext(filename)
 		base := strings.TrimSuffix(filename, ext)
-		dest = "raw/processed/" + date + "/" + base + "-" + time.Now().UTC().Format("150405") + ext
+		dest = filepath.Join(processedDir, base+"-"+time.Now().UTC().Format("150405")+ext)
 	}
-	if err := copyFromRoot(root, rel, cfg.BrainDir, dest); err != nil {
+	if err := copyFromRoot(root, rel, dest); err != nil {
 		return fmt.Errorf("copy to processed: %w", err)
 	}
-	if err := putBrainFile(cfg.BrainDir, "raw/"+filepath.ToSlash(rel)+".processed", []byte(date)); err != nil {
+	if err := os.WriteFile(path+".processed", []byte(date), 0o644); err != nil {
 		slog.Error("watcher: failed to write .processed marker", "error", err)
 	}
 
@@ -208,22 +214,23 @@ 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())
 
-	if err := brainfs.AppendFile(brainDir, "log.md", []byte(entry)); err != nil {
+	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
 		return fmt.Errorf("write log: %w", err)
 	}
-	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)
+	return f.Close()
 }
 
 // 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, brainDir, dstRel string) error {
+func copyFromRoot(root *os.Root, rel, dst string) error {
 	fi, err := root.Lstat(rel)
 	if err != nil {
 		return err
@@ -236,9 +243,13 @@ func copyFromRoot(root *os.Root, rel, brainDir, dstRel string) error {
 		return err
 	}
 	defer func() { _ = in.Close() }()
-	data, err := io.ReadAll(in)
+	out, err := os.Create(dst)
 	if err != nil {
 		return err
 	}
-	return putBrainFile(brainDir, dstRel, data)
+	if _, err := io.Copy(out, in); err != nil {
+		_ = out.Close()
+		return err
+	}
+	return out.Close()
 }

ingestion/internal/watcher/writes_redirect_test.go

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

ingestion/internal/wiki/log.go

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

ingestion/internal/wiki/writers_redirect_test.go

@@ -1,35 +0,0 @@
-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")
-}