fix(brain_edit): snapshot, rollback and lock file go through the brain root (#192)

brain_edit did its own I/O by path around notes.Edit:
- the pre-edit snapshot used os.ReadFile, which hung on a FIFO note held
  open by a writer;
- the rollback (when the provenance stamp fails) used os.WriteFile;
- the edit lock "<note>.lock" was opened with O_CREATE by path, so a
  planted dangling .lock symlink made a successful edit create a file at
  the link's target, in the brain or outside it.

Snapshot is brainfs ReadRegular, rollback WriteRegular, and the lock is
opened and removed through new brainfs OpenLock/RemoveLock: clean path,
real parent directories, an existing lock must be regular, and the opened
handle must be the file at the path (SameFile).

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

ingestion/cmd/server/jwt_validator_test.go

@@ -12,6 +12,8 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/metrics"
 )
 
 // fakeIssuer answers OIDC discovery with 502 for the first fail requests, as
@@ -73,8 +75,37 @@ func TestBuildMuxAnswers503ToAJWTWhileTheIssuerIsUnresolved(t *testing.T) {
 	srv, _ := fakeIssuer(t, 1000)
 	v, err := buildJWTValidator(context.Background(), slog.New(slog.DiscardHandler), srv.URL, "brain")
 	require.NoError(t, err)
-	mux, err := buildMux(restAuth{token: routesTok, validator: v, realm: "brain"}, testHandler(t), nil)
+	mux, err := buildMux(restAuth{token: routesTok, validator: v, realm: "brain"}, testHandler(t),
+		okHandler("mcp"), metrics.New(), nil)
 	require.NoError(t, err)
 	code, _ := do(t, mux, "GET", "/pending", "Bearer aaa.bbb.ccc")
 	assert.Equal(t, http.StatusServiceUnavailable, code)
 }
+
+// PR #183 review: /mcp shares REST's bearer, but only the static token was
+// asserted on it. With the issuer unresolved, a JWT on /mcp answers 503 too,
+// so /mcp's middleware was built with the JWT validator.
+func TestBuildMuxAnswers503ToAJWTOnMCPWhileTheIssuerIsUnresolved(t *testing.T) {
+	srv, _ := fakeIssuer(t, 1000)
+	v, err := buildJWTValidator(context.Background(), slog.New(slog.DiscardHandler), srv.URL, "brain")
+	require.NoError(t, err)
+	mux, err := buildMux(restAuth{token: routesTok, validator: v, realm: "brain"}, testHandler(t),
+		okHandler("mcp"), metrics.New(), nil)
+	require.NoError(t, err)
+	code, _ := do(t, mux, "POST", "/mcp", "Bearer aaa.bbb.ccc")
+	assert.Equal(t, http.StatusServiceUnavailable, code)
+}
+
+// PR #183 review: a 401 on /mcp names the protected-resource metadata in
+// WWW-Authenticate (what the claude.ai OAuth connector discovers from), so
+// /mcp's middleware was built with resourceMetadataURL.
+func TestBuildMuxMCP401CarriesResourceMetadataInWWWAuthenticate(t *testing.T) {
+	const rm = "https://brain.example/.well-known/oauth-protected-resource"
+	mux, err := buildMux(restAuth{token: routesTok, realm: "brain", resourceMetadataURL: rm}, testHandler(t),
+		okHandler("mcp"), metrics.New(), nil)
+	require.NoError(t, err)
+	rec := httptest.NewRecorder()
+	mux.ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/mcp", nil))
+	require.Equal(t, http.StatusUnauthorized, rec.Code)
+	assert.Contains(t, rec.Header().Get("WWW-Authenticate"), `resource_metadata="`+rm+`"`)
+}

ingestion/cmd/server/main.go

@@ -516,8 +516,6 @@ func main() {
 		}
 	}
 
-	public["/mcp"] = chassisauth.BearerMiddleware(mcpToken, jwtValidator, "brain", resourceMetadataURL, mcpSrv)
-
 	// POST /capture (#53/#54): the uniform capture REST door. Needs a ticket
 	// tracker to file action items, so it only mounts when Gitea is
 	// configured. It reuses the MCP server's graph-wired brain store (one
@@ -541,7 +539,7 @@ func main() {
 		public["POST /capture"] = captureH
 		// Same use-case behind the MCP `capture` tool (#55 relay) so MCP-native
 		// harnesses (claude.ai, Crush, Pi, LLM Council) reach capture through
-		// the existing /mcp OAuth connector. mcpSrv is already wrapped above;
+		// the existing /mcp OAuth connector. buildMux wraps this same mcpSrv;
 		// WithCapture mutates the same instance, so the tool appears live.
 		mcpSrv.WithCapture(captureSvc, jwtValidator, mcpToken, "local-cli", resolver)
 		// hyperguild#97: a governance-file rewrite gets the same trail a
@@ -583,19 +581,18 @@ func main() {
 		os.Exit(1)
 	}
 
-	// /metrics — unauthenticated Prometheus endpoint. kube-prometheus-stack
-	// scrapes it via the ServiceMonitor in k3s/apps/supervisor/. The metrics
-	// middleware below wraps every other registered handler so it observes
-	// real request latency. /metrics itself is excluded from its own
-	// observation by registering it on the outer mux (post-wrap).
-	reg := metrics.New()
-	public["GET /metrics"] = http.HandlerFunc(reg.Handler())
-
-	// The whole router, built in one place so the test of buildMux is a test
-	// of production wiring (PR #152 review). The REST API's credential is the
-	// same as /mcp's.
-	mux, err := buildMux(restAuth{token: mcpToken, validator: jwtValidator, realm: "brain",
-		resourceMetadataURL: resourceMetadataURL}, h, public)
+	// /metrics — unauthenticated Prometheus endpoint, scraped via the
+	// ServiceMonitor in k3s/apps/supervisor/. buildMux registers it and wraps
+	// the whole router in the registry's middleware.
+	//
+	// The whole router, /mcp's bearer included, is built in buildMux so its
+	// tests are tests of production wiring (PR #152 review, hyperguild#154).
+	// The REST API's credential is the same as /mcp's. Untested here: the
+	// restAuth fields and the public map this call passes in (e.g. a nil
+	// validator would drop JWT auth on /mcp and REST and the suite stays
+	// green), and ListenAndServe serving the result unchanged (hyperguild#182).
+	handler, err := buildMux(restAuth{token: mcpToken, validator: jwtValidator, realm: "brain",
+		resourceMetadataURL: resourceMetadataURL}, h, mcpSrv, metrics.New(), public)
 	if err != nil {
 		logger.Error("build router", "err", err)
 		os.Exit(1)
@@ -616,7 +613,7 @@ func main() {
 		"watch_interval", watchIntervalLog,
 		"mcp_enabled", true,
 	)
-	if err := http.ListenAndServe(addr, reg.Middleware(mux)); err != nil {
+	if err := http.ListenAndServe(addr, handler); err != nil {
 		logger.Error("server stopped", "err", err)
 		os.Exit(1)
 	}

ingestion/cmd/server/routes.go

@@ -8,22 +8,22 @@ import (
 	chassisauth "git.d-ma.be/mathias/mcp-chassis/auth"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/metrics"
 )
 
-// publicRoutes is the complete set of patterns allowed on the outer mux,
-// outside the REST API's auth (hyperguild#149). Each authenticates itself or is
-// meant to be open: /mcp (bearer/JWT), /capture (bearer/JWT), the webhook
-// (HMAC), /oauth/token (client secret), OAuth metadata and /metrics (open).
-// A REST pattern added here would beat the authenticated catch-all by
-// specificity and ship open, which is why buildMux refuses anything else.
+// publicRoutes is the complete set of patterns a caller may register on the
+// outer mux, outside the REST API's auth (hyperguild#149). Each authenticates
+// itself or is meant to be open: /capture (bearer/JWT), the webhook (HMAC),
+// /oauth/token (client secret) and OAuth metadata (open). /mcp and /metrics
+// are not here: buildMux builds them itself (hyperguild#154). A REST pattern
+// added here would beat the authenticated catch-all by specificity and ship
+// open, which is why buildMux refuses anything else.
 var publicRoutes = map[string]bool{
-	"/mcp":                      true,
 	"POST /capture":             true,
 	"POST /webhooks/brain-sync": true,
 	"GET /.well-known/oauth-protected-resource":   true,
 	"GET /.well-known/oauth-authorization-server": true,
 	"POST /oauth/token":                           true,
-	"GET /metrics":                                true,
 }
 
 // restAuth is the credential the REST API checks: the same as /mcp's.
@@ -34,16 +34,25 @@ type restAuth struct {
 	resourceMetadataURL string
 }
 
-// buildMux is the server's whole router. The REST API is mounted at "/"
-// behind bearer auth that buildMux constructs itself, so a caller cannot pass
-// a no-op; public handlers are registered as given, and only for patterns on
-// the publicRoutes allowlist. It returns an http.Handler, not the
-// *ServeMux, so nothing can register a route on the result afterwards and
-// bypass the allowlist.
-func buildMux(auth restAuth, h *api.Handler, public map[string]http.Handler) (http.Handler, error) {
+// buildMux builds the handler main passes to ListenAndServe unchanged. The
+// REST API is mounted at "/" and /mcp is registered, both behind bearer auth
+// that buildMux constructs itself from auth (one credential), so a caller
+// cannot pass a no-op. GET /metrics serves reg, and the whole router is
+// wrapped in reg's middleware. Other public handlers are registered as given,
+// and only for patterns on the publicRoutes allowlist. It returns an
+// http.Handler, not the *ServeMux, so nothing can register a route on the
+// result. What stays untested is main's call site: the restAuth fields and
+// the public map main passes in, and ListenAndServe serving this handler
+// unchanged (hyperguild#182). The tests build their own arguments.
+func buildMux(
+	auth restAuth, h *api.Handler, mcpHandler http.Handler, reg *metrics.Registry, public map[string]http.Handler,
+) (http.Handler, error) {
 	if auth.token == "" {
 		return nil, errors.New("buildMux: REST auth needs a token")
 	}
+	if mcpHandler == nil || reg == nil {
+		return nil, errors.New("buildMux: needs the MCP handler and the metrics registry")
+	}
 	mux := http.NewServeMux()
 	for pattern, handler := range public {
 		if !publicRoutes[pattern] {
@@ -51,10 +60,15 @@ func buildMux(auth restAuth, h *api.Handler, public map[string]http.Handler) (ht
 		}
 		mux.Handle(pattern, handler)
 	}
-	mountREST(mux, h, func(next http.Handler) http.Handler {
+	bearer := func(next http.Handler) http.Handler {
 		return chassisauth.BearerMiddleware(auth.token, auth.validator, auth.realm, auth.resourceMetadataURL, next)
-	})
-	return mux, nil
+	}
+	mux.Handle("/mcp", bearer(mcpHandler))
+	// /metrics is registered on the mux and so observed by its own
+	// middleware, like any route.
+	mux.Handle("GET /metrics", reg.Handler())
+	mountREST(mux, h, bearer)
+	return reg.Middleware(mux), nil
 }
 
 // mountREST registers the REST API on its own mux and mounts it at "/" behind

ingestion/cmd/server/routes_observability_test.go

@@ -9,8 +9,6 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-
-	"github.com/mathiasbq/hyperguild/ingestion/internal/metrics"
 )
 
 // wrongTokSentinel is a presented credential distinctive enough that any
@@ -53,8 +51,8 @@ func TestBuildMuxAcceptedLogLineOmitsTheBareStaticToken(t *testing.T) {
 // An authenticated REST request is labelled with the REST mux's pattern:
 // the inner mux sets it on the same *http.Request the outer middleware reads.
 func TestMetricsLabelAnAuthenticatedRESTRequestWithItsRoutePattern(t *testing.T) {
-	reg := metrics.New()
-	code, _ := do(t, reg.Middleware(testMux(t)), "GET", "/pending", "Bearer "+routesTok)
+	mux, reg := testMuxAndRegistry(t)
+	code, _ := do(t, mux, "GET", "/pending", "Bearer "+routesTok)
 	require.Equal(t, http.StatusOK, code)
 
 	rec := httptest.NewRecorder()
@@ -67,8 +65,8 @@ func TestMetricsLabelAnAuthenticatedRESTRequestWithItsRoutePattern(t *testing.T)
 // so it was labelled path="/" and a 4xx on /query could not be told from one
 // on /write. It is now labelled with the REST pattern it was addressed to.
 func TestMetricsLabelARejectedRESTRequestWithItsRoutePattern(t *testing.T) {
-	reg := metrics.New()
-	code, _ := do(t, reg.Middleware(testMux(t)), "POST", "/query", "")
+	mux, reg := testMuxAndRegistry(t)
+	code, _ := do(t, mux, "POST", "/query", "")
 	require.Equal(t, http.StatusUnauthorized, code)
 
 	rec := httptest.NewRecorder()
@@ -79,8 +77,8 @@ func TestMetricsLabelARejectedRESTRequestWithItsRoutePattern(t *testing.T) {
 // A path no REST route matches keeps the catch-all label, so an attacker
 // probing random URLs cannot grow the series set.
 func TestMetricsLabelARejectedUnknownPathWithTheCatchAll(t *testing.T) {
-	reg := metrics.New()
-	code, _ := do(t, reg.Middleware(testMux(t)), "POST", "/no-such-route-zq", "")
+	mux, reg := testMuxAndRegistry(t)
+	code, _ := do(t, mux, "POST", "/no-such-route-zq", "")
 	require.Equal(t, http.StatusUnauthorized, code)
 
 	rec := httptest.NewRecorder()

ingestion/cmd/server/routes_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/metrics"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 )
 
@@ -21,20 +22,29 @@ func okHandler(body string) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { _, _ = w.Write([]byte(body)) })
 }
 
-// testMux builds the router exactly as main does: buildMux with the full
-// public set main registers (stub handlers) and real bearer config.
-// hyperguild#149: the REST API is authenticated as a whole; the PR #152
-// review showed a test of a COPY of the router let main.go regress unseen.
+// testMux builds the router through buildMux, the function main calls, with
+// every allowlisted public pattern (stub handlers), a stub MCP server and a
+// static token only: no JWT validator and no resourceMetadataURL (the tests
+// in jwt_validator_test.go pass those). It does not use main's own restAuth
+// or public map (hyperguild#182). hyperguild#149: the REST API is
+// authenticated as a whole; the PR #152 review showed a test of a COPY of
+// the router let main.go regress unseen.
 func testMux(t *testing.T) http.Handler {
 	t.Helper()
-	h := testHandler(t)
+	mux, _ := testMuxAndRegistry(t)
+	return mux
+}
+
+func testMuxAndRegistry(t *testing.T) (http.Handler, *metrics.Registry) {
+	t.Helper()
 	public := map[string]http.Handler{}
 	for p := range publicRoutes {
 		public[p] = okHandler("public " + p)
 	}
-	mux, err := buildMux(restAuth{token: routesTok, realm: "brain"}, h, public)
+	reg := metrics.New()
+	mux, err := buildMux(restAuth{token: routesTok, realm: "brain"}, testHandler(t), okHandler("mcp"), reg, public)
 	require.NoError(t, err)
-	return mux
+	return mux, reg
 }
 
 func testHandler(t *testing.T) *api.Handler {
@@ -79,8 +89,9 @@ func TestBuildMuxAuthenticatesAnUnregisteredPath(t *testing.T) {
 }
 
 // buildMux registers public handlers as given, without adding auth: each
-// public route owns its own (bearer on /mcp, HMAC on the webhook, client
-// secret on /oauth/token) or is meant to be open (/metrics, OAuth metadata).
+// public route owns its own (bearer/JWT on /capture, HMAC on the webhook,
+// client secret on /oauth/token) or is meant to be open (OAuth metadata).
+// /mcp and /metrics are not public routes: buildMux builds them itself.
 func TestBuildMuxDoesNotWrapPublicRoutes(t *testing.T) {
 	r := testMux(t)
 	for p := range publicRoutes {
@@ -98,14 +109,53 @@ func TestBuildMuxDoesNotWrapPublicRoutes(t *testing.T) {
 // over the authenticated catch-all (more specific pattern), so it is refused.
 func TestBuildMuxRefusesAPublicPatternOffTheAllowlist(t *testing.T) {
 	h := api.NewHandler(t.TempDir(), slog.New(slog.NewTextHandler(os.Stderr, nil)), pipeline.Config{})
-	for _, p := range []string{"POST /query", "GET /pending", "/", "POST /metrics"} {
-		_, err := buildMux(restAuth{token: routesTok, realm: "brain"}, h, map[string]http.Handler{p: okHandler("x")})
+	// "/mcp" and "GET /metrics" are built by buildMux itself (hyperguild#154):
+	// passing either as public would register them unauthenticated or twice.
+	for _, p := range []string{"POST /query", "GET /pending", "/", "POST /metrics", "/mcp", "GET /metrics"} {
+		_, err := buildMux(restAuth{token: routesTok, realm: "brain"}, h, okHandler("mcp"), metrics.New(),
+			map[string]http.Handler{p: okHandler("x")})
 		assert.Error(t, err, "public pattern %q must be refused", p)
 	}
 }
 
 func TestBuildMuxRefusesAnEmptyToken(t *testing.T) {
 	h := api.NewHandler(t.TempDir(), slog.New(slog.NewTextHandler(os.Stderr, nil)), pipeline.Config{})
-	_, err := buildMux(restAuth{token: "", realm: "brain"}, h, nil)
+	_, err := buildMux(restAuth{token: "", realm: "brain"}, h, okHandler("mcp"), metrics.New(), nil)
 	assert.Error(t, err)
 }
+
+// hyperguild#154: /mcp's bearer was built in main.go, untested; the buildMux
+// tests used stubs. buildMux now wraps the MCP handler itself, with the same
+// credential as the REST API.
+func TestBuildMuxRefusesMCPWithoutAValidToken(t *testing.T) {
+	r := testMux(t)
+	for _, authz := range []string{"", "Bearer wrong"} {
+		code, body := do(t, r, "POST", "/mcp", authz)
+		assert.Equal(t, http.StatusUnauthorized, code, "authz %q", authz)
+		assert.NotEqual(t, "mcp", body)
+	}
+	code, body := do(t, r, "POST", "/mcp", "Bearer "+routesTok)
+	assert.Equal(t, http.StatusOK, code)
+	assert.Equal(t, "mcp", body)
+}
+
+func TestBuildMuxRefusesANilMCPHandlerOrRegistry(t *testing.T) {
+	auth := restAuth{token: routesTok, realm: "brain"}
+	_, err := buildMux(auth, testHandler(t), nil, metrics.New(), nil)
+	assert.Error(t, err)
+	_, err = buildMux(auth, testHandler(t), okHandler("mcp"), nil, nil)
+	assert.Error(t, err)
+}
+
+// hyperguild#154: main wrapped buildMux's result in the metrics middleware
+// before ListenAndServe, untested. buildMux now returns the handler main
+// serves as-is, metrics included: a request through it is observed and
+// exposed on its own GET /metrics.
+func TestBuildMuxObservesRequestsAndServesMetrics(t *testing.T) {
+	r := testMux(t)
+	code, _ := do(t, r, "GET", "/pending", "Bearer "+routesTok)
+	require.Equal(t, http.StatusOK, code)
+	code, body := do(t, r, "GET", "/metrics", "")
+	require.Equal(t, http.StatusOK, code)
+	assert.Contains(t, body, `path="GET /pending"`)
+}

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/go.mod

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

ingestion/internal/api/readnote_root_test.go

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

ingestion/internal/api/update.go

@@ -3,15 +3,18 @@ package api
 import (
 	"crypto/sha256"
 	"encoding/hex"
+	"errors"
 	"fmt"
-	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
 	"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/notes"
 )
 
 // ContentHash returns the lowercase hex sha256 of b. It is the note's
@@ -91,14 +94,23 @@ func UpdateNote(brainDir string, opts UpdateNoteOptions) (relPath, contentHash,
 		rel = filepath.ToSlash(rel)
 	}
 
-	rel, abs, err := resolveWithin(brainDir, rel)
+	// The path is caller-supplied (brain_update): resolve it as brain_edit
+	// does, knowledge/ and wiki/ notes only, and read and rewrite it through
+	// the brain root, never through a symlink (hyperguild#169).
+	t, err := notes.Resolve(brainDir, rel, notes.ScopeNotes)
 	if err != nil {
 		return "", "", "", err
 	}
-
-	prior, err := os.ReadFile(abs)
+	rel = t.Rel
+	bfs, err := brainfs.Open(brainDir)
 	if err != nil {
-		if os.IsNotExist(err) {
+		return "", "", "", fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+
+	prior, err := bfs.ReadRegular(rel)
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
 			return "", "", "", fmt.Errorf("note %q does not exist: use brain_write to create", rel)
 		}
 		return "", "", "", fmt.Errorf("read target: %w", err)
@@ -164,7 +176,7 @@ func UpdateNote(brainDir string, opts UpdateNoteOptions) (relPath, contentHash,
 		return "", "", "", err
 	}
 	out := []byte(stamped)
-	if err := os.WriteFile(abs, out, 0o644); err != nil {
+	if err := bfs.WriteRegular(rel, out); err != nil {
 		return "", "", "", fmt.Errorf("write: %w", err)
 	}
 	return rel, ContentHash(out), priorHash, nil

ingestion/internal/api/update_redirect_test.go

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

ingestion/internal/api/update_scope_test.go

@@ -0,0 +1,112 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// brain_update passed the caller's path through resolveWithin, a lexical
+// containment check only: any file in the brain could be superseded
+// (classification.yaml, raw/, sessions/), and a final symlink was written
+// through. It now resolves like brain_edit: knowledge/ and wiki/ notes only,
+// read and rewritten through the brain root.
+func TestUpdateNoteRefusesPathsOutsideKnowledgeAndWikiNotes(t *testing.T) {
+	brain := t.TempDir()
+	files := map[string]string{
+		"classification.yaml": "levels: {}\n",
+		"raw/r.md":            "raw\n",
+		"sessions/s.jsonl":    "{}\n",
+		"wiki/w/facts/ok.md":  "---\ntitle: ok\n---\nold\n",
+		"knowledge/k.md":      "---\ntitle: k\n---\nold\n",
+		"wiki/w/facts/x.txt":  "txt\n",
+	}
+	for rel, body := range files {
+		p := filepath.Join(brain, filepath.FromSlash(rel))
+		require.NoError(t, os.MkdirAll(filepath.Dir(p), 0o755))
+		require.NoError(t, os.WriteFile(p, []byte(body), 0o644))
+	}
+	for _, rel := range []string{"classification.yaml", "raw/r.md", "sessions/s.jsonl", "wiki/w/facts/x.txt", "wiki/w/../../raw/r.md"} {
+		_, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: rel, Content: "replaced"})
+		assert.Error(t, err, rel)
+	}
+	for rel, body := range files {
+		if rel == "wiki/w/facts/ok.md" || rel == "knowledge/k.md" {
+			continue
+		}
+		got, err := os.ReadFile(filepath.Join(brain, filepath.FromSlash(rel)))
+		require.NoError(t, err)
+		assert.Equal(t, body, string(got), rel)
+	}
+	for _, rel := range []string{"wiki/w/facts/ok.md", "knowledge/k.md"} {
+		_, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: rel, Content: "new body"})
+		require.NoError(t, err, "positive control: %s", rel)
+		got, _ := os.ReadFile(filepath.Join(brain, filepath.FromSlash(rel)))
+		assert.Contains(t, string(got), "new body")
+	}
+}
+
+func TestUpdateNoteDoesNotWriteThroughASymlinkedNote(t *testing.T) {
+	brain := t.TempDir()
+	facts := filepath.Join(brain, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	victim := filepath.Join(brain, "raw", "victim.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "victim.md"), filepath.Join(facts, "l.md")))
+	_, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: "wiki/w/facts/l.md", Content: "replaced"})
+	assert.Error(t, err)
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched\n", string(got))
+}
+
+// The note is swapped between a regular file and an in-brain symlink to a
+// raw/ file while UpdateNote runs: the read and the write each refuse a
+// symlink, so the raw/ file is never rewritten.
+func TestUpdateNoteNeverRewritesASymlinkSwappedInForTheNote(t *testing.T) {
+	brain := t.TempDir()
+	facts := filepath.Join(brain, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	victim := filepath.Join(brain, "raw", "victim.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	note := filepath.Join(facts, "n.md")
+	body := "---\ntitle: n\n---\nold\n"
+	require.NoError(t, os.WriteFile(note, []byte(body), 0o644))
+
+	var stop atomic.Bool
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		tmp := note + ".swap"
+		for i := 0; !stop.Load(); i++ {
+			_ = os.Remove(tmp)
+			if i%2 == 0 {
+				_ = os.WriteFile(tmp, []byte(body), 0o644)
+			} else {
+				_ = os.Symlink(filepath.Join("..", "..", "..", "raw", "victim.md"), tmp)
+			}
+			_ = os.Rename(tmp, note)
+		}
+	}()
+	ok := 0
+	for deadline := time.Now().Add(1500 * time.Millisecond); time.Now().Before(deadline); {
+		if _, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: "wiki/w/facts/n.md", Content: "new"}); err == nil {
+			ok++
+		}
+	}
+	stop.Store(true)
+	wg.Wait()
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched\n", string(got))
+	assert.Positive(t, ok, "positive control: some updates reach the regular note")
+}

ingestion/internal/api/write_keeps_learning_test.go

@@ -0,0 +1,34 @@
+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#178: an unreadable directory under wiki/ made the link check
+// fail and brain_write refuse the note, losing the learning. The note is now
+// written with its links as given.
+func TestWriteNoteKeepsTheLearningWhenTheLinkCheckCannotIndex(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root ignores directory permissions")
+	}
+	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", "real.md"), []byte("x"), 0o644))
+	locked := filepath.Join(brain, "wiki", "other", "locked")
+	require.NoError(t, os.MkdirAll(locked, 0o755))
+	require.NoError(t, os.Chmod(locked, 0o000))
+	t.Cleanup(func() { _ = os.Chmod(locked, 0o755) })
+
+	rel, err := api.WriteNote(brain, api.WriteNoteOptions{Wing: "w", Hall: "facts", Filename: "n", Content: "learning [[real]] and [[gone]]"})
+	require.NoError(t, err)
+	got, err := os.ReadFile(filepath.Join(brain, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "[[gone]]", "links kept as given when the index is partial")
+}

ingestion/internal/brain/detect_root_test.go

@@ -0,0 +1,125 @@
+package brain_test
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest"
+)
+
+// hyperguild#174 / #157 slice 5b: DetectTunnels walked wiki/ and opened
+// every note with a blocking os.Open, so a FIFO named *.md anywhere under
+// wiki/ hung every brain_write and brain_update (wikiUpkeep -> AutoTunnel),
+// and a symlinked note's title became a tunnel candidate.
+func TestDetectTunnelsReturnsPromptlyWithAFIFOUnderWikiWithAndWithoutAWriter(t *testing.T) {
+	for _, withWriter := range []bool{false, true} {
+		t.Run(fmt.Sprintf("writer=%v", withWriter), func(t *testing.T) {
+			b := t.TempDir()
+			facts := filepath.Join(b, "wiki", "w", "facts")
+			require.NoError(t, os.MkdirAll(facts, 0o755))
+			require.NoError(t, os.WriteFile(filepath.Join(facts, "ok.md"), []byte("---\ntitle: Zqinside Phrase\n---\n"), 0o644))
+			fifo := filepath.Join(facts, "f.md")
+			require.NoError(t, syscall.Mkfifo(fifo, 0o644))
+			if withWriter {
+				// A writer held open: a reader that opens the FIFO gets no
+				// EOF and parks, unless the FIFO is never opened.
+				w, err := os.OpenFile(fifo, os.O_RDWR, 0)
+				require.NoError(t, err)
+				t.Cleanup(func() { _ = w.Close() })
+			}
+			done := make(chan []brain.TunnelCandidate, 1)
+			go func() {
+				cs, _ := brain.DetectTunnels(b, "text mentioning zqinside phrase here")
+				done <- cs
+			}()
+			select {
+			case cs := <-done:
+				assert.Contains(t, fmt.Sprintf("%+v", cs), "Zqinside Phrase", "positive control")
+			case <-time.After(3 * time.Second):
+				if r, err := os.OpenFile(fifo, os.O_WRONLY|syscall.O_NONBLOCK, 0); err == nil {
+					_ = r.Close()
+				}
+				t.Fatal("DetectTunnels blocked on a FIFO")
+			}
+		})
+	}
+}
+
+func TestDetectTunnelsRefusesSymlinkedNotesAndSurvivesSwapRaces(t *testing.T) {
+	b := t.TempDir()
+	facts := filepath.Join(b, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	// The static note's title differs from the raced note's, so the
+	// harness's "inside was read" floor can only be met by reading r.md.
+	require.NoError(t, os.WriteFile(filepath.Join(facts, "ok.md"), []byte("---\ntitle: Zqstatic Words\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(facts, "out.md")))
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(b, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "in.md")))
+	content := "zqstatic words, zqinside phrase and " + brainfstest.Sentinel
+
+	cs, err := brain.DetectTunnels(b, content)
+	require.NoError(t, err)
+	got := fmt.Sprintf("%+v", cs)
+	assert.Contains(t, got, "Zqstatic Words", "positive control")
+	assert.NotContains(t, got, brainfstest.Sentinel)
+
+	p := filepath.Join(facts, "r.md")
+	read := func() string {
+		cs, _ := brain.DetectTunnels(b, content)
+		return fmt.Sprintf("%+v", cs)
+	}
+	brainfstest.AssertNoLeak(t, p, "---\ntitle: Zqinside Phrase\n---\n", 1500*time.Millisecond, read)
+	brainfstest.AssertNoLeakFrom(t, p, "---\ntitle: Zqinside Phrase\n---\n", inBrain, 1500*time.Millisecond, read)
+}
+
+// A wiki/ that is not a real directory yields no candidates and no error:
+// AutoTunnel runs inside brain_write.
+func TestDetectTunnelsSkipsAWikiThatIsNotARealDirectory(t *testing.T) {
+	b := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "raw", "w", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(b, "raw", "w", "facts", "r.md"), []byte("---\ntitle: Zqrawonly Phrase\n---\n"), 0o644))
+	require.NoError(t, os.Symlink("raw", filepath.Join(b, "wiki")))
+	cs, err := brain.DetectTunnels(b, "zqrawonly phrase")
+	require.NoError(t, err)
+	assert.Empty(t, cs)
+}
+
+// An unreadable directory under wiki/ is a walk error and DetectTunnels
+// reports it, as filepath.WalkDir did; it is not silently dropped.
+func TestDetectTunnelsReportsAnUnreadableDirectoryUnderWiki(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root ignores directory permissions")
+	}
+	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", "ok.md"), []byte("---\ntitle: Zqinside Phrase\n---\n"), 0o644))
+	locked := filepath.Join(b, "wiki", "other", "locked")
+	require.NoError(t, os.MkdirAll(locked, 0o755))
+	require.NoError(t, os.Chmod(locked, 0o000))
+	t.Cleanup(func() { _ = os.Chmod(locked, 0o755) })
+	_, err := brain.DetectTunnels(b, "zqinside phrase")
+	assert.ErrorIs(t, err, os.ErrPermission)
+}
+
+// _index.md files are generated, not notes: their title never becomes a
+// candidate.
+func TestDetectTunnelsSkipsIndexFiles(t *testing.T) {
+	b := t.TempDir()
+	w := filepath.Join(b, "wiki", "w")
+	require.NoError(t, os.MkdirAll(filepath.Join(w, "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(w, "_index.md"), []byte("---\ntitle: Zqindex Words\n---\n"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(w, "facts", "ok.md"), []byte("---\ntitle: Zqinside Phrase\n---\n"), 0o644))
+	cs, err := brain.DetectTunnels(b, "zqindex words and zqinside phrase")
+	require.NoError(t, err)
+	got := fmt.Sprintf("%+v", cs)
+	assert.Contains(t, got, "Zqinside Phrase", "positive control")
+	assert.NotContains(t, got, "Zqindex")
+}

ingestion/internal/brain/index.go

@@ -116,23 +116,6 @@ func collectWingEntries(bfs *brainfs.Brain, wingRel string) ([]noteEntry, error)
 	return out, nil
 }
 
-// readTitleAndCreated reads YAML frontmatter for title + created_at; falls
-// back to slug and file mtime when absent.
-func readTitleAndCreated(path, slug string) (string, string) {
-	f, err := os.Open(path)
-	if err != nil {
-		return slug, ""
-	}
-	defer func() { _ = f.Close() }()
-	title, created := parseTitleAndCreated(f)
-	if created == "" {
-		if info, err := os.Stat(path); err == nil {
-			created = info.ModTime().UTC().Format("2006-01-02")
-		}
-	}
-	return titleOrSlug(title, slug), created
-}
-
 // readTitleAndCreatedIn is readTitleAndCreated through the brain root,
 // regular files only (hyperguild#157).
 func readTitleAndCreatedIn(bfs *brainfs.Brain, rel, slug string) (string, string) {

ingestion/internal/brain/linkcheck.go

@@ -47,7 +47,12 @@ var (
 func StripUnresolvedLinks(brainDir, content string) (string, []string, error) {
 	index, err := entryIndex(brainDir)
 	if err != nil {
-		return "", nil, err
+		// A partial index cannot tell an invented link from one into the
+		// part it could not read, so unwrap nothing, and do not refuse the
+		// write either: this runs before every brain_write, and a refused
+		// write is a lost learning (hyperguild#178).
+		slog.Warn("link check skipped: cannot index the brain", "err", err)
+		return content, nil, nil
 	}
 	if len(index) == 0 {
 		return content, nil, nil

ingestion/internal/brain/linkcheck_fallback_test.go

@@ -0,0 +1,41 @@
+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#178: StripUnresolvedLinks runs before every brain_write and
+// brain_update. An unreadable directory under knowledge/ or wiki/ made it
+// error, the write was refused and the learning lost. When the link index
+// cannot be built, the content is now returned unchanged (no link is
+// unwrapped, none is invented) and no error stops the write.
+func TestStripUnresolvedLinksKeepsContentWhenTheIndexCannotBeBuilt(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root ignores directory permissions")
+	}
+	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", "real.md"), []byte("x"), 0o644))
+	locked := filepath.Join(b, "wiki", "other", "locked")
+	require.NoError(t, os.MkdirAll(locked, 0o755))
+	require.NoError(t, os.Chmod(locked, 0o000))
+	t.Cleanup(func() { _ = os.Chmod(locked, 0o755) })
+
+	in := "learning [[real]] and [[gone]]"
+	out, unlinked, err := brain.StripUnresolvedLinks(b, in)
+	require.NoError(t, err)
+	assert.Equal(t, in, out, "content unchanged: no link unwrapped on a partial index")
+	assert.Empty(t, unlinked)
+
+	require.NoError(t, os.Chmod(locked, 0o755))
+	out, _, err = brain.StripUnresolvedLinks(b, in)
+	require.NoError(t, err)
+	assert.NotContains(t, out, "[[gone]]", "positive control: with a readable tree the strip runs")
+}

ingestion/internal/brain/tunnel.go

@@ -2,11 +2,16 @@ package brain
 
 import (
 	"bufio"
+	"errors"
 	"fmt"
+	"io/fs"
 	"os"
+	"path"
 	"path/filepath"
 	"strings"
 	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 )
 
 // seeAlsoHeader is the markdown heading used to group cross-wing links.
@@ -36,24 +41,29 @@ type TunnelCandidate struct {
 // A note's title is read from YAML frontmatter `title:`; failing that,
 // the filename slug (sans `.md`, hyphens → spaces) is used.
 func DetectTunnels(brainDir, content string) ([]TunnelCandidate, error) {
-	wikiDir := filepath.Join(brainDir, "wiki")
-	if _, err := os.Stat(wikiDir); os.IsNotExist(err) {
+	// Walked and read through the brain root, regular files only
+	// (hyperguild#174, #157): this runs inside every brain_write, so a FIFO
+	// must not block it and a symlinked note's title must not become a
+	// candidate.
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return nil, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	if _, err := bfs.Lstat("wiki"); errors.Is(err, fs.ErrNotExist) {
 		return nil, nil
-	} else if err != nil {
-		return nil, fmt.Errorf("stat wiki: %w", err)
 	}
 
 	lowerContent := strings.ToLower(content)
 
 	var out []TunnelCandidate
-	err := filepath.WalkDir(wikiDir, func(path string, d os.DirEntry, err error) error {
-		if err != nil {
-			return err
-		}
-		if d.IsDir() || !strings.HasSuffix(path, ".md") || d.Name() == "_index.md" {
+	var walkErr error
+	err = bfs.WalkRegular("wiki", func(rel string) error {
+		name := path.Base(rel)
+		if !strings.HasSuffix(name, ".md") || name == "_index.md" {
 			return nil
 		}
-		title, _ := readTitleAndCreated(path, strings.TrimSuffix(d.Name(), ".md"))
+		title, _ := readTitleAndCreatedIn(bfs, rel, strings.TrimSuffix(name, ".md"))
 		title = strings.TrimSpace(title)
 		if title == "" {
 			return nil
@@ -75,17 +85,25 @@ func DetectTunnels(brainDir, content string) ([]TunnelCandidate, error) {
 		if idx == -1 {
 			return nil
 		}
-		rel, err := filepath.Rel(brainDir, path)
-		if err != nil {
-			return err
-		}
 		out = append(out, TunnelCandidate{
-			TargetPath:  filepath.ToSlash(rel),
+			TargetPath:  rel,
 			MatchedTerm: title,
 			Exact:       isWholeWord(haystack, idx, len(needle)),
 		})
 		return nil
+	}, func(rel string, err error) {
+		// A wiki/ that is not a real directory yields no candidates, as
+		// filepath.WalkDir did; other walk errors still abort.
+		if rel == "wiki" && errors.Is(err, brainfs.ErrNotRegular) {
+			return
+		}
+		if walkErr == nil {
+			walkErr = fmt.Errorf("%s: %w", rel, err)
+		}
 	})
+	if err == nil {
+		err = walkErr
+	}
 	if err != nil {
 		return nil, err
 	}
@@ -197,6 +215,12 @@ func fileExists(p string) bool {
 // section headers. Rejects same-wing pairs (a tunnel is by definition
 // cross-wing) and missing notes.
 func WriteTunnel(brainDir, sourcePath, targetPath string) error {
+	if err := checkNotePath(sourcePath); err != nil {
+		return fmt.Errorf("source: %w", err)
+	}
+	if err := checkNotePath(targetPath); err != nil {
+		return fmt.Errorf("target: %w", err)
+	}
 	srcWing, err := wingOf(sourcePath)
 	if err != nil {
 		return fmt.Errorf("source: %w", err)
@@ -209,20 +233,50 @@ func WriteTunnel(brainDir, sourcePath, targetPath string) error {
 		return fmt.Errorf("tunnel must cross wings; got both in %q", srcWing)
 	}
 
-	srcFull := filepath.Join(brainDir, filepath.FromSlash(sourcePath))
-	tgtFull := filepath.Join(brainDir, filepath.FromSlash(targetPath))
-	if _, err := os.Stat(srcFull); err != nil {
+	// Both notes are read and rewritten through the brain root, regular
+	// files only: brain_tunnel passes caller-supplied paths, and the brain is
+	// a Syncthing folder that can hold symlinks.
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	srcContent, err := bfs.ReadRegular(sourcePath)
+	if err != nil {
 		return fmt.Errorf("source note: %w", err)
 	}
-	if _, err := os.Stat(tgtFull); err != nil {
+	tgtContent, err := bfs.ReadRegular(targetPath)
+	if err != nil {
 		return fmt.Errorf("target note: %w", err)
 	}
 
-	if err := appendSeeAlso(srcFull, wikilinkOf(targetPath)); err != nil {
+	if out, changed, err := withSeeAlso(srcContent, wikilinkOf(targetPath)); err != nil {
 		return fmt.Errorf("update source: %w", err)
+	} else if changed {
+		if err := bfs.WriteRegular(sourcePath, out); err != nil {
+			return fmt.Errorf("update source: %w", err)
+		}
 	}
-	if err := appendSeeAlso(tgtFull, wikilinkOf(sourcePath)); err != nil {
+	if out, changed, err := withSeeAlso(tgtContent, wikilinkOf(sourcePath)); err != nil {
 		return fmt.Errorf("update target: %w", err)
+	} else if changed {
+		if err := bfs.WriteRegular(targetPath, out); err != nil {
+			return fmt.Errorf("update target: %w", err)
+		}
+	}
+	return nil
+}
+
+// checkNotePath accepts only a clean, local wiki/<wing>/<hall>/.../<slug>.md
+// path: no "." or ".." segments, no empty segments, no leading slash.
+func checkNotePath(p string) error {
+	if p == "" || path.Clean(p) != p || !filepath.IsLocal(p) || !strings.HasSuffix(p, ".md") {
+		return fmt.Errorf("not a clean wiki note path: %q", p)
+	}
+	for _, part := range strings.Split(p, "/") {
+		if part == "" || part == "." || part == ".." {
+			return fmt.Errorf("not a clean wiki note path: %q", p)
+		}
 	}
 	return nil
 }
@@ -248,16 +302,13 @@ func wingOf(relPath string) (string, error) {
 	return parts[1], nil
 }
 
-// appendSeeAlso inserts `- [[link]]` under the file's See also section,
-// creating the section if absent. No-op when the link is already present.
-func appendSeeAlso(filePath, link string) error {
-	content, err := os.ReadFile(filePath)
-	if err != nil {
-		return err
-	}
+// withSeeAlso returns content with `- [[link]]` under its See also section,
+// creating the section if absent. changed is false when the link is already
+// present.
+func withSeeAlso(content []byte, link string) (out []byte, changed bool, err error) {
 	wikilink := "[[" + link + "]]"
 	if strings.Contains(string(content), wikilink) {
-		return nil
+		return content, false, nil
 	}
 
 	bullet := "- " + wikilink
@@ -266,8 +317,7 @@ func appendSeeAlso(filePath, link string) error {
 		// No section yet — append a fresh one. Always emit a trailing
 		// newline so subsequent appends don't merge into the previous line.
 		trimmed := strings.TrimRight(string(content), "\n")
-		out := trimmed + "\n\n" + seeAlsoHeader + "\n\n" + bullet + "\n"
-		return os.WriteFile(filePath, []byte(out), 0o644)
+		return []byte(trimmed + "\n\n" + seeAlsoHeader + "\n\n" + bullet + "\n"), true, nil
 	}
 
 	// Section exists — splice the bullet in just before the next `## `
@@ -293,12 +343,11 @@ func appendSeeAlso(filePath, link string) error {
 		b.WriteByte('\n')
 	}
 	if err := scanner.Err(); err != nil {
-		return err
+		return nil, false, err
 	}
 	if !inserted {
 		// section was the last thing in the file — just append bullet
-		out := strings.TrimRight(b.String(), "\n") + "\n" + bullet + "\n"
-		return os.WriteFile(filePath, []byte(out), 0o644)
+		return []byte(strings.TrimRight(b.String(), "\n") + "\n" + bullet + "\n"), true, nil
 	}
-	return os.WriteFile(filePath, []byte(b.String()), 0o644)
+	return []byte(b.String()), true, nil
 }

ingestion/internal/brain/tunnel_redirect_test.go

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

ingestion/internal/brain/tunnel_root_test.go

@@ -0,0 +1,141 @@
+package brain_test
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+)
+
+// brain_tunnel passes caller-supplied source and target paths to WriteTunnel,
+// which checked only "wiki/<wing>/..." and then joined them onto the brain
+// dir: ".." segments resolved outside the brain and appendSeeAlso rewrote the
+// file there.
+func TestWriteTunnelRefusesATargetThatTraversesOutOfTheBrain(t *testing.T) {
+	brain0 := t.TempDir()
+	src := filepath.Join(brain0, "wiki", "a", "facts", "s.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(src), 0o755))
+	require.NoError(t, os.WriteFile(src, []byte("---\ntitle: S\n---\nbody\n"), 0o644))
+	victim := filepath.Join(t.TempDir(), "victim.md")
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+
+	up := strings.Repeat("../", strings.Count(filepath.Clean(brain0), "/")+3)
+	target := "wiki/b/x/" + up + strings.TrimPrefix(victim, "/")
+	err := brain.WriteTunnel(brain0, "wiki/a/facts/s.md", target)
+	assert.Error(t, err)
+	got, rerr := os.ReadFile(victim)
+	require.NoError(t, rerr)
+	assert.Equal(t, "untouched\n", string(got), "a file outside the brain was modified")
+}
+
+func TestWriteTunnelRefusesUncleanOrNonWikiPaths(t *testing.T) {
+	brain0 := t.TempDir()
+	for _, p := range []string{"wiki/a/facts/s.md", "wiki/b/facts/t.md", "wiki/b/facts/t.txt", "raw/r.md"} {
+		require.NoError(t, os.MkdirAll(filepath.Dir(filepath.Join(brain0, p)), 0o755))
+		require.NoError(t, os.WriteFile(filepath.Join(brain0, p), []byte("x\n"), 0o644))
+	}
+	for _, target := range []string{
+		"wiki/b/facts/../../../raw/r.md",
+		"wiki/b/./facts/t.md",
+		"wiki/b//facts/t.md",
+		"/wiki/b/facts/t.md",
+		"wiki/b/facts/t.txt",
+		"wiki/b/facts/",
+	} {
+		assert.Error(t, brain.WriteTunnel(brain0, "wiki/a/facts/s.md", target), target)
+	}
+	for _, p := range []string{"raw/r.md", "wiki/b/facts/t.txt"} {
+		got, err := os.ReadFile(filepath.Join(brain0, p))
+		require.NoError(t, err)
+		assert.Equal(t, "x\n", string(got), p)
+	}
+	require.NoError(t, brain.WriteTunnel(brain0, "wiki/a/facts/s.md", "wiki/b/facts/t.md"), "positive control")
+	got, err := os.ReadFile(filepath.Join(brain0, "wiki", "b", "facts", "t.md"))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "[[a/facts/s]]")
+}
+
+func TestWriteTunnelDoesNotWriteThroughASymlinkedNote(t *testing.T) {
+	brain0 := t.TempDir()
+	src := filepath.Join(brain0, "wiki", "a", "facts", "s.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(src), 0o755))
+	require.NoError(t, os.WriteFile(src, []byte("x\n"), 0o644))
+	tdir := filepath.Join(brain0, "wiki", "b", "facts")
+	require.NoError(t, os.MkdirAll(tdir, 0o755))
+	victim := filepath.Join(t.TempDir(), "victim.md")
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	require.NoError(t, os.Symlink(victim, filepath.Join(tdir, "t.md")))
+	assert.Error(t, brain.WriteTunnel(brain0, "wiki/a/facts/s.md", "wiki/b/facts/t.md"))
+	got, err := os.ReadFile(victim)
+	require.NoError(t, err)
+	assert.Equal(t, "untouched\n", string(got))
+
+	// The same with a link to a file elsewhere in the brain, which os.Root
+	// would follow.
+	inVictim := filepath.Join(brain0, "raw", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(inVictim), 0o755))
+	require.NoError(t, os.WriteFile(inVictim, []byte("untouched\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "v.md"), filepath.Join(tdir, "u.md")))
+	assert.Error(t, brain.WriteTunnel(brain0, "wiki/a/facts/s.md", "wiki/b/facts/u.md"))
+	got, err = os.ReadFile(inVictim)
+	require.NoError(t, err)
+	assert.Equal(t, "untouched\n", string(got))
+	got, err = os.ReadFile(src)
+	require.NoError(t, err)
+	assert.Equal(t, "x\n", string(got), "the source is not touched when the target is refused")
+}
+
+// The target is swapped between a regular note and a symlink to an in-brain
+// file outside wiki/ while WriteTunnel runs: the read and the write each
+// refuse a symlink, so the other file is never rewritten.
+func TestWriteTunnelNeverRewritesASymlinkSwappedInForTheTarget(t *testing.T) {
+	brain0 := t.TempDir()
+	src := filepath.Join(brain0, "wiki", "a", "facts", "s.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(src), 0o755))
+	require.NoError(t, os.WriteFile(src, []byte("x\n"), 0o644))
+	tdir := filepath.Join(brain0, "wiki", "b", "facts")
+	require.NoError(t, os.MkdirAll(tdir, 0o755))
+	victim := filepath.Join(brain0, "raw", "victim.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	tgt := filepath.Join(tdir, "t.md")
+	require.NoError(t, os.WriteFile(tgt, []byte("t\n"), 0o644))
+
+	var stop atomic.Bool
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		tmp := tgt + ".swap"
+		for i := 0; !stop.Load(); i++ {
+			_ = os.Remove(tmp)
+			if i%2 == 0 {
+				_ = os.WriteFile(tmp, []byte("t\n"), 0o644)
+			} else {
+				_ = os.Symlink(filepath.Join("..", "..", "..", "raw", "victim.md"), tmp)
+			}
+			_ = os.Rename(tmp, tgt)
+		}
+	}()
+	ok := 0
+	for deadline := time.Now().Add(1500 * time.Millisecond); time.Now().Before(deadline); {
+		if brain.WriteTunnel(brain0, "wiki/a/facts/s.md", "wiki/b/facts/t.md") == nil {
+			ok++
+		}
+		_ = os.WriteFile(src, []byte("x\n"), 0o644)
+	}
+	stop.Store(true)
+	wg.Wait()
+	got, err := os.ReadFile(victim)
+	require.NoError(t, err)
+	assert.Equal(t, "untouched\n", string(got), "the swapped-in symlink's target was rewritten")
+	assert.Positive(t, ok, "positive control: some tunnels were written to the regular target")
+}

ingestion/internal/brainfs/brainfs.go

@@ -104,6 +104,17 @@ func (b *Brain) ReadDirRegular(relDir string) ([]string, error) {
 	return names, nil
 }
 
+// cleanRel refuses a path that is not clean and local. realDir checks the
+// cleaned parent, so the I/O must use that same path: os.Root resolves ".."
+// after following a symlink, and a ".." after a symlinked directory would
+// otherwise pass the check and redirect the read or write.
+func cleanRel(rel string) error {
+	if rel == "" || path.Clean(rel) != rel || !filepath.IsLocal(rel) || strings.Contains(rel, "\\") {
+		return fmt.Errorf("%q: not a clean brain-relative path: %w", rel, ErrNotRegular)
+	}
+	return nil
+}
+
 // ReadDirDirs lists the real subdirectories directly in a brain-relative
 // directory, by name. Every component of relDir must be a real directory
 // (ErrNotRegular otherwise); symlinks to directories are left out.
@@ -125,9 +136,58 @@ func (b *Brain) ReadDirDirs(relDir string) ([]string, error) {
 	return names, 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). A dangling or swapped-in
+// symlink is refused; nothing is created at its target.
+func (b *Brain) OpenLock(rel string) (*os.File, error) {
+	if err := cleanRel(rel); err != nil {
+		return nil, err
+	}
+	if err := b.realDir(path.Dir(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 || lerr != nil || !lfi.Mode().IsRegular() || !os.SameFile(lfi, hfi) {
+		_ = f.Close()
+		return nil, fmt.Errorf("%s: changed while opening: %w", rel, ErrNotRegular)
+	}
+	return f, nil
+}
+
+// RemoveLock removes the lock file at rel through the root (a symlink there
+// is removed itself, never its target).
+func (b *Brain) RemoveLock(rel string) error {
+	if err := cleanRel(rel); err != nil {
+		return err
+	}
+	if err := b.realDir(path.Dir(rel)); err != nil {
+		return err
+	}
+	return b.root.Remove(rel)
+}
+
 // ReadRegular reads a brain-relative path, refusing anything that is not a
 // regular file, both before the open and on the opened handle.
 func (b *Brain) ReadRegular(rel string) ([]byte, error) {
+	if err := cleanRel(rel); err != nil {
+		return nil, err
+	}
+	if err := b.realDir(path.Dir(rel)); err != nil {
+		return nil, err
+	}
 	fi, err := b.root.Lstat(rel)
 	if err != nil {
 		return nil, err
@@ -154,6 +214,12 @@ func (b *Brain) readOpened(rel string) ([]byte, error) { return b.readOpenedMax(
 // ReadRegularMax is ReadRegular with a size limit, checked on the opened
 // handle before reading (max < 0 means no limit).
 func (b *Brain) ReadRegularMax(rel string, max int64) ([]byte, error) {
+	if err := cleanRel(rel); err != nil {
+		return nil, err
+	}
+	if err := b.realDir(path.Dir(rel)); err != nil {
+		return nil, err
+	}
 	fi, err := b.root.Lstat(rel)
 	if err != nil {
 		return nil, err
@@ -249,3 +315,51 @@ func (b *Brain) WalkRegular(relDir string, fn func(rel string) error, onErr func
 		return fn(p)
 	})
 }
+
+// WriteRegular replaces the contents of an existing regular file at a
+// brain-relative path. It never creates a file and never writes through a
+// final symlink: os.Root.OpenFile follows an in-root final symlink even with
+// O_NOFOLLOW (verified on go1.27), so the path is Lstat-ed through the root
+// first and the opened handle must be that same file (os.SameFile), which
+// also catches a swap between the two. O_NONBLOCK keeps a FIFO from blocking
+// the open. Every directory above the file must be a real directory
+// (hyperguild#173); a directory swapped in after that check is the #167
+// residual.
+func (b *Brain) WriteRegular(rel string, data []byte) error {
+	if err := cleanRel(rel); err != nil {
+		return err
+	}
+	// Every directory above the file must be real: os.Root follows an
+	// in-brain intermediate symlink, which would redirect the write
+	// elsewhere in the brain (hyperguild#173). A swap after this check is
+	// the #167 residual.
+	if err := b.realDir(path.Dir(rel)); err != nil {
+		return err
+	}
+	lfi, err := b.root.Lstat(rel)
+	if err != nil {
+		return err
+	}
+	if !lfi.Mode().IsRegular() {
+		return fmt.Errorf("%s: %w", rel, ErrNotRegular)
+	}
+	f, err := b.root.OpenFile(rel, os.O_WRONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = f.Close() }()
+	fi, err := f.Stat()
+	if err != nil {
+		return err
+	}
+	if !fi.Mode().IsRegular() || !os.SameFile(lfi, fi) {
+		return fmt.Errorf("%s: changed while opening: %w", rel, ErrNotRegular)
+	}
+	if err := f.Truncate(0); err != nil {
+		return err
+	}
+	if _, err := f.Write(data); err != nil {
+		return err
+	}
+	return f.Close()
+}

ingestion/internal/brainfs/brainfs_test.go

@@ -218,7 +218,7 @@ func TestReadDirRegularListsOnlyRegularFilesAndRefusesSymlinkedComponents(t *tes
 // A final component swapped for a symlink to another regular file in the
 // brain between the Lstat and the open: os.Root follows in-root links, so
 // only comparing the two (os.SameFile) refuses it.
-func TestReadRegularNeverReturnsAnInBrainFileSwappedInBehindASymlink(t *testing.T) {
+func TestReadRegularDoesNotReturnAnInBrainFileSwappedInBehindASymlink(t *testing.T) {
 	dir := t.TempDir()
 	require.NoError(t, os.WriteFile(filepath.Join(dir, "s.md"), []byte("zqsamefilesentinel"), 0o644))
 	p := filepath.Join(dir, "r.md")
@@ -263,6 +263,52 @@ func TestReadRegularNeverReturnsAnInBrainFileSwappedInBehindASymlink(t *testing.
 	assert.Positive(t, ok, "positive control: the regular file is read")
 }
 
+func TestWriteRegularRefusesFinalSymlinksFIFOsEscapesAndMissingFilesAndRewritesRegularFiles(t *testing.T) {
+	dir := t.TempDir()
+	outside := filepath.Join(t.TempDir(), "o.md")
+	require.NoError(t, os.WriteFile(outside, []byte("untouched"), 0o644))
+	require.NoError(t, os.Symlink(outside, filepath.Join(dir, "l.md")))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(dir, "f.md"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "n.md"), []byte("old content"), 0o644))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	assert.Error(t, b.WriteRegular("l.md", []byte("x")))
+	got, _ := os.ReadFile(outside)
+	assert.Equal(t, "untouched", string(got))
+
+	// A symlink to another file inside the brain: os.Root would allow it,
+	// only O_NOFOLLOW refuses it.
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "in.md"), []byte("inside"), 0o644))
+	require.NoError(t, os.Symlink("in.md", filepath.Join(dir, "il.md")))
+	assert.Error(t, b.WriteRegular("il.md", []byte("x")))
+	got, _ = os.ReadFile(filepath.Join(dir, "in.md"))
+	assert.Equal(t, "inside", string(got))
+
+	// A reader held open, so a non-blocking write open would succeed. The
+	// Lstat type check refuses the FIFO first; the handle check and
+	// O_NONBLOCK matter only if it is swapped in after the Lstat.
+	r, err := os.OpenFile(filepath.Join(dir, "f.md"), os.O_RDONLY|syscall.O_NONBLOCK, 0)
+	require.NoError(t, err)
+	defer func() { _ = r.Close() }()
+	done := make(chan error, 1)
+	go func() { done <- b.WriteRegular("f.md", []byte("x")) }()
+	select {
+	case err := <-done:
+		assert.Error(t, err)
+	case <-time.After(3 * time.Second):
+		t.Fatal("WriteRegular hung on a FIFO")
+	}
+
+	assert.Error(t, b.WriteRegular("../"+filepath.Base(filepath.Dir(outside))+"/o.md", []byte("x")))
+	assert.Error(t, b.WriteRegular("missing.md", []byte("x")), "does not create files")
+
+	require.NoError(t, b.WriteRegular("n.md", []byte("new")))
+	got, _ = os.ReadFile(filepath.Join(dir, "n.md"))
+	assert.Equal(t, "new", string(got), "truncated and rewritten")
+}
+
 func TestReadDirDirsListsOnlyRealSubdirsAndRefusesSymlinkedComponents(t *testing.T) {
 	dir := t.TempDir()
 	require.NoError(t, os.MkdirAll(filepath.Join(dir, "a", "real"), 0o755))
@@ -280,3 +326,53 @@ func TestReadDirDirsListsOnlyRealSubdirsAndRefusesSymlinkedComponents(t *testing
 	_, err = b.ReadDirDirs("alias")
 	assert.ErrorIs(t, err, ErrNotRegular)
 }
+
+// hyperguild#173: a file reached through a symlinked directory inside the
+// brain is refused for reads and writes, so a caller-supplied path cannot be
+// redirected to another part of the brain.
+func TestReadAndWriteRegularRefuseAFileBehindASymlinkedDirectory(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "raw", "v.md"), []byte("untouched"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(dir, "wiki", "alias")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	_, err = b.ReadRegular("wiki/alias/v.md")
+	assert.ErrorIs(t, err, ErrNotRegular)
+	_, err = b.ReadRegularMax("wiki/alias/v.md", 100)
+	assert.ErrorIs(t, err, ErrNotRegular)
+	assert.ErrorIs(t, b.WriteRegular("wiki/alias/v.md", []byte("x")), ErrNotRegular)
+	got, _ := os.ReadFile(filepath.Join(dir, "raw", "v.md"))
+	assert.Equal(t, "untouched", string(got))
+	got, err = b.ReadRegular("raw/v.md")
+	require.NoError(t, err, "positive control: the real path still reads")
+	assert.Equal(t, "untouched", string(got))
+}
+
+// realDir checks the cleaned parent, so the I/O must use that same clean
+// path: os.Root resolves ".." after following a symlink, and a ".." placed
+// after a symlinked directory would otherwise pass the check and redirect.
+func TestReadAndWriteRegularRefuseAPathThatIsNotClean(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "raw", "v.md"), []byte("untouched"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw", "facts"), filepath.Join(dir, "wiki", "alias")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	for _, rel := range []string{"wiki/alias/../v.md", "./raw/v.md", "raw//v.md", "/raw/v.md"} {
+		got, err := b.ReadRegular(rel)
+		assert.ErrorIs(t, err, ErrNotRegular, rel)
+		assert.NotContains(t, string(got), "untouched", rel)
+		_, err = b.ReadRegularMax(rel, 100)
+		assert.ErrorIs(t, err, ErrNotRegular, rel)
+		assert.ErrorIs(t, b.WriteRegular(rel, []byte("OVERWRITTEN")), ErrNotRegular, rel)
+	}
+	got, _ := os.ReadFile(filepath.Join(dir, "raw", "v.md"))
+	assert.Equal(t, "untouched", string(got))
+}

ingestion/internal/brainfs/brainfstest/brainfstest.go

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

ingestion/internal/classification/classification.go

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

ingestion/internal/classification/root_test.go

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

ingestion/internal/mcp/edit_pathio_test.go

@@ -0,0 +1,61 @@
+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/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") },
+		"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)
+			require.NoError(t, os.Symlink(tgt, filepath.Join(dir, "wiki", "homelab", "facts", "n.md.lock")))
+			srv := mcp.NewServer(dir, nil, nil, nil)
+			_ = call(t, srv, "brain_edit", map[string]any{"path": "wiki/homelab/facts/n.md", "old_str": "beta", "new_str": "BETA"})
+			_, err := os.Lstat(tgt)
+			assert.True(t, os.IsNotExist(err), "a file was created at the lock symlink's target")
+		})
+	}
+}

ingestion/internal/mcp/readexcerpt_root_test.go

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

ingestion/internal/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)
 	}
@@ -131,7 +138,7 @@ func (s *Server) brainEdit(ctx context.Context, args json.RawMessage) (json.RawM
 	// to the editor after every edit (PR #147 review, escape E1).
 	origin, writtenBy := provenanceFrom(ctx)
 	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)

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,20 +220,32 @@ 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.
+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)
+	}
+	f, err := bfs.OpenLock(lockRel)
+	_ = bfs.Close()
+	if err != nil {
+		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)
+		return nil, fmt.Errorf("notes: flock %s: %w", lockRel, err)
 	}
 	return func() {
 		_ = syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
 		_ = f.Close()
-		_ = os.Remove(abs + ".lock")
+		if b, err := brainfs.Open(t.Brain); err == nil {
+			_ = b.RemoveLock(lockRel)
+			_ = b.Close()
+		}
 	}, nil
 }
 

ingestion/internal/notes/read_root_test.go

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

ingestion/internal/pipeline/backfill.go

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

ingestion/internal/pipeline/pipeline.go

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

ingestion/internal/pipeline/refs.go

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

ingestion/internal/pipeline/root_test.go

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

ingestion/internal/search/brainroot_test.go

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

ingestion/internal/session/id_test.go

@@ -0,0 +1,177 @@
+package session
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync/atomic"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/sys/unix"
+)
+
+// session_log passed the caller's session_id straight into
+// filepath.Join(sessionsDir, id+".jsonl") and opened it O_CREATE|O_APPEND:
+// path segments in the id created or appended files anywhere the pod could
+// write. The id is now a plain name, and the open does not follow a final
+// symlink.
+func TestAppendRefusesSessionIDsThatAreNotPlainNames(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, "sessions")
+	for _, id := range []string{"../x", "a/b", "/abs", ".", "..", ".hidden", "", "a\\b", "a\x00b"} {
+		assert.Error(t, Append(dir, id, Entry{SessionID: id}), "%q", id)
+	}
+	ents, _ := os.ReadDir(root)
+	for _, e := range ents {
+		assert.Equal(t, "sessions", e.Name(), "nothing created beside the sessions dir")
+	}
+	for _, id := range []string{"1557b2e1-bf0d-5c4f-bbe3-0754d087e356", "_routing", "2026-05-05-infra.plan", "0"} {
+		require.NoError(t, Append(dir, id, Entry{SessionID: id}), "positive control: %q", id)
+	}
+}
+
+func TestAppendDoesNotWriteThroughASymlinkedLog(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, "sessions")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	victim := filepath.Join(root, "victim.md")
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "victim.md"), filepath.Join(dir, "s.jsonl")))
+	assert.Error(t, Append(dir, "s", Entry{SessionID: "s"}))
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched\n", string(got))
+}
+
+func TestReadRefusesSessionIDsThatAreNotPlainNames(t *testing.T) {
+	root := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(root, "x.jsonl"), []byte(`{"session_id":"x"}`+"\n"), 0o644))
+	_, err := Read(filepath.Join(root, "sessions"), "../x")
+	assert.Error(t, err)
+}
+
+// A name that starts plainly and then climbs out with ".." is exactly what the
+// ban on "/" in the id's tail stops: filepath.Join cleans "a/../../x" to a
+// path beside the sessions dir without needing sessions/a to exist. The
+// assertion is on the refusal itself (ErrInvalidID), not on any error.
+func TestAppendRefusesAnIDThatClimbsOutAfterAPlainPrefix(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, "sessions")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	for _, id := range []string{"a/../../escape", "a/../../../escape", "a/../b"} {
+		err := Append(dir, id, Entry{SessionID: id})
+		assert.ErrorIs(t, err, ErrInvalidID, "%q", id)
+	}
+	_, err := os.Lstat(filepath.Join(root, "escape.jsonl"))
+	assert.True(t, errors.Is(err, os.ErrNotExist), "nothing created beside the sessions dir")
+	_, err = os.Lstat(filepath.Join(dir, "b.jsonl"))
+	assert.True(t, errors.Is(err, os.ErrNotExist), "no in-dir alias created either")
+}
+
+// Append does no Lstat type check, so O_NONBLOCK is the only thing that keeps
+// a FIFO named <id>.jsonl with no reader from blocking session_log forever.
+func TestAppendReturnsPromptlyOnAFIFOLogWithNoReader(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "sessions")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	fifo := filepath.Join(dir, "s.jsonl")
+	require.NoError(t, syscall.Mkfifo(fifo, 0o644))
+	done := make(chan error, 1)
+	go func() { done <- Append(dir, "s", Entry{SessionID: "s"}) }()
+	select {
+	case err := <-done:
+		assert.Error(t, err, "a FIFO with no reader is refused, not written")
+	case <-time.After(3 * time.Second):
+		// Unblock the stuck open so the goroutine and TempDir cleanup finish.
+		if r, err := os.OpenFile(fifo, os.O_RDONLY|syscall.O_NONBLOCK, 0); err == nil {
+			defer r.Close() //nolint:errcheck
+		}
+		<-done
+		t.Fatal("Append blocked on a FIFO log with no reader")
+	}
+}
+
+// hyperguild#173: session_log followed a symlinked sessions dir.
+func TestAppendRefusesASymlinkedSessionsDir(t *testing.T) {
+	root := t.TempDir()
+	elsewhere := filepath.Join(root, "elsewhere")
+	require.NoError(t, os.MkdirAll(elsewhere, 0o755))
+	dir := filepath.Join(root, "sessions")
+	require.NoError(t, os.Symlink("elsewhere", dir))
+	assert.Error(t, Append(dir, "s", Entry{SessionID: "s"}))
+	ents, _ := os.ReadDir(elsewhere)
+	assert.Empty(t, ents, "a log was created through the symlinked dir")
+}
+
+// The sessions dir is swapped (RENAME_EXCHANGE) with a symlink to a
+// directory outside the brain while Append runs. Append opens through an
+// os.Root on the sessions dir's parent, so a swap can redirect it only
+// inside that parent (the #167 residual), never outside it.
+func TestAppendNeverCreatesALogOutsideTheParentUnderADirSwapRace(t *testing.T) {
+	brain := t.TempDir()
+	outside := t.TempDir()
+	dir := filepath.Join(brain, "sessions")
+	other := filepath.Join(brain, "sessions.link")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	require.NoError(t, os.Symlink(outside, other))
+	var stop atomic.Bool
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		for !stop.Load() {
+			_ = unix.Renameat2(unix.AT_FDCWD, dir, unix.AT_FDCWD, other, unix.RENAME_EXCHANGE)
+		}
+	}()
+	ok := 0
+	for i := 0; i < 20000; i++ {
+		if Append(dir, fmt.Sprintf("s%d", i), Entry{SessionID: "s"}) == nil {
+			ok++
+		}
+	}
+	stop.Store(true)
+	<-done
+	ents, _ := os.ReadDir(outside)
+	assert.Empty(t, ents, "logs were created outside the brain")
+	assert.Positive(t, ok, "positive control: appends to the real dir succeed")
+}
+
+// The log file is swapped between a regular file and a symlink to another
+// file in the brain while Append runs: Append writes only after confirming
+// the path is the regular file it opened, so the other file never grows.
+func TestAppendNeverWritesThroughALogSwappedForASymlink(t *testing.T) {
+	brain := t.TempDir()
+	dir := filepath.Join(brain, "sessions")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	victim := filepath.Join(brain, "victim.md")
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	log := filepath.Join(dir, "s.jsonl")
+	var stop atomic.Bool
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		tmp := log + ".swap"
+		for i := 0; !stop.Load(); i++ {
+			_ = os.Remove(tmp)
+			if i%2 == 0 {
+				_ = os.WriteFile(tmp, nil, 0o644)
+			} else {
+				_ = os.Symlink(filepath.Join("..", "victim.md"), tmp)
+			}
+			_ = os.Rename(tmp, log)
+		}
+	}()
+	ok := 0
+	for i := 0; i < 20000; i++ {
+		if Append(dir, "s", Entry{SessionID: "s"}) == nil {
+			ok++
+		}
+	}
+	stop.Store(true)
+	<-done
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched\n", string(got), "a log line was written through the swapped-in symlink")
+	assert.Positive(t, ok, "positive control: appends to the regular log succeed")
+}

ingestion/internal/session/session.go

@@ -9,6 +9,8 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"regexp"
+	"syscall"
 	"time"
 )
 
@@ -42,16 +44,63 @@ type Attempt struct {
 	RunnerOutput  string `json:"runner_output,omitempty"`
 }
 
+// idPattern is a plain file name: session_log takes the id from the caller,
+// and a path segment in it created or appended files anywhere the pod could
+// write (hyperguild#169).
+var idPattern = regexp.MustCompile(`^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$`)
+
+// ErrInvalidID is returned when a session id is not a plain file name.
+var ErrInvalidID = errors.New("session id is not a plain name")
+
+func checkID(sessionID string) error {
+	if !idPattern.MatchString(sessionID) {
+		return fmt.Errorf("%w: %q", ErrInvalidID, sessionID)
+	}
+	return nil
+}
+
 // Append writes entry as a single JSON line to sessionsDir/{sessionID}.jsonl.
+// The open does not follow a final symlink.
 func Append(sessionsDir, sessionID string, entry Entry) error {
-	if err := os.MkdirAll(sessionsDir, 0o755); err != nil {
+	if err := checkID(sessionID); err != nil {
+		return err
+	}
+	// Opened through an os.Root on the sessions dir's parent (the brain dir),
+	// so a sessions dir swapped for a symlink after the check below can
+	// redirect the log only inside that parent, never outside it (#173; the
+	// in-brain swap is the #167 residual).
+	parentDir, name := filepath.Dir(sessionsDir), filepath.Base(sessionsDir)
+	if err := os.MkdirAll(parentDir, 0o755); err != nil {
+		return fmt.Errorf("create sessions parent: %w", err)
+	}
+	root, err := os.OpenRoot(parentDir)
+	if err != nil {
+		return fmt.Errorf("open sessions parent: %w", err)
+	}
+	defer func() { _ = root.Close() }()
+	if err := root.Mkdir(name, 0o755); err != nil && !errors.Is(err, fs.ErrExist) {
 		return fmt.Errorf("create sessions dir: %w", err)
 	}
-	path := filepath.Join(sessionsDir, sessionID+".jsonl")
-	f, err := os.OpenFile(path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o644)
+	// The sessions dir itself must be a real directory, not a symlink that
+	// redirects the log elsewhere (hyperguild#173).
+	if fi, err := root.Lstat(name); err != nil {
+		return fmt.Errorf("stat sessions dir: %w", err)
+	} else if !fi.IsDir() {
+		return fmt.Errorf("sessions dir %s is not a real directory", sessionsDir)
+	}
+	logRel := name + "/" + sessionID + ".jsonl"
+	f, err := root.OpenFile(logRel, os.O_CREATE|os.O_APPEND|os.O_WRONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0o644)
 	if err != nil {
 		return fmt.Errorf("open session log: %w", err)
 	}
+	// os.Root follows an in-root final symlink even with O_NOFOLLOW, so
+	// confirm, before writing, that the path is the regular file we opened.
+	hfi, herr := f.Stat()
+	lfi, lerr := root.Lstat(logRel)
+	if herr != nil || lerr != nil || !lfi.Mode().IsRegular() || !os.SameFile(lfi, hfi) {
+		_ = f.Close()
+		return fmt.Errorf("session log %s is not a regular file", logRel)
+	}
 
 	line, err := json.Marshal(entry)
 	if err != nil {
@@ -70,6 +119,9 @@ func Append(sessionsDir, sessionID string, entry Entry) error {
 
 // Read returns all entries for sessionID. Returns empty slice if no log exists.
 func Read(sessionsDir, sessionID string) ([]Entry, error) {
+	if err := checkID(sessionID); err != nil {
+		return nil, err
+	}
 	path := filepath.Join(sessionsDir, sessionID+".jsonl")
 	f, err := os.Open(path)
 	if errors.Is(err, fs.ErrNotExist) {

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

@@ -18,9 +18,14 @@ import (
 	"sort"
 	"strconv"
 	"strings"
+	"sync"
+	"sync/atomic"
 	"time"
 )
 
+// shutdownFlushTimeout bounds the final flush when Watch stops.
+var shutdownFlushTimeout = 5 * time.Second
+
 // DefaultInterval is used when Watch is given a non-positive interval.
 const DefaultInterval = 30 * time.Second
 
@@ -41,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.
@@ -54,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)))
 	}
@@ -108,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
@@ -133,13 +151,32 @@ func Scan(brainDir string) (Result, error) {
 // queue until Notify succeeds (see alertQueue): an outage delays them, and
 // any that do not fit the bounded queue, or are undeliverable, are counted in
 // a summary that is never dropped, so every incident is delivered or counted.
+//
+// Delivery runs in its own goroutine (hyperguild#164): a hung notifier, with
+// a full queue, blocked one flush for several notify timeouts, and while the
+// scan waited on it a planted link stayed readable for several intervals.
+// The scan hands alerts over without blocking; any that do not fit are
+// counted in the summary. When ctx ends, Watch returns after a final flush
+// of what was handed over (bounded by shutdownFlushTimeout); alerts that
+// flush cannot deliver are counted in one error log line instead. That
+// shutdown path only runs for a caller that cancels ctx: cmd/server passes
+// context.Background(), so in production the flush on handoff is what keeps
+// alerts from waiting on a restart.
 func Watch(ctx context.Context, brainDir string, interval time.Duration, n Notifier) {
 	if interval <= 0 {
 		interval = DefaultInterval
 	}
 	t := time.NewTicker(interval)
 	defer t.Stop()
-	q := &alertQueue{}
+	alerts := make(chan string, maxPending)
+	var overflow atomic.Int64
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() { defer wg.Done(); deliver(ctx, interval, n, alerts, &overflow) }()
+	// The scan is the only sender: closing alerts tells deliver to drain and
+	// flush once more, and Watch returns only after it has.
+	defer func() { close(alerts); wg.Wait() }()
+	q := alertSender{alerts: alerts, overflow: &overflow}
 	reported := ""
 	for {
 		select {
@@ -158,17 +195,92 @@ 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.")
 			}
 		}
-		q.flush(ctx, n)
+	}
+}
+
+// alertSender hands alerts to deliver without ever blocking the scan; an
+// alert that does not fit is counted in overflow, which deliver adds to the
+// summary.
+type alertSender struct {
+	alerts   chan<- string
+	overflow *atomic.Int64
+}
+
+func (s alertSender) push(msg string) {
+	select {
+	case s.alerts <- msg:
+	default:
+		s.overflow.Add(1)
+	}
+}
+
+// deliver owns the alertQueue. It flushes as soon as an alert is handed
+// over, and again every interval while any are pending (outage retries).
+// When alerts is closed (Watch is stopping) it drains it and flushes once
+// more, bounded by shutdownFlushTimeout, so an alert handed over just before
+// shutdown is not lost (PR #180 review). Whatever that flush cannot deliver
+// is logged as one error with its counts, never dropped silently.
+func deliver(ctx context.Context, interval time.Duration, n Notifier, alerts <-chan string, overflow *atomic.Int64) {
+	t := time.NewTicker(interval)
+	defer t.Stop()
+	q := &alertQueue{}
+	// drain moves everything handed over into the queue; it reports false
+	// once alerts is closed.
+	drain := func() bool {
+		defer func() { q.suppressed += int(overflow.Swap(0)) }()
+		for {
+			select {
+			case msg, ok := <-alerts:
+				if !ok {
+					return false
+				}
+				q.push(msg)
+			default:
+				return true
+			}
+		}
+	}
+	for {
+		select {
+		case msg, ok := <-alerts:
+			if ok {
+				q.push(msg)
+				ok = drain()
+			}
+			if !ok {
+				q.suppressed += int(overflow.Swap(0))
+				fctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), shutdownFlushTimeout)
+				q.flush(fctx, n)
+				cancel()
+				if len(q.items) > 0 || q.suppressed > 0 {
+					slog.Error("symlink tripwire alerts not delivered at shutdown",
+						"undelivered", len(q.items), "suppressed", q.suppressed)
+				}
+				return
+			}
+			q.flush(ctx, n)
+		case <-t.C:
+			if !drain() {
+				continue // the closed channel is handled by the case above
+			}
+			q.flush(ctx, n)
+		}
 	}
 }
 
@@ -229,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/symlinkguard/symlinkguard_test.go

@@ -1,10 +1,12 @@
 package symlinkguard
 
 import (
+	"bytes"
 	"context"
 	"errors"
 	"fmt"
 	"os"
+	"log/slog"
 	"path/filepath"
 	"strconv"
 	"strings"
@@ -345,13 +347,19 @@ func TestWatchDropsAMessageThatNeverSendsSoLaterAlertsFlow(t *testing.T) {
 	}, 3*time.Second, 10*time.Millisecond, "a later alert is delivered despite a poison message")
 }
 
-// toggleNotifier fails while down is set.
+// toggleNotifier fails while down is set. Like the real audit.NtfyNotifier
+// (http.NewRequestWithContext), it also fails, without recording, when its
+// ctx is already done (PR #180 round 2: notifiers that ignored ctx let a
+// final flush on the cancelled ctx pass).
 type toggleNotifier struct {
 	recNotifier
 	down atomic.Bool
 }
 
 func (r *toggleNotifier) Notify(ctx context.Context, m string) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
 	if r.down.Load() {
 		return errors.New("ntfy down")
 	}
@@ -496,3 +504,271 @@ func TestWatchDropsAPoisonMessageAndCountsIt(t *testing.T) {
 		return false
 	}, 3*time.Second, 5*time.Millisecond, "the dropped poison alert is counted in a summary")
 }
+
+// hungNotifier answers every Notify only after latency (or when ctx ends),
+// with an outage error: an ntfy that accepts connections but never responds
+// until its timeout.
+type hungNotifier struct{ latency time.Duration }
+
+func (h hungNotifier) Notify(ctx context.Context, _ string) error {
+	select {
+	case <-time.After(h.latency):
+	case <-ctx.Done():
+	}
+	return errors.New("ntfy timeout")
+}
+
+func waitGone(t *testing.T, link string) {
+	t.Helper()
+	require.Eventually(t, func() bool { _, err := os.Lstat(link); return os.IsNotExist(err) }, 10*time.Second, time.Millisecond)
+}
+
+// hyperguild#164: alerts were flushed in the scan goroutine, so with a hung
+// ntfy and a full queue one flush (6 x notify timeout) delayed the next scan.
+// The notifier here is slower than the interval, as in production (10 s
+// timeout vs 30 s interval with 6 messages), so the alert handoff is full:
+// a scan that waited on it would keep a link for seconds.
+func TestWatchLinkLifetimeStaysNearOneIntervalWithANotifierSlowerThanTheInterval(t *testing.T) {
+	const interval = 100 * time.Millisecond
+	brain := t.TempDir()
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go Watch(ctx, brain, interval, hungNotifier{latency: 400 * time.Millisecond})
+
+	for i := 0; i < 2*maxPending+3; i++ { // overfill queue and handoff
+		link := filepath.Join(brain, "fill"+strconv.Itoa(i))
+		require.NoError(t, os.Symlink(t.TempDir(), link))
+		waitGone(t, link)
+	}
+	var worst time.Duration
+	for i := 0; i < 6; i++ {
+		link := filepath.Join(brain, "probe"+strconv.Itoa(i))
+		require.NoError(t, os.Symlink(t.TempDir(), link))
+		planted := time.Now()
+		waitGone(t, link)
+		worst = max(worst, time.Since(planted))
+	}
+	assert.LessOrEqual(t, worst, interval+interval/2, "worst link lifetime %v with a hung notifier", worst)
+}
+
+// Review of PR #180: delivery waited for its own tick, about one interval
+// after the removal. An alert is now flushed as soon as it is handed over.
+func TestWatchDeliversARemovalAlertWellWithinOneInterval(t *testing.T) {
+	const interval = 400 * time.Millisecond
+	brain := t.TempDir()
+	n := &recNotifier{}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go Watch(ctx, brain, interval, n)
+	link := filepath.Join(brain, "prompt")
+	require.NoError(t, os.Symlink(t.TempDir(), link))
+	waitGone(t, link)
+	removed := time.Now()
+	require.Eventually(t, func() bool { return n.count() == 1 }, 2*time.Second, time.Millisecond)
+	assert.Less(t, time.Since(removed), interval/4)
+}
+
+// Review of PR #180: on ctx end, deliver returned without draining what the
+// scan had handed over, so a removal just before shutdown was neither
+// delivered nor counted. Watch now drains and flushes before returning.
+func TestWatchDeliversAnAlertHandedOverJustBeforeShutdown(t *testing.T) {
+	for i := 0; i < 20; i++ {
+		brain := t.TempDir()
+		n := &recNotifier{}
+		ctx, cancel := context.WithCancel(context.Background())
+		done := make(chan struct{})
+		go func() { Watch(ctx, brain, 5*time.Millisecond, n); close(done) }()
+		link := filepath.Join(brain, "late")
+		require.NoError(t, os.Symlink(t.TempDir(), link))
+		waitGone(t, link)
+		cancel()
+		<-done
+		require.Equal(t, 1, n.count(), "iteration %d: the removal alert was lost at shutdown", i)
+	}
+}
+
+// blockingNotifier holds every Notify until its ctx ends, tracking calls in
+// flight.
+type blockingNotifier struct{ inFlight atomic.Int32 }
+
+func (b *blockingNotifier) Notify(ctx context.Context, _ string) error {
+	b.inFlight.Add(1)
+	defer b.inFlight.Add(-1)
+	<-ctx.Done()
+	return ctx.Err()
+}
+
+// Watch does not return while its delivery goroutine is still notifying.
+func TestWatchReturnsOnlyAfterDeliveryHasStopped(t *testing.T) {
+	prev := shutdownFlushTimeout
+	shutdownFlushTimeout = 50 * time.Millisecond
+	t.Cleanup(func() { shutdownFlushTimeout = prev })
+	brain := t.TempDir()
+	n := &blockingNotifier{}
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() { Watch(ctx, brain, 5*time.Millisecond, n); close(done) }()
+	link := filepath.Join(brain, "x")
+	require.NoError(t, os.Symlink(t.TempDir(), link))
+	waitGone(t, link)
+	require.Eventually(t, func() bool { return n.inFlight.Load() == 1 }, 2*time.Second, time.Millisecond)
+	cancel()
+	select {
+	case <-done:
+	case <-time.After(5 * time.Second):
+		t.Fatal("Watch did not return after cancel")
+	}
+	assert.Zero(t, n.inFlight.Load(), "Notify still running after Watch returned")
+}
+
+// slowToggleNotifier fails slowly (a hung ntfy) while down, then records.
+type slowToggleNotifier struct {
+	recNotifier
+	down    atomic.Bool
+	latency time.Duration
+}
+
+func (r *slowToggleNotifier) Notify(ctx context.Context, m string) error {
+	if r.down.Load() {
+		select {
+		case <-time.After(r.latency):
+		case <-ctx.Done():
+		}
+		return errors.New("ntfy timeout")
+	}
+	return r.recNotifier.Notify(ctx, m)
+}
+
+// Review of PR #180: with a slow notifier the scan's handoff overflows, and
+// those alerts exist only in the overflow counter. Every removal is still
+// delivered or counted in the summary.
+func TestWatchCountsHandoffOverflowWithASlowNotifier(t *testing.T) {
+	brain := t.TempDir()
+	n := &slowToggleNotifier{latency: 30 * time.Millisecond}
+	n.down.Store(true)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go Watch(ctx, brain, 2*time.Millisecond, n)
+	const plants = 40
+	for i := 0; i < plants; i++ {
+		link := filepath.Join(brain, "ov"+strconv.Itoa(i))
+		require.NoError(t, os.Symlink(t.TempDir(), link))
+		waitGone(t, link)
+	}
+	n.down.Store(false)
+	delivered, counted := 0, 0
+	require.Eventually(t, func() bool {
+		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") {
+				var c int
+				_, _ = fmt.Sscanf(m[i+3:], "%d", &c)
+				counted += c
+			}
+		}
+		return delivered+counted == plants
+	}, 5*time.Second, 10*time.Millisecond, "delivered %d + counted %d of %d", delivered, counted, plants)
+}
+
+// An alert still queued when Watch stops (its send failed, the notifier has
+// since recovered, the retry tick has not come) is flushed once more before
+// Watch returns, on a ctx that is not the cancelled one: toggleNotifier fails
+// on a done ctx, as the real ntfy notifier does.
+func TestWatchFinalFlushSendsAQueuedAlertOnACtxThatOutlivesTheCancel(t *testing.T) {
+	brain := t.TempDir()
+	n := &toggleNotifier{}
+	n.down.Store(true)
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() { Watch(ctx, brain, 300*time.Millisecond, n); close(done) }()
+	link := filepath.Join(brain, "queued")
+	require.NoError(t, os.Symlink(t.TempDir(), link))
+	waitGone(t, link)
+	time.Sleep(20 * time.Millisecond) // let the immediate send fail
+	n.down.Store(false)
+	cancel()
+	<-done
+	assert.Equal(t, 1, n.count(), "the queued alert was not flushed at shutdown")
+}
+
+// lockedBuffer is a goroutine-safe log sink: Watch goroutines of earlier
+// tests may still log while one test captures.
+type lockedBuffer struct {
+	mu  sync.Mutex
+	buf bytes.Buffer
+}
+
+func (b *lockedBuffer) Write(p []byte) (int, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.Write(p)
+}
+
+func (b *lockedBuffer) String() string { b.mu.Lock(); defer b.mu.Unlock(); return b.buf.String() }
+
+func captureLog(t *testing.T) *lockedBuffer {
+	t.Helper()
+	b := &lockedBuffer{}
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(b, nil)))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+	return b
+}
+
+// PR #180 round 2: when the final flush fails (ntfy hung at shutdown) the
+// undelivered alerts vanished with only "will retry" warnings. Watch now logs
+// one error with both counts.
+func TestWatchLogsUndeliveredAndSuppressedCountsWhenTheFinalFlushFails(t *testing.T) {
+	prev := shutdownFlushTimeout
+	shutdownFlushTimeout = 50 * time.Millisecond
+	t.Cleanup(func() { shutdownFlushTimeout = prev })
+	logs := captureLog(t)
+	brain := t.TempDir()
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() { Watch(ctx, brain, 5*time.Millisecond, hungNotifier{latency: time.Hour}); close(done) }()
+	link := filepath.Join(brain, "lost")
+	require.NoError(t, os.Symlink(t.TempDir(), link))
+	waitGone(t, link)
+	cancel()
+	<-done
+	out := logs.String()
+	assert.Contains(t, out, "level=ERROR")
+	assert.Contains(t, out, `msg="symlink tripwire alerts not delivered at shutdown"`)
+	assert.Contains(t, out, "undelivered=1")
+	assert.Contains(t, out, "suppressed=0")
+}
+
+// deliver, given a handoff that already holds alerts and is closed, moves them
+// into the queue and runs the final flush, even though the ctx is cancelled:
+// the drain-on-close path, without depending on when the close lands.
+func TestDeliverFlushesAlertsDrainedFromAClosedHandoffOnACancelledCtx(t *testing.T) {
+	alerts := make(chan string, 3)
+	alerts <- "a1"
+	alerts <- "a2"
+	close(alerts)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	n := &toggleNotifier{}
+	var overflow atomic.Int64
+	deliver(ctx, time.Hour, n, alerts, &overflow)
+	assert.Equal(t, []string{"a1", "a2"}, n.msgs)
+}
+
+// PR #180 round 2: when the first receive after close finds the handoff empty,
+// overflow counted by the scan was never moved into the summary.
+func TestDeliverCountsOverflowWhenTheHandoffIsClosedAndEmpty(t *testing.T) {
+	alerts := make(chan string)
+	close(alerts)
+	n := &recNotifier{}
+	var overflow atomic.Int64
+	overflow.Store(3)
+	deliver(context.Background(), time.Hour, n, alerts, &overflow)
+	require.Len(t, n.msgs, 1)
+	assert.Contains(t, n.msgs[0], "3 further alert(s)")
+}

ingestion/internal/vectorstore/sync_root_test.go

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