test(brain_edit): the rollback test proves the swap happened (#192)

Review round 2 on PR #194: with the hook made a no-op the test still
passed (no swap, the rollback wrote the real note, victim trivially
untouched). It now asserts the error says the edit could NOT be rolled
back and that the note path is still the swapped-in symlink; red when
the hook does not fire.

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)
@@ -184,9 +179,12 @@ func alertingWarnings(getenv func(string) string) []string {
 	return out
 }
 
-func buildNotifier() audit.Notifier {
-	if n := audit.NewNtfyNotifier(os.Getenv("BRAIN_NTFY_URL"), os.Getenv("BRAIN_NTFY_TOKEN")); n != nil {
-		return n
+// buildNotifier returns the ntfy notifier for one alert source, titled so
+// the source is recognisable (hyperguild#163), or nil when ntfy is not
+// configured.
+func buildNotifier(getenv func(string) string, title string) audit.Notifier {
+	if n := audit.NewNtfyNotifier(getenv("BRAIN_NTFY_URL"), getenv("BRAIN_NTFY_TOKEN")); n != nil {
+		return n.WithTitle(title)
 	}
 	return nil
 }
@@ -208,7 +206,7 @@ func buildAuditSink(ctx context.Context, brainDir string, logger *slog.Logger) c
 		logger.Error("capture audit buffer init", "err", err)
 		os.Exit(1)
 	}
-	notifier := buildNotifier()
+	notifier := buildNotifier(os.Getenv, "brain-capture audit degraded")
 	reconcileInterval := time.Duration(envInt("BRAIN_AUDIT_RECONCILE_INTERVAL", 60)) * time.Second
 	audit.StartReconcile(ctx, central, buffer, notifier, reconcileInterval)
 	logger.Info("capture audit: loki+buffer sink", "loki", lokiURL, "reconcile_s", int(reconcileInterval.Seconds()))
@@ -371,7 +369,7 @@ func main() {
 
 	ctx := context.Background()
 	// hyperguild#157: report a symlink that appears in the brain while running.
-	go symlinkguard.Watch(ctx, brainDir, symlinkScanInterval(os.Getenv), buildNotifier())
+	go symlinkguard.Watch(ctx, brainDir, symlinkScanInterval(os.Getenv), buildNotifier(os.Getenv, "brain symlink tripwire"))
 
 	// Never fatal on an unreachable issuer (#83): on a cold cluster boot this
 	// pod can beat dex to serving and get a 502 from ingress, and exiting meant
@@ -551,7 +549,7 @@ func main() {
 		// capture already gets, plus an out-of-band alert. Wired here because
 		// brain_edit_root needs the capture plumbing anyway — that is what
 		// re-derives the static principal its gate checks.
-		mcpSrv.WithGovernanceObserver(auditSink, buildNotifier())
+		mcpSrv.WithGovernanceObserver(auditSink, buildNotifier(os.Getenv, "brain governance edit"))
 		logger.Info("capture enabled (REST + MCP tool)", "sovereign_principals", len(sovereign),
 			"governance_observer", true)
 	} else {

ingestion/cmd/server/main_test.go

@@ -76,27 +76,3 @@ func TestAlertingWarnings(t *testing.T) {
 		})
 	}
 }
-
-// hyperguild#158: the claude-session archive was written with os.MkdirAll +
-// os.WriteFile by path, so a symlinked archive directory redirected it.
-func TestClaudeSinkDoesNotWriteThroughASymlinkedArchiveDir(t *testing.T) {
-	for name, mk := range map[string]func(t *testing.T, dir string) (link, target string){
-		"outside": func(t *testing.T, _ string) (string, string) { o := t.TempDir(); return o, o },
-		"in-brain": func(t *testing.T, dir string) (string, string) {
-			require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
-			return filepath.Join("..", "raw"), filepath.Join(dir, "raw")
-		},
-	} {
-		t.Run(name, func(t *testing.T) {
-			dir := t.TempDir()
-			link, target := mk(t, dir)
-			require.NoError(t, os.Symlink(link, filepath.Join(dir, "archive")))
-			sink := &claudeSink{brainDir: dir, logger: slog.New(slog.NewTextHandler(os.Stderr, nil))}
-			err := sink.Ingest(context.Background(), claudewatcher.Batch{Host: "koala", SessionID: "abc",
-				Turns: []claudewatcher.Turn{{Type: "assistant", Content: "x"}}})
-			assert.Error(t, err)
-			ents, _ := os.ReadDir(target)
-			assert.Empty(t, ents, "the archive was written at the link's target")
-		})
-	}
-}

ingestion/cmd/server/symlink_check_test.go

@@ -1,6 +1,9 @@
 package main
 
 import (
+	"context"
+	"net/http"
+	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"strings"
@@ -74,3 +77,16 @@ func TestStartupSymlinkCheckRefusesABrainWithAFIFO(t *testing.T) {
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "classification.yaml")
 }
+
+// hyperguild#163: each alert source gets its own ntfy title.
+func TestBuildNotifierUsesTheGivenTitle(t *testing.T) {
+	var got string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { got = r.Header.Get("Title") }))
+	defer srv.Close()
+	env := map[string]string{"BRAIN_NTFY_URL": srv.URL}
+	n := buildNotifier(func(k string) string { return env[k] }, "brain symlink tripwire")
+	require.NotNil(t, n)
+	require.NoError(t, n.Notify(context.Background(), "m"))
+	assert.Equal(t, "brain symlink tripwire", got)
+	assert.Nil(t, buildNotifier(func(string) string { return "" }, "x"), "no ntfy URL, no notifier")
+}

ingestion/internal/audit/ntfy.go

@@ -13,9 +13,14 @@ import (
 type NtfyNotifier struct {
 	topicURL string
 	token    string
+	title    string
 	http     *http.Client
 }
 
+// defaultNtfyTitle is the title of a notifier built without WithTitle: the
+// capture audit's degraded-state alert, its first user.
+const defaultNtfyTitle = "brain-capture audit degraded"
+
 // NewNtfyNotifier constructs a notifier for the given ntfy topic URL
 // (e.g. https://ntfy.sh/my-topic). token is an optional bearer for
 // protected ntfy instances; it is held here and only sent in the
@@ -27,17 +32,31 @@ func NewNtfyNotifier(topicURL, token string) *NtfyNotifier {
 	return &NtfyNotifier{
 		topicURL: strings.TrimRight(topicURL, "/"),
 		token:    token,
+		title:    defaultNtfyTitle,
 		http:     &http.Client{Timeout: 10 * time.Second},
 	}
 }
 
+// WithTitle returns a copy that sends title as the ntfy Title header, so each
+// alert source (the capture audit, the symlink tripwire, governance edits)
+// is recognisable on the phone (hyperguild#163). A nil notifier (ntfy not
+// configured) stays nil.
+func (n *NtfyNotifier) WithTitle(title string) *NtfyNotifier {
+	if n == nil {
+		return nil
+	}
+	c := *n
+	c.title = title
+	return &c
+}
+
 // Notify posts a message to the ntfy topic.
 func (n *NtfyNotifier) Notify(ctx context.Context, msg string) error {
 	req, err := http.NewRequestWithContext(ctx, http.MethodPost, n.topicURL, strings.NewReader(msg))
 	if err != nil {
 		return err
 	}
-	req.Header.Set("Title", "brain-capture audit degraded")
+	req.Header.Set("Title", n.title)
 	req.Header.Set("Priority", "high")
 	req.Header.Set("Tags", "warning,brain")
 	if n.token != "" {

ingestion/internal/audit/ntfy_title_test.go

@@ -0,0 +1,29 @@
+package audit
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// hyperguild#163: every alert went out titled "brain-capture audit
+// degraded", including the symlink tripwire's and governance alerts.
+func TestNtfyNotifierSendsItsOwnTitle(t *testing.T) {
+	var got []string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		got = append(got, r.Header.Get("Title"))
+	}))
+	defer srv.Close()
+	base := NewNtfyNotifier(srv.URL, "")
+	require.NoError(t, base.Notify(context.Background(), "m"))
+	require.NoError(t, base.WithTitle("brain symlink tripwire").Notify(context.Background(), "m"))
+	require.NoError(t, base.Notify(context.Background(), "m"))
+	assert.Equal(t, []string{"brain-capture audit degraded", "brain symlink tripwire", "brain-capture audit degraded"}, got,
+		"WithTitle returns a copy; the base keeps its default title")
+	var nilN *NtfyNotifier
+	assert.Nil(t, nilN.WithTitle("x"), "nil (ntfy not configured) stays nil")
+}

ingestion/internal/brainfs/brainfs.go

@@ -22,6 +22,10 @@ import (
 // ErrNotRegular is returned for an entry that is not a regular file.
 var ErrNotRegular = errors.New("not a regular file")
 
+// ErrLockChanged is returned by OpenLock when the lock file was replaced
+// while it was being opened.
+var ErrLockChanged = errors.New("lock file replaced while opening")
+
 // ErrTooLarge is returned by ReadRegularMax for a file over the limit.
 var ErrTooLarge = errors.New("file too large")
 
@@ -109,7 +113,7 @@ func (b *Brain) ReadDirRegular(relDir string) ([]string, error) {
 // 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) {
+	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
@@ -243,27 +247,6 @@ func (b *Brain) RealParent(rel string) error {
 	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.
@@ -291,6 +274,54 @@ func (b *Brain) mkdirReal(rel string) error {
 	return nil
 }
 
+// OpenLock opens (creating if absent) a regular lock file at a clean
+// brain-relative path for flock, through the root (hyperguild#192): every
+// directory above it must be real, an existing lock must be a regular file,
+// and the opened handle must be the file at the path (os.Root follows an
+// in-root final symlink even with O_NOFOLLOW, so the Lstat pre-check is
+// what refuses a dangling in-brain link). A link swapped in between the
+// pre-check and the open can still have an empty file created at an in-brain
+// target before the refusal: the #167 residual. ErrLockChanged reports a
+// lock replaced while opening (a peer removed and recreated it); callers
+// retry.
+func (b *Brain) OpenLock(rel string) (*os.File, error) {
+	if err := b.RealParent(rel); err != nil {
+		return nil, err
+	}
+	if fi, err := b.root.Lstat(rel); err == nil && !fi.Mode().IsRegular() {
+		return nil, fmt.Errorf("%s: %w", rel, ErrNotRegular)
+	} else if err != nil && !errors.Is(err, fs.ErrNotExist) {
+		return nil, err
+	}
+	f, err := b.root.OpenFile(rel, os.O_RDWR|os.O_CREATE|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0o644)
+	if err != nil {
+		return nil, err
+	}
+	hfi, herr := f.Stat()
+	lfi, lerr := b.root.Lstat(rel)
+	if herr != nil || !hfi.Mode().IsRegular() {
+		_ = f.Close()
+		return nil, fmt.Errorf("%s: %w", rel, ErrNotRegular)
+	}
+	if lerr != nil || !os.SameFile(lfi, hfi) {
+		_ = f.Close()
+		if lerr == nil && !lfi.Mode().IsRegular() {
+			return nil, fmt.Errorf("%s: %w", rel, ErrNotRegular)
+		}
+		return nil, fmt.Errorf("%s: %w", rel, ErrLockChanged)
+	}
+	return f, nil
+}
+
+// LockIsCurrent reports whether f is still the file at rel: after taking a
+// flock, a lock file removed and recreated by a peer means the flock is on
+// an orphaned inode and does not exclude anyone (hyperguild#192).
+func (b *Brain) LockIsCurrent(rel string, f *os.File) bool {
+	hfi, herr := f.Stat()
+	lfi, lerr := b.root.Lstat(rel)
+	return herr == nil && lerr == nil && os.SameFile(lfi, hfi)
+}
+
 // 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

@@ -530,19 +530,48 @@ func TestCreateRegularCreatesOnlyNewFilesThroughRealDirectories(t *testing.T) {
 	assert.Equal(t, "one", string(got))
 }
 
-// On Linux a backslash is an ordinary filename byte, not a separator, so a
-// name containing one stays a single in-root component (hyperguild#158: the
-// watcher retried such a note forever while cleanRel refused it).
-func TestReadAndPutRegularTreatABackslashAsAFilenameByte(t *testing.T) {
+// hyperguild#192: OpenLock creates or reuses a regular lock file through the
+// root and refuses every other shape without creating anything at a link's
+// target or hanging.
+func TestOpenLockOpensOnlyARegularLockThroughRealDirectories(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", "w"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "raw", "v.md"), []byte("untouched"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "created"), filepath.Join(dir, "wiki", "w", "dangling.lock")))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "v.md"), filepath.Join(dir, "wiki", "w", "live.lock")))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(dir, "wiki", "w", "fifo.lock"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki", "w", "dir.lock"), 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() }()
-	require.NoError(t, b.PutRegular(`a\..\b.md`, []byte("x")))
-	got, err := os.ReadFile(filepath.Join(dir, `a\..\b.md`))
-	require.NoError(t, err, "the name was not kept as one component")
-	assert.Equal(t, "x", string(got))
-	got, err = b.ReadRegular(`a\..\b.md`)
-	require.NoError(t, err)
-	assert.Equal(t, "x", string(got))
+
+	for _, rel := range []string{"wiki/w/dangling.lock", "wiki/w/live.lock", "wiki/w/fifo.lock", "wiki/w/dir.lock", "wiki/alias/x.lock", "wiki/w/../w/x.lock"} {
+		done := make(chan error, 1)
+		go func() {
+			f, err := b.OpenLock(rel)
+			if f != nil {
+				_ = f.Close()
+			}
+			done <- err
+		}()
+		select {
+		case err := <-done:
+			assert.ErrorIs(t, err, ErrNotRegular, rel)
+		case <-time.After(3 * time.Second):
+			t.Fatalf("OpenLock hung on %s", rel)
+		}
+	}
+	_, err = os.Lstat(filepath.Join(dir, "raw", "created"))
+	assert.True(t, os.IsNotExist(err), "nothing created at the dangling link's target")
+	got, _ := os.ReadFile(filepath.Join(dir, "raw", "v.md"))
+	assert.Equal(t, "untouched", string(got))
+
+	f, err := b.OpenLock("wiki/w/n.md.lock")
+	require.NoError(t, err, "positive control: creates a lock")
+	assert.True(t, b.LockIsCurrent("wiki/w/n.md.lock", f))
+	require.NoError(t, b.Remove("wiki/w/n.md.lock"))
+	assert.False(t, b.LockIsCurrent("wiki/w/n.md.lock", f), "a removed lock is no longer current")
+	_ = f.Close()
 }

ingestion/internal/extract/callsites_test.go

@@ -88,6 +88,7 @@ func TestNoPackageReferencesExtractTextOutsideExtract(t *testing.T) {
 // osOpenAllowed names the functions in guarded files that may call os.Open*
 // on a path that is not a raw/ read.
 var osOpenAllowed = map[string]bool{
+	"internal/watcher/watcher.go:appendWatcherLog": true, // ingest log append, not a raw/ read
 	// Text reads by path; outside this package only TextIn's temp copy reaches
 	// it (TestNoPackageReferencesExtractTextOutsideExtract enforces that).
 	"internal/extract/extract.go:Text": true,

ingestion/internal/mcp/edit_pathio_test.go

@@ -0,0 +1,124 @@
+package mcp_test
+
+import (
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/audit"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainstore"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capturehttp"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/mcp"
+)
+
+// hyperguild#192: brain_edit snapshotted the note with os.ReadFile by path,
+// which blocks on a FIFO held open by a writer, and hung the call.
+func TestBrainEditReturnsPromptlyOnAFIFONoteWithAWriter(t *testing.T) {
+	dir := newBrainRepo(t)
+	fifo := filepath.Join(dir, "wiki", "homelab", "facts", "f.md")
+	require.NoError(t, syscall.Mkfifo(fifo, 0o644))
+	w, err := os.OpenFile(fifo, os.O_RDWR, 0)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = w.Close() })
+	srv := mcp.NewServer(dir, nil, nil, nil)
+
+	done := make(chan map[string]any, 1)
+	go func() {
+		done <- call(t, srv, "brain_edit", map[string]any{"path": "wiki/homelab/facts/f.md", "old_str": "a", "new_str": "b"})
+	}()
+	select {
+	case resp := <-done:
+		assert.Contains(t, resp, "error", "a FIFO note is refused")
+	case <-time.After(3 * time.Second):
+		t.Fatal("brain_edit hung on a FIFO note")
+	}
+
+	resp := call(t, srv, "brain_edit", map[string]any{"path": "wiki/homelab/facts/n.md", "old_str": "beta", "new_str": "BETA"})
+	require.NotContains(t, resp, "error", "positive control: a regular note is edited: %v", resp["error"])
+}
+
+// hyperguild#192: the edit lock "<note>.lock" was opened by path with
+// O_CREATE, so a planted dangling .lock symlink made a successful edit create
+// a file at the link's target, outside the brain or elsewhere in it.
+func TestBrainEditDoesNotCreateAFileThroughADanglingLockSymlink(t *testing.T) {
+	for name, target := range map[string]func(t *testing.T, dir string) string{
+		"outside":  func(t *testing.T, _ string) string { return filepath.Join(t.TempDir(), "created") },
+		// Relative, as Syncthing carries it: os.Root refuses an absolute
+		// link on its own, so only OpenLock's pre-check stops this one.
+		"in-brain": func(t *testing.T, dir string) string { return filepath.Join(dir, "raw", "created") },
+	} {
+		t.Run(name, func(t *testing.T) {
+			dir := newBrainRepo(t)
+			require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
+			tgt := target(t, dir)
+			lock := filepath.Join(dir, "wiki", "homelab", "facts", "n.md.lock")
+			linkTo := tgt
+			if name == "in-brain" {
+				rel, err := filepath.Rel(filepath.Dir(lock), tgt)
+				require.NoError(t, err)
+				linkTo = rel
+			}
+			require.NoError(t, os.Symlink(linkTo, lock))
+			srv := mcp.NewServer(dir, nil, nil, nil)
+			resp := call(t, srv, "brain_edit", map[string]any{"path": "wiki/homelab/facts/n.md", "old_str": "beta", "new_str": "BETA"})
+			require.NotNil(t, resp["error"], "the edit is refused")
+			assert.Contains(t, resp["error"].(map[string]any)["message"], "lock", "refused because of the lock file")
+			_, err := os.Lstat(tgt)
+			assert.True(t, os.IsNotExist(err), "a file was created at the lock symlink's target")
+		})
+	}
+}
+
+// The rollback (when the stamp cannot be verified) writes the prior bytes
+// through the brain root: a symlink swapped in for the note before the
+// rollback is refused, and its target, in the brain or outside, is
+// untouched.
+func TestBrainEditRollbackDoesNotWriteThroughASymlinkSwappedInForTheNote(t *testing.T) {
+	for name, mk := range map[string]func(t *testing.T, dir string) (link, victim string){
+		"outside": func(t *testing.T, _ string) (string, string) {
+			v := filepath.Join(t.TempDir(), "victim.md")
+			return v, v
+		},
+		"in-brain": func(t *testing.T, dir string) (string, string) {
+			return filepath.Join("..", "..", "..", "raw", "victim.md"), filepath.Join(dir, "raw", "victim.md")
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			dir := newBrainRepo(t)
+			require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
+			cfg, err := classification.Load(dir)
+			require.NoError(t, err)
+			svc := capture.NewService(brainstore.New(dir), capFakeTracker{}, cfg, audit.NewSlogSink(nil))
+			srv := mcp.NewServer(dir, nil, nil, nil)
+			srv.WithCapture(svc, capFakeValidator{subject: "bad\xff"}, capStaticTok, "local-cli", capturehttp.NewOriginResolver(nil))
+			out := resultText(t, authCall(t, srv, "Bearer "+capStaticTok, "brain_write", map[string]any{
+				"content": "# R\n\nstatic body", "wing": "testing", "hall": "facts", "filename": "rb",
+			}))
+			path := out["path"].(string)
+			note := filepath.Join(dir, path)
+			link, victim := mk(t, dir)
+			require.NoError(t, os.WriteFile(victim, []byte("untouched"), 0o644))
+			defer mcp.SetBeforeStampHook(func() {
+				require.NoError(t, os.Remove(note))
+				require.NoError(t, os.Symlink(link, note))
+			})()
+			resp := authCall(t, srv, jwtAuthz, "brain_edit", map[string]any{"path": path, "old_str": "static body", "new_str": "injected"})
+			require.NotNil(t, resp["error"])
+			// The swap happened and the rollback refused it: the error says so,
+			// and the note path is still the planted symlink.
+			assert.Contains(t, resp["error"].(map[string]any)["message"], "could NOT be rolled back")
+			fi, err := os.Lstat(note)
+			require.NoError(t, err)
+			assert.NotZero(t, fi.Mode()&os.ModeSymlink, "the note path is still the swapped-in symlink")
+			got, _ := os.ReadFile(victim)
+			assert.Equal(t, "untouched", string(got), "the rollback wrote through the swapped-in symlink")
+		})
+	}
+}

ingestion/internal/mcp/export_test.go

@@ -0,0 +1,9 @@
+package mcp
+
+// SetBeforeStampHook installs beforeStampHook for a test and returns a
+// restore func.
+func SetBeforeStampHook(f func()) func() {
+	old := beforeStampHook
+	beforeStampHook = f
+	return func() { beforeStampHook = old }
+}

ingestion/internal/mcp/tools_notes.go

@@ -6,8 +6,8 @@ import (
 	"errors"
 	"fmt"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"log/slog"
-	"os"
 	"strings"
 	"time"
 
@@ -118,7 +118,14 @@ func (s *Server) brainEdit(ctx context.Context, args json.RawMessage) (json.RawM
 		return nil, err
 	}
 	// No snapshot, no edit: without one a failed stamp could not be undone.
-	prior, err := os.ReadFile(target.Abs)
+	// Read through the brain root, regular files only (hyperguild#192): a
+	// FIFO held open by a writer hung os.ReadFile.
+	bfs, err := brainfs.Open(s.brainDir)
+	if err != nil {
+		return nil, fmt.Errorf("snapshot before edit: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	prior, err := bfs.ReadRegular(target.Rel)
 	if err != nil {
 		return nil, fmt.Errorf("snapshot before edit: %w", err)
 	}
@@ -130,8 +137,11 @@ func (s *Server) brainEdit(ctx context.Context, args json.RawMessage) (json.RawM
 	// whoever edits a note is the author of what a reader now sees: re-stamp
 	// to the editor after every edit (PR #147 review, escape E1).
 	origin, writtenBy := provenanceFrom(ctx)
+	if beforeStampHook != nil {
+		beforeStampHook()
+	}
 	if serr := api.StampProvenanceFile(s.brainDir, res.Path, origin, writtenBy); serr != nil {
-		if werr := os.WriteFile(target.Abs, prior, 0o644); werr != nil {
+		if werr := bfs.WriteRegular(target.Rel, prior); werr != nil {
 			// Say exactly what state the note is in: edited, unverified.
 			return nil, fmt.Errorf("stamp provenance failed (%v) AND the edit could NOT be rolled back: %w; "+
 				"%s carries the edit under its previous attribution", serr, werr, res.Path)
@@ -141,6 +151,11 @@ func (s *Server) brainEdit(ctx context.Context, args json.RawMessage) (json.RawM
 	return out, nil
 }
 
+// beforeStampHook is a test seam (nil in production): it runs between the
+// edit and the provenance stamp, so a test can swap the note before the
+// rollback path runs.
+var beforeStampHook func()
+
 // brainEditRoot edits a governance file (CLAUDE.md). De-surfaced AND gated on
 // the authenticated principal: only the static local-CLI token may call it, so
 // a claude.ai-origin session — the one that may have just read an untrusted

ingestion/internal/notes/edit.go

@@ -127,7 +127,7 @@ func Edit(brainDir, path, oldStr, newStr string, scope Scope) (Result, error) {
 	mu.Lock()
 	defer mu.Unlock()
 
-	unlock, err := flockFile(t.Abs)
+	unlock, err := flockFile(t)
 	if err != nil {
 		return Result{}, err
 	}
@@ -220,21 +220,49 @@ func lockFor(abs string) *sync.Mutex {
 }
 
 // flockFile takes an advisory lock covering other processes sharing the
-// hostPath — during a RollingUpdate two ingestion pods do.
-func flockFile(abs string) (func(), error) {
-	f, err := os.OpenFile(abs+".lock", os.O_CREATE|os.O_RDWR, 0o644)
+// hostPath — during a RollingUpdate two ingestion pods do. The lock file is
+// opened and removed through the brain root, never through a symlink
+// (hyperguild#192): a planted dangling "<note>.lock" link made a successful
+// edit create a file at its target.
+//
+// Unlock removes the lock file while still holding the flock, so a waiter
+// can wake holding a lock on an orphaned inode while the next caller locks a
+// fresh file: two editors at once (measured on main). After taking the
+// flock, the file must still be the one at the path; otherwise retry.
+func flockFile(t Target) (func(), error) {
+	lockRel := t.Rel + ".lock"
+	bfs, err := brainfs.Open(t.Brain)
 	if err != nil {
-		return nil, fmt.Errorf("notes: lock %s: %w", filepath.Base(abs), err)
+		return nil, fmt.Errorf("notes: lock %s: %w", lockRel, err)
+	}
+	for attempt := 0; attempt < 1000; attempt++ {
+		f, err := bfs.OpenLock(lockRel)
+		if errors.Is(err, brainfs.ErrLockChanged) {
+			continue
+		}
+		if err != nil {
+			_ = bfs.Close()
+			return nil, fmt.Errorf("notes: lock %s: %w", lockRel, err)
 		}
 		if err := syscall.Flock(int(f.Fd()), syscall.LOCK_EX); err != nil {
 			_ = f.Close()
-		return nil, fmt.Errorf("notes: flock %s: %w", filepath.Base(abs), err)
+			_ = bfs.Close()
+			return nil, fmt.Errorf("notes: flock %s: %w", lockRel, err)
 		}
-	return func() {
+		if !bfs.LockIsCurrent(lockRel, f) {
 			_ = syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
 			_ = f.Close()
-		_ = os.Remove(abs + ".lock")
+			continue
+		}
+		return func() {
+			_ = bfs.Remove(lockRel)
+			_ = syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
+			_ = f.Close()
+			_ = bfs.Close()
 		}, nil
+	}
+	_ = bfs.Close()
+	return nil, fmt.Errorf("notes: lock %s: kept changing while locking", lockRel)
 }
 
 // writeAtomic replaces the file via a same-directory temp + rename, then

ingestion/internal/notes/lock_xproc_test.go

@@ -0,0 +1,82 @@
+package notes
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// lockChild runs inside a re-executed test binary: it takes the note's edit
+// lock N times and, while holding it, creates an O_EXCL marker. Finding the
+// marker already there means another process holds the "same" lock: mutual
+// exclusion failed. It prints the overlap count.
+func lockChild(brainDir string, rounds int) {
+	t, err := Resolve(brainDir, "wiki/w/facts/n.md", ScopeNotes)
+	if err != nil {
+		fmt.Println("resolve:", err)
+		os.Exit(2)
+	}
+	marker := filepath.Join(brainDir, "marker")
+	overlaps := 0
+	for i := 0; i < rounds; i++ {
+		unlock, err := flockFile(t)
+		if err != nil {
+			fmt.Println("lock:", err)
+			os.Exit(2)
+		}
+		f, err := os.OpenFile(marker, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644)
+		if errors.Is(err, os.ErrExist) {
+			overlaps++
+		} else if err == nil {
+			_ = f.Close()
+			_ = os.Remove(marker)
+		}
+		unlock()
+	}
+	fmt.Println(overlaps)
+	os.Exit(0)
+}
+
+func TestMain(m *testing.M) {
+	if dir := os.Getenv("NOTES_LOCK_CHILD"); dir != "" {
+		n, _ := strconv.Atoi(os.Getenv("NOTES_LOCK_ROUNDS"))
+		lockChild(dir, n)
+	}
+	os.Exit(m.Run())
+}
+
+// hyperguild#192: the edit lock must exclude other processes (two ingestion
+// pods share the hostPath brain during a RollingUpdate). Unlock removes the
+// lock file, so without re-checking that the locked file is still the one at
+// the path, a waiter and the next caller each held a lock (measured on main:
+// hundreds of overlaps in 2000 rounds).
+func TestEditLockExcludesOtherProcesses(t *testing.T) {
+	brain := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki", "w", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "w", "facts", "n.md"), []byte("x"), 0o644))
+	const procs, rounds = 3, 400
+	cmds := make([]*exec.Cmd, procs)
+	outs := make([]*strings.Builder, procs)
+	for i := range cmds {
+		outs[i] = &strings.Builder{}
+		cmds[i] = exec.Command(os.Args[0], "-test.run=^$")
+		cmds[i].Env = append(os.Environ(), "NOTES_LOCK_CHILD="+brain, "NOTES_LOCK_ROUNDS="+strconv.Itoa(rounds))
+		cmds[i].Stdout, cmds[i].Stderr = outs[i], outs[i]
+		require.NoError(t, cmds[i].Start())
+	}
+	total := 0
+	for i, c := range cmds {
+		require.NoError(t, c.Wait(), "child %d: %s", i, outs[i].String())
+		n, err := strconv.Atoi(strings.TrimSpace(outs[i].String()))
+		require.NoError(t, err, "child %d output: %q", i, outs[i].String())
+		total += n
+	}
+	require.Zero(t, total, "processes held the edit lock at the same time")
+}

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,53 +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")
-}
-
-// hyperguild#158: buildAndWrite wrote each page with os.WriteFile by path, so
-// a page read as regular and swapped for a symlink before the write was
-// written through. The target is not restored between rounds, so any
-// write-through shows.
-func TestBuildAndWriteNeverWritesThroughAPageSwappedForASymlink(t *testing.T) {
-	brain := t.TempDir()
-	mkdirs(t, brain, "wiki/sources", "wiki/concepts", "wiki/entities", "raw")
-	page := filepath.Join(brain, "wiki", "concepts", "zq-concept.md")
-	target := filepath.Join(brain, "raw", "secret.md")
-	require.NoError(t, os.WriteFile(target, []byte("untouched"), 0o644))
-	inside := "---\ntitle: Zq Concept\n---\nbody\n"
-	require.NoError(t, os.WriteFile(page, []byte(inside), 0o644))
-	pages := []RawPage{{Title: "Zq Concept", Type: "concept", Content: "## About\n\nmore\n"}}
-	brainfstest.StartSwap(t, page, inside, target, false)
-	ok := 0
-	for deadline := time.Now().Add(2 * time.Second); time.Now().Before(deadline); {
-		if _, err := RunRaw(context.Background(), brain, "zq source", pages, false); err == nil {
-			ok++
-		}
-	}
-	got, _ := os.ReadFile(target)
-	assert.Equal(t, "untouched", string(got), "buildAndWrite wrote through a swapped-in symlink")
-	assert.Positive(t, ok, "positive control: some runs returned without error")
-}

ingestion/internal/symlinkguard/symlinkguard_test.go

@@ -381,18 +381,19 @@ func TestWatchQueueIsBoundedDuringAnOutage(t *testing.T) {
 		require.Eventually(t, func() bool { _, err := os.Lstat(link); return os.IsNotExist(err) }, 2*time.Second, 2*time.Millisecond)
 	}
 	n.down.Store(false)
-	require.Eventually(t, func() bool { return n.count() >= 1 }, 2*time.Second, 5*time.Millisecond)
-	time.Sleep(100 * time.Millisecond)
-	assert.LessOrEqual(t, n.count(), maxPending+1, "queued alerts plus at most one suppression summary")
+	// Synchronise on the summary being delivered (hyperguild#193: a fixed
+	// sleep flaked under load); once it is, the queue has been flushed.
+	require.Eventually(t, func() bool {
 		n.mu.Lock()
 		defer n.mu.Unlock()
-	found := false
 		for _, m := range n.msgs {
 			if strings.Contains(m, "suppressed") {
-			found = true
+				return true
 			}
 		}
-	assert.True(t, found, "suppressed alerts are counted in a summary")
+		return false
+	}, 10*time.Second, 5*time.Millisecond, "suppressed alerts are counted in a summary")
+	assert.LessOrEqual(t, n.count(), maxPending+1, "queued alerts plus at most one suppression summary")
 }
 
 // Within the bound, every alert queued during an outage is delivered after
@@ -411,11 +412,21 @@ func TestWatchDeliversEveryQueuedAlertAfterAShortOutage(t *testing.T) {
 		require.Eventually(t, func() bool { _, err := os.Lstat(link); return os.IsNotExist(err) }, 2*time.Second, 2*time.Millisecond)
 	}
 	n.down.Store(false)
-	require.Eventually(t, func() bool { return n.count() == 3 }, 2*time.Second, 5*time.Millisecond)
+	require.Eventually(t, func() bool { return n.count() >= 3 }, 10*time.Second, 5*time.Millisecond)
 	n.mu.Lock()
 	defer n.mu.Unlock()
-	for i, name := range []string{"qa", "qb", "qc"} {
-		assert.Contains(t, n.msgs[i], strconv.Quote(name))
+	// Each removal delivered exactly once, in any order: the outage ends
+	// asynchronously, possibly mid-flush, so a later item can send before an
+	// earlier one (hyperguild#193). Order is not what this test is about.
+	assert.Len(t, n.msgs, 3)
+	for _, name := range []string{"qa", "qb", "qc"} {
+		hits := 0
+		for _, m := range n.msgs {
+			if strings.Contains(m, strconv.Quote(name)) {
+				hits++
+			}
+		}
+		assert.Equal(t, 1, hits, "%s delivered exactly once", name)
 	}
 }
 
@@ -457,29 +468,30 @@ func TestWatchAccountsForEveryRemovalDuringAnOutage(t *testing.T) {
 		require.Eventually(t, func() bool { _, err := os.Lstat(link); return os.IsNotExist(err) }, 2*time.Second, 1*time.Millisecond)
 	}
 	n.down.Store(false)
-	require.Eventually(t, func() bool {
+	// Synchronise on the record being complete, not on a fixed sleep after
+	// the first summary (hyperguild#193): sum every "removed N" alert and
+	// every suppression count until they account for all plants.
+	account := func() (delivered, counted int) {
 		n.mu.Lock()
 		defer n.mu.Unlock()
 		for _, m := range n.msgs {
-			if strings.Contains(m, "suppressed") {
-				return true
+			var k int
+			if i := strings.Index(m, "removed "); i >= 0 && strings.Contains(m, "symlink(s)") {
+				if _, err := fmt.Sscanf(m[i+len("removed "):], "%d", &k); err == nil {
+					delivered += k
 				}
 			}
-		return false
-	}, 2*time.Second, 5*time.Millisecond)
-	time.Sleep(50 * time.Millisecond)
-	n.mu.Lock()
-	defer n.mu.Unlock()
-	delivered, counted := 0, 0
-	for _, m := range n.msgs {
-		if strings.Contains(m, "removed 1 symlink(s)") {
-			delivered++
-		}
 			if i := strings.Index(m, "): "); i >= 0 && strings.Contains(m, "suppressed") {
-			_, _ = fmt.Sscanf(m[i+3:], "%d", &counted)
+				if _, err := fmt.Sscanf(m[i+3:], "%d", &k); err == nil {
+					counted += k
 				}
 			}
-	assert.Equal(t, plants, delivered+counted, "delivered %d + counted %d must equal %d removals", delivered, counted, plants)
+		}
+		return delivered, counted
+	}
+	require.Eventually(t, func() bool { d, c := account(); return d+c >= plants }, 10*time.Second, 5*time.Millisecond)
+	d, c := account()
+	assert.Equal(t, plants, d+c, "delivered %d + counted %d must equal %d removals", d, c, plants)
 }
 
 // A poison message is still dropped (others send while it fails), and the

ingestion/internal/watcher/watcher.go

@@ -3,18 +3,15 @@ package watcher
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"io"
 	"log/slog"
 	"os"
 	"path/filepath"
 	"strings"
-	"sync"
 	"time"
 	"unicode"
 
-	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/extract"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 )
@@ -112,28 +109,14 @@ func processDir(ctx context.Context, cfg Config, date string) []error {
 		}
 
 		// Skip files that have already been processed or permanently failed.
-		// Any entry at the marker path counts (Lstat, not Stat): a dangling
-		// marker symlink made os.Stat report nothing and the note was
-		// reprocessed every interval (hyperguild#158).
-		if _, err := os.Lstat(path + ".processed"); err == nil {
+		if _, err := os.Stat(path + ".processed"); err == nil {
 			return nil
 		}
-		if _, err := os.Lstat(path + ".failed"); err == nil {
-			return nil
-		}
-		// A note whose archive copy or marker was refused is not retried
-		// until it changes: a refusal has no marker to stop the next round,
-		// and each round can cost an LLM call (hyperguild#158).
-		info, ierr := d.Info()
-		if ierr == nil && refusedUnchanged(path, info) {
+		if _, err := os.Stat(path + ".failed"); err == nil {
 			return nil
 		}
 
 		if err := processFile(ctx, cfg, root, rawDir, path, date); err != nil {
-			if ierr == nil && errors.Is(err, brainfs.ErrNotRegular) {
-				rememberRefused(path, info)
-				slog.Error("watcher: note refused; not retried until it changes", "file", filepath.Base(path), "error", err)
-			}
 			errs = append(errs, fmt.Errorf("process %s: %w", filepath.Base(path), err))
 		}
 		return nil
@@ -162,15 +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 errors.Is(mkErr, brainfs.ErrNotRegular) {
-				return fmt.Errorf("write .failed marker: %w", mkErr)
-			}
+		if mkErr := os.WriteFile(path+".failed", []byte(runErr.Error()), 0o644); mkErr != nil {
 			slog.Error("watcher: failed to write .failed marker", "error", mkErr)
 		}
 
@@ -184,21 +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 errors.Is(err, brainfs.ErrNotRegular) {
-			return fmt.Errorf("write .processed marker: %w", err)
-		}
+	if err := os.WriteFile(path+".processed", []byte(date), 0o644); err != nil {
 		slog.Error("watcher: failed to write .processed marker", "error", err)
 	}
 
@@ -206,32 +190,6 @@ func processFile(ctx context.Context, cfg Config, root *os.Root, rawDir, path, d
 	return nil
 }
 
-// refused remembers notes whose archive copy or marker write was refused,
-// by path, with the size and mtime they had, for the life of the process.
-var refused sync.Map
-
-type refusedStamp struct {
-	size  int64
-	mtime time.Time
-}
-
-func rememberRefused(path string, info os.FileInfo) {
-	refused.Store(path, refusedStamp{size: info.Size(), mtime: info.ModTime()})
-}
-
-func refusedUnchanged(path string, info os.FileInfo) bool {
-	v, ok := refused.Load(path)
-	if !ok {
-		return false
-	}
-	st := v.(refusedStamp)
-	if st.size == info.Size() && st.mtime.Equal(info.ModTime()) {
-		return true
-	}
-	refused.Delete(path)
-	return false
-}
-
 // deriveSource turns a filename into a human-readable source name.
 // "shape-up-book.md" → "Shape Up Book"
 func deriveSource(filename string) string {
@@ -256,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
@@ -284,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,186 +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 TestProcessDirDoesNotWriteThroughASymlinkedArchiveDir(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)))
-			_ = processDir(context.Background(), Config{BrainDir: brainDir, Interval: time.Hour, Pipeline: pcfg}, "2026-10-05")
-			got, _ := os.ReadFile(victim)
-			assert.Equal(t, "untouched", string(got))
-			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")
-}
-
-// The log.md entry for a failed note is appended through the brain root: with
-// a real raw/failed (so the archive copy succeeds and the log is reached), a
-// symlinked log.md is not written through.
-func TestProcessDirDoesNotAppendTheLogThroughASymlink(t *testing.T) {
-	brainDir := setupBrainDir(t)
-	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(filepath.Join("wiki", "concepts", "v.md"), filepath.Join(brainDir, "log.md")))
-	_ = processDir(context.Background(), Config{BrainDir: brainDir, Interval: time.Hour, Pipeline: failingPipeline()}, "2026-10-05")
-	_, err := os.Stat(filepath.Join(brainDir, "raw", "failed", "n.md"))
-	require.NoError(t, err, "positive control: the archive copy was written, so the log append was reached")
-	got, _ := os.ReadFile(victim)
-	assert.Equal(t, "untouched", string(got), "the log was appended through a symlink")
-}
-
-// A marker path holding anything (here a dangling symlink) counts as a
-// marker: the note is skipped and nothing is created at the link's target.
-// (os.Stat followed the link, saw nothing, and processed the note again.)
-func TestProcessDirTreatsAnyEntryAtTheMarkerPathAsAMarker(t *testing.T) {
-	for _, kind := range []string{"processed", "failed"} {
-		t.Run(kind, func(t *testing.T) {
-			brainDir := setupBrainDir(t)
-			outside := filepath.Join(t.TempDir(), "created")
-			require.NoError(t, os.WriteFile(filepath.Join(brainDir, "raw", "n.md"), []byte("note"), 0o644))
-			require.NoError(t, os.Symlink(outside, filepath.Join(brainDir, "raw", "n.md."+kind)))
-			calls := 0
-			cfg := Config{BrainDir: brainDir, Interval: time.Hour, Pipeline: pipeline.Config{
-				Complete: func(context.Context, string, string) (string, error) { calls++; return "[]", nil }, Schema: "# Schema"}}
-			_ = processDir(context.Background(), cfg, "2026-10-05")
-			assert.Zero(t, calls, "the note was processed despite an entry at its marker path")
-			_, err := os.Lstat(outside)
-			assert.True(t, os.IsNotExist(err), "a file was created at the marker link's target")
-		})
-	}
-}
-
-// The marker write itself is reachable while pipeline.Run is in flight
-// (in production, an LLM call): a link planted at the marker path then is
-// refused, and the note is remembered, so removing the link (as
-// symlinkguard does) does not make the watcher call the model again.
-func TestProcessDirRefusesAMarkerLinkPlantedDuringTheRunAndDoesNotRetry(t *testing.T) {
-	for _, kind := range []string{"processed", "failed"} {
-		for _, target := range []string{"outside", "in-brain"} {
-			t.Run(kind+"/"+target, func(t *testing.T) {
-				brainDir := setupBrainDir(t)
-				raw := filepath.Join(brainDir, "raw")
-				marker := filepath.Join(raw, "n.md."+kind)
-				require.NoError(t, os.WriteFile(filepath.Join(raw, "n.md"), []byte("note"), 0o644))
-				// The in-brain target is relative, so os.Root itself would
-				// follow it; only the regular-file check refuses it.
-				victim := filepath.Join(raw, "victim")
-				link := filepath.Join(t.TempDir(), "created")
-				if target == "in-brain" {
-					require.NoError(t, os.WriteFile(victim, []byte("untouched"), 0o644))
-					link = "victim"
-				}
-				ok := okPipeline().Complete
-				calls := 0
-				cfg := Config{BrainDir: brainDir, Interval: time.Hour, Pipeline: pipeline.Config{Schema: "# Schema",
-					Complete: func(ctx context.Context, sys, user string) (string, error) {
-						calls++
-						require.NoError(t, os.Symlink(link, marker))
-						if kind == "failed" {
-							return "", errors.New("model down")
-						}
-						return ok(ctx, sys, user)
-					}}}
-				for i := 0; i < 3; i++ {
-					errs := processDir(context.Background(), cfg, "2026-10-05")
-					if i == 0 {
-						require.NotEmpty(t, errs, "the planted link was not refused")
-					}
-					_ = os.Remove(marker)
-				}
-				assert.Equal(t, 1, calls, "the note was retried after its marker write was refused")
-				if target == "in-brain" {
-					got, err := os.ReadFile(victim)
-					require.NoError(t, err)
-					assert.Equal(t, "untouched", string(got), "the marker was written through the link")
-				} else {
-					_, err := os.Lstat(link)
-					assert.True(t, os.IsNotExist(err), "the marker was written through the link")
-				}
-			})
-		}
-	}
-}
-
-// A refused archive copy must not retry every interval: the note is
-// remembered and skipped until it changes (a symlinked raw/failed cost one
-// LLM call per round before).
-func TestProcessDirDoesNotRetryANoteWhoseArchiveCopyIsRefused(t *testing.T) {
-	brainDir := setupBrainDir(t)
-	require.NoError(t, os.WriteFile(filepath.Join(brainDir, "raw", "n.md"), []byte("note"), 0o644))
-	require.NoError(t, os.Symlink(t.TempDir(), filepath.Join(brainDir, "raw", "failed")))
-	calls := 0
-	cfg := Config{BrainDir: brainDir, Interval: time.Hour, Pipeline: pipeline.Config{
-		Complete: func(context.Context, string, string) (string, error) { calls++; return "", errors.New("model down") }, Schema: "# Schema"}}
-	for i := 0; i < 3; i++ {
-		_ = processDir(context.Background(), cfg, "2026-10-05")
-	}
-	assert.Equal(t, 1, calls, "the refused note was retried every round")
-
-	// Once the note changes it is tried again.
-	require.NoError(t, os.WriteFile(filepath.Join(brainDir, "raw", "n.md"), []byte("note, edited"), 0o644))
-	future := time.Now().Add(2 * time.Second)
-	require.NoError(t, os.Chtimes(filepath.Join(brainDir, "raw", "n.md"), future, future))
-	_ = processDir(context.Background(), cfg, "2026-10-05")
-	assert.Equal(t, 2, calls, "positive control: a changed note is tried again")
-}
-
-// A note whose name has a backslash is legal on Linux and must be processed
-// (cleanRel refused it, so it was never archived or marked).
-func TestProcessDirProcessesANoteWithABackslashInItsName(t *testing.T) {
-	brainDir := setupBrainDir(t)
-	require.NoError(t, os.WriteFile(filepath.Join(brainDir, "raw", "a\\b.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", "a\\b.md.processed"))
-	assert.NoError(t, err)
-}