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

@@ -179,9 +179,12 @@ func alertingWarnings(getenv func(string) string) []string {
 	return out
 }
 
-func buildNotifier() audit.Notifier {
+// buildNotifier returns the ntfy notifier for one alert source, titled so
-	if n := audit.NewNtfyNotifier(os.Getenv("BRAIN_NTFY_URL"), os.Getenv("BRAIN_NTFY_TOKEN")); n != nil {
+// the source is recognisable (hyperguild#163), or nil when ntfy is not
-		return n
+// 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
 }
@@ -203,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()))
@@ -366,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
@@ -546,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/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")
 
@@ -270,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

@@ -529,3 +529,49 @@ func TestCreateRegularCreatesOnlyNewFilesThroughRealDirectories(t *testing.T) {
 	got, _ = os.ReadFile(filepath.Join(dir, "wiki", "new", "facts", "n.md"))
 	assert.Equal(t, "one", string(got))
 }
+
+// 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() }()
+
+	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/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.
+// hostPath — during a RollingUpdate two ingestion pods do. The lock file is
-func flockFile(abs string) (func(), error) {
+// opened and removed through the brain root, never through a symlink
-	f, err := os.OpenFile(abs+".lock", os.O_CREATE|os.O_RDWR, 0o644)
+// (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)
 	}
-	if err := syscall.Flock(int(f.Fd()), syscall.LOCK_EX); err != nil {
+	for attempt := 0; attempt < 1000; attempt++ {
-		_ = f.Close()
+		f, err := bfs.OpenLock(lockRel)
-		return nil, fmt.Errorf("notes: flock %s: %w", filepath.Base(abs), err)
+		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()
+			_ = bfs.Close()
+			return nil, fmt.Errorf("notes: flock %s: %w", lockRel, err)
+		}
+		if !bfs.LockIsCurrent(lockRel, f) {
+			_ = syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
+			_ = f.Close()
+			continue
+		}
+		return func() {
+			_ = bfs.Remove(lockRel)
+			_ = syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
+			_ = f.Close()
+			_ = bfs.Close()
+		}, nil
 	}
-	return func() {
+	_ = bfs.Close()
-		_ = syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
+	return nil, fmt.Errorf("notes: lock %s: kept changing while locking", lockRel)
-		_ = f.Close()
-		_ = os.Remove(abs + ".lock")
-	}, nil
 }
 
 // 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/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)
+	// Synchronise on the summary being delivered (hyperguild#193: a fixed
-	time.Sleep(100 * time.Millisecond)
+	// sleep flaked under load); once it is, the queue has been flushed.
-	assert.LessOrEqual(t, n.count(), maxPending+1, "queued alerts plus at most one suppression summary")
+	require.Eventually(t, func() bool {
-	n.mu.Lock()
+		n.mu.Lock()
-	defer n.mu.Unlock()
+		defer n.mu.Unlock()
-	found := false
+		for _, m := range n.msgs {
-	for _, m := range n.msgs {
+			if strings.Contains(m, "suppressed") {
-		if strings.Contains(m, "suppressed") {
+				return true
-			found = true
+			}
 		}
-	}
+		return false
-	assert.True(t, found, "suppressed alerts are counted in a summary")
+	}, 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"} {
+	// Each removal delivered exactly once, in any order: the outage ends
-		assert.Contains(t, n.msgs[i], strconv.Quote(name))
+	// 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") {
+			var k int
-				return true
+			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
+				}
+			}
+			if i := strings.Index(m, "): "); i >= 0 && strings.Contains(m, "suppressed") {
+				if _, err := fmt.Sscanf(m[i+3:], "%d", &k); err == nil {
+					counted += k
+				}
 			}
 		}
-		return false
+		return delivered, counted
-	}, 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)
-		}
 	}
-	assert.Equal(t, plants, delivered+counted, "delivered %d + counted %d must equal %d removals", delivered, counted, plants)
+	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