fix(brainfs,session): clean paths only; session logs open through the brain root (#173)

Review round 1 on PR #187:

- realDir checked the cleaned parent while Lstat/OpenFile used the raw
  path; os.Root resolves ".." after following a symlink, so a ".." placed
  after a symlinked directory passed the check and redirected the read or
  write. ReadRegular, ReadRegularMax and WriteRegular now refuse a path
  that is not clean and local (ErrNotRegular). No current entry point
  reached it (callers clean first); the primitive no longer relies on that.
- session.Append checked the sessions dir with Lstat, then opened by plain
  path: a symlink swapped in between created logs outside the brain
  (29k in the reviewer's RENAME_EXCHANGE race). It now opens through an
  os.Root on the sessions dir's parent, so a swap can only redirect inside
  the brain (#167), and, since os.Root follows an in-root final symlink
  even with O_NOFOLLOW, writes only after confirming the path is the
  regular file it opened (Lstat + os.SameFile).
- Endpoint tests assert ErrorIs(brainfs.ErrNotRegular) and have positive
  controls.

golang.org/x/sys moves from indirect to direct (unix.Renameat2 in the
session race test); it was already in the module graph.

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

ingestion/cmd/server/jwt_validator.go

@@ -2,24 +2,25 @@ package main
 
 import (
 	"context"
+	"fmt"
 	"log/slog"
 
 	chassisauth "git.d-ma.be/mathias/mcp-chassis/auth"
-
-	"github.com/mathiasbq/hyperguild/ingestion/internal/startupretry"
 )
 
-// buildJWTValidator runs OIDC discovery under policy, so a 502 from an auth
-// upstream that is not serving yet on a cold boot is retried instead of
-// exiting (#83). It honours ctx between attempts.
-func buildJWTValidator(
-	ctx context.Context, logger *slog.Logger, issuer, audience string, policy startupretry.Policy,
-) (*chassisauth.JWTValidator, error) {
-	return startupretry.Do(ctx, policy, func(ctx context.Context) (*chassisauth.JWTValidator, error) {
-		v, err := chassisauth.NewJWTValidator(ctx, issuer, audience)
-		if err != nil {
-			logger.Warn("oidc discovery not ready, retrying", "err", err)
-		}
-		return v, err
-	})
+// buildJWTValidator builds the JWT validator for issuer (nil when issuer is
+// empty: JWT auth disabled). Since mcp-chassis v0.7 construction no longer
+// fails when OIDC discovery does (mcp-chassis#4): the issuer resolves lazily,
+// and until it does a JWT is answered 503-and-retry, not 401. That replaces
+// #83's boot-time retry loop (hyperguild#155). An issuer still unresolved at
+// boot is logged, so a misconfigured issuer is visible rather than silent.
+func buildJWTValidator(ctx context.Context, logger *slog.Logger, issuer, audience string) (*chassisauth.JWTValidator, error) {
+	v, err := chassisauth.NewJWTValidator(ctx, issuer, audience)
+	if err != nil {
+		return nil, fmt.Errorf("build jwt validator: %w", err)
+	}
+	if ok, rerr := v.Ready(ctx); !ok {
+		logger.Warn("jwt issuer not resolved at boot; JWTs answer 503 until it is", "issuer", issuer, "err", rerr)
+	}
+	return v, nil
 }

ingestion/cmd/server/jwt_validator_test.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"bytes"
 	"context"
 	"io"
 	"log/slog"
@@ -8,12 +9,11 @@ import (
 	"net/http/httptest"
 	"sync/atomic"
 	"testing"
-	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	"github.com/mathiasbq/hyperguild/ingestion/internal/startupretry"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/metrics"
 )
 
 // fakeIssuer answers OIDC discovery with 502 for the first fail requests, as
@@ -41,46 +41,71 @@ func fakeIssuer(t *testing.T, fail int32) (*httptest.Server, *atomic.Int32) {
 	return srv, &discoveries
 }
 
-var fastPolicy = startupretry.Policy{Attempts: 8, Base: time.Millisecond, Max: 5 * time.Millisecond}
-
-func TestBuildJWTValidatorRetriesDiscovery502sThenSucceeds(t *testing.T) {
-	srv, discoveries := fakeIssuer(t, 3)
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-
-	v, err := buildJWTValidator(ctx, slog.New(slog.DiscardHandler), srv.URL, "brain", fastPolicy)
+// #83 retried discovery at boot because chassis v0.2.0 failed construction on
+// a 502. Since chassis v0.7 (mcp-chassis#4) the validator is built anyway and
+// resolves the issuer lazily, so boot no longer waits or exits on it
+// (hyperguild#155). An unresolved issuer is logged at boot.
+func TestBuildJWTValidatorReturnsAValidatorWhileDiscovery502s(t *testing.T) {
+	srv, _ := fakeIssuer(t, 1000)
+	var buf bytes.Buffer
+	v, err := buildJWTValidator(context.Background(), slog.New(slog.NewTextHandler(&buf, nil)), srv.URL, "brain")
 	require.NoError(t, err)
 	assert.NotNil(t, v)
-	assert.Equal(t, int32(4), discoveries.Load(), "three 502s, then the successful discovery")
+	assert.Contains(t, buf.String(), "jwt issuer not resolved at boot")
 }
 
-func TestBuildJWTValidatorGivesUpAfterTheBudgetWithTheLastError(t *testing.T) {
-	srv, discoveries := fakeIssuer(t, 1000)
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-
-	_, err := buildJWTValidator(ctx, slog.New(slog.DiscardHandler), srv.URL, "brain", fastPolicy)
-	require.Error(t, err)
-	assert.Contains(t, err.Error(), "status 502")
-	assert.Equal(t, int32(8), discoveries.Load(), "bounded: exactly the attempt budget")
+func TestBuildJWTValidatorLogsNothingAgainstAHealthyIssuer(t *testing.T) {
+	srv, _ := fakeIssuer(t, 0)
+	var buf bytes.Buffer
+	v, err := buildJWTValidator(context.Background(), slog.New(slog.NewTextHandler(&buf, nil)), srv.URL, "brain")
+	require.NoError(t, err)
+	assert.NotNil(t, v)
+	assert.NotContains(t, buf.String(), "not resolved")
 }
 
-func TestBuildJWTValidatorStopsRetryingWhenTheContextIsCancelled(t *testing.T) {
+func TestBuildJWTValidatorIsNilWithoutAnIssuer(t *testing.T) {
+	v, err := buildJWTValidator(context.Background(), slog.New(slog.DiscardHandler), "", "brain")
+	require.NoError(t, err)
+	assert.Nil(t, v)
+}
+
+// With the issuer unresolved, a JWT on a REST route answers 503 (retry), not
+// 401: the token may be fine, the server just cannot check it yet.
+func TestBuildMuxAnswers503ToAJWTWhileTheIssuerIsUnresolved(t *testing.T) {
 	srv, _ := fakeIssuer(t, 1000)
-	ctx, cancel := context.WithCancel(context.Background())
-	slow := startupretry.Policy{Attempts: 8, Base: time.Hour, Max: time.Hour}
+	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, "GET", "/pending", "Bearer aaa.bbb.ccc")
+	assert.Equal(t, http.StatusServiceUnavailable, code)
+}
 
-	done := make(chan error, 1)
-	go func() {
-		_, err := buildJWTValidator(ctx, slog.New(slog.DiscardHandler), srv.URL, "brain", slow)
-		done <- err
-	}()
-	time.Sleep(50 * time.Millisecond)
-	cancel()
-	select {
-	case err := <-done:
-		assert.ErrorIs(t, err, context.Canceled)
-	case <-time.After(3 * time.Second):
-		t.Fatal("did not return after the context was cancelled")
-	}
+// 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

@@ -32,7 +32,6 @@ import (
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/reranker"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/search"
-	"github.com/mathiasbq/hyperguild/ingestion/internal/startupretry"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/symlinkguard"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/vectorstore"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/watcher"
@@ -369,21 +368,15 @@ func main() {
 	// hyperguild#157: report a symlink that appears in the brain while running.
 	go symlinkguard.Watch(ctx, brainDir, symlinkScanInterval(os.Getenv), buildNotifier())
 
-	// Built before the watcher, the graph backfill and session ingestion, and
-	// retried rather than fatal (#83). Two separate reasons:
-	//
-	//   - On a cold cluster boot this pod can beat dex to serving and gets a
-	//     502 from ingress. Nothing is misconfigured; it simply started first.
-	//     Exiting there meant CrashLoopBackOff redoing the backfill on every
-	//     attempt, with exponential backoff stretching the brain outage.
-	//   - Constructing it first means a genuine config error (wrong issuer,
-	//     bad audience) fails in seconds instead of after all that work.
-	//
-	// The budget stays bounded: retrying forever would turn a misconfiguration
-	// into a process that looks alive and never serves.
+	// Never fatal on an unreachable issuer (#83): on a cold cluster boot this
+	// pod can beat dex to serving and get a 502 from ingress, and exiting meant
+	// CrashLoopBackOff redoing the backfill. Since mcp-chassis v0.7 the
+	// validator resolves the issuer lazily and answers JWTs 503-and-retry until
+	// it does (hyperguild#155), so no boot retry is needed. A misconfigured
+	// issuer no longer exits the process: it is logged at boot and every JWT
+	// gets 503; the static bearer keeps working.
 	jwtValidator, err := buildJWTValidator(ctx, logger,
-		os.Getenv("DEX_ISSUER_URL"), os.Getenv("MCP_AUDIENCE"),
-		startupretry.Policy{Attempts: 8, Base: time.Second, Max: 30 * time.Second})
+		os.Getenv("DEX_ISSUER_URL"), os.Getenv("MCP_AUDIENCE"))
 	if err != nil {
 		logger.Error("build jwt validator", "err", err)
 		os.Exit(1)
@@ -523,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
@@ -548,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
@@ -590,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)
@@ -623,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
@@ -73,5 +87,23 @@ func mountREST(mux *http.ServeMux, h *api.Handler, auth func(http.Handler) http.
 	rest.HandleFunc("POST /promote", h.Promote)
 	rest.HandleFunc("POST /backfill-embeddings", h.BackfillEmbeddings)
 	rest.HandleFunc("GET /pass-rate", h.PassRate)
-	mux.Handle("/", auth(rest))
+	mux.Handle("/", labelRESTPattern(rest, auth(rest)))
+}
+
+// labelRESTPattern sets the request's Pattern to the REST route it addresses
+// before auth runs, so the metrics middleware (which reads Pattern from the
+// same *http.Request) labels a refused request by its route rather than by
+// the "/" mount (hyperguild#155). A refused request to a path no route
+// matches keeps "/", so for refused requests the label set stays bounded by
+// the registered routes. That bound does not hold for authenticated
+// requests: an unregistered path reaches the REST mux, which 404s with an
+// empty Pattern, and the metrics middleware falls back to the raw URL path
+// (hyperguild#185).
+func labelRESTPattern(rest *http.ServeMux, next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if _, pattern := rest.Handler(r); pattern != "" {
+			r.Pattern = pattern
+		}
+		next.ServeHTTP(w, r)
+	})
 }

ingestion/cmd/server/routes_observability_test.go

@@ -0,0 +1,88 @@
+package main
+
+import (
+	"bytes"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// wrongTokSentinel is a presented credential distinctive enough that any
+// occurrence in a log line is the raw token, not a coincidence.
+const wrongTokSentinel = "wrong-tok-sentinel-q7zx"
+
+// hyperguild#155: since #149 every REST route sits behind BearerMiddleware,
+// and chassis v0.2.0 refused without logging, so an unknown caller got
+// silent 401s. The chassis now writes an `mcp auth rejected` line, and the
+// presented token appears nowhere in the log as a bare value (PR #181
+// review: asserting on the "Bearer " header form could never fail, since
+// the chassis logs fields, not headers).
+func TestBuildMuxRejectionLogLineOmitsTheBarePresentedToken(t *testing.T) {
+	var buf bytes.Buffer
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(&buf, nil)))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+
+	code, _ := do(t, testMux(t), "POST", "/query", "Bearer "+wrongTokSentinel)
+	require.Equal(t, http.StatusUnauthorized, code)
+	assert.Contains(t, buf.String(), "mcp auth rejected")
+	assert.Contains(t, buf.String(), "path=/query")
+	assert.NotContains(t, buf.String(), wrongTokSentinel, "the rejected token is logged as a bare value")
+	assert.NotContains(t, buf.String(), routesTok, "the valid static token is logged")
+}
+
+// The `mcp auth accepted` line leaves out the valid static token.
+func TestBuildMuxAcceptedLogLineOmitsTheBareStaticToken(t *testing.T) {
+	var buf bytes.Buffer
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(&buf, nil)))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+
+	code, _ := do(t, testMux(t), "GET", "/pending", "Bearer "+routesTok)
+	require.Equal(t, http.StatusOK, code)
+	assert.Contains(t, buf.String(), "mcp auth accepted")
+	assert.NotContains(t, buf.String(), routesTok, "the accepted static token is logged as a bare value")
+}
+
+// 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) {
+	mux, reg := testMuxAndRegistry(t)
+	code, _ := do(t, mux, "GET", "/pending", "Bearer "+routesTok)
+	require.Equal(t, http.StatusOK, code)
+
+	rec := httptest.NewRecorder()
+	reg.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/metrics", nil))
+	assert.Contains(t, rec.Body.String(), `path="GET /pending"`)
+	assert.NotContains(t, rec.Body.String(), `path="/"`)
+}
+
+// hyperguild#155: a request refused by REST auth never reaches the REST mux,
+// 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) {
+	mux, reg := testMuxAndRegistry(t)
+	code, _ := do(t, mux, "POST", "/query", "")
+	require.Equal(t, http.StatusUnauthorized, code)
+
+	rec := httptest.NewRecorder()
+	reg.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/metrics", nil))
+	assert.Contains(t, rec.Body.String(), `path="POST /query",status="4xx"`)
+}
+
+// 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) {
+	mux, reg := testMuxAndRegistry(t)
+	code, _ := do(t, mux, "POST", "/no-such-route-zq", "")
+	require.Equal(t, http.StatusUnauthorized, code)
+
+	rec := httptest.NewRecorder()
+	reg.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/metrics", nil))
+	assert.Contains(t, rec.Body.String(), `path="/",status="4xx"`)
+	assert.NotContains(t, rec.Body.String(), "no-such-route-zq")
+}

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,34 @@ 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 := api.NewHandler(t.TempDir(), slog.New(slog.NewTextHandler(os.Stderr, nil)), pipeline.Config{})
+	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 {
+	t.Helper()
+	return api.NewHandler(t.TempDir(), slog.New(slog.NewTextHandler(os.Stderr, nil)), pipeline.Config{})
 }
 
 func do(t *testing.T, h http.Handler, method, path, authz string) (int, string) {
@@ -74,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 {
@@ -93,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/go.mod

@@ -51,7 +51,7 @@ require (
 )
 
 require (
-	git.d-ma.be/mathias/mcp-chassis v0.2.0
+	git.d-ma.be/mathias/mcp-chassis v0.7.1
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0 // indirect
 	github.com/goccy/go-json v0.10.3 // indirect
@@ -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/go.sum

@@ -1,5 +1,5 @@
-git.d-ma.be/mathias/mcp-chassis v0.2.0 h1:6fLmb7xqRa2nNVWsHaUbbfbArgDXJw/gDhb09clBIjo=
-git.d-ma.be/mathias/mcp-chassis v0.2.0/go.mod h1:Ks7EK2UnGAN0H3rJjKUxUagX8/ZBdtLrOlcUbv0RwH8=
+git.d-ma.be/mathias/mcp-chassis v0.7.1 h1:4h8TOBHTA0L/no4IPcr4tLcQtmKUlhE2/cXyPdNFGmM=
+git.d-ma.be/mathias/mcp-chassis v0.7.1/go.mod h1:Ks7EK2UnGAN0H3rJjKUxUagX8/ZBdtLrOlcUbv0RwH8=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=

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/brain/index.go

@@ -2,12 +2,18 @@ package brain
 
 import (
 	"bufio"
+	"bytes"
+	"errors"
 	"fmt"
+	"io"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"sort"
 	"strings"
 	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 )
 
 // noteEntry is one row in a Wing _index.md.
@@ -27,13 +33,18 @@ func BuildWingIndex(brainDir, wing string) error {
 		return fmt.Errorf("invalid wing %q", wing)
 	}
 	wingDir := filepath.Join(brainDir, "wiki", w)
-	if _, err := os.Stat(wingDir); os.IsNotExist(err) {
+	// Listed and read through the brain root (hyperguild#157): a wing or
+	// hall that is a symlink is not followed, and notes are regular files.
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	if _, err := bfs.Lstat("wiki/" + w); errors.Is(err, fs.ErrNotExist) {
 		return nil
-	} else if err != nil {
-		return fmt.Errorf("stat wing: %w", err)
 	}
 
-	entries, err := collectWingEntries(wingDir)
+	entries, err := collectWingEntries(bfs, "wiki/"+w)
 	if err != nil {
 		return err
 	}
@@ -58,51 +69,47 @@ func BuildWingIndex(brainDir, wing string) error {
 
 // BuildAllWingIndexes regenerates _index.md for every wing under brain/wiki/.
 func BuildAllWingIndexes(brainDir string) error {
-	wikiDir := filepath.Join(brainDir, "wiki")
-	ents, err := os.ReadDir(wikiDir)
-	if os.IsNotExist(err) {
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	wings, err := bfs.ReadDirDirs("wiki")
+	_ = bfs.Close()
+	if errors.Is(err, fs.ErrNotExist) {
 		return nil
 	}
 	if err != nil {
 		return fmt.Errorf("read wiki: %w", err)
 	}
-	for _, e := range ents {
-		if !e.IsDir() {
-			continue
-		}
-		if err := BuildWingIndex(brainDir, e.Name()); err != nil {
-			return fmt.Errorf("index %s: %w", e.Name(), err)
+	for _, w := range wings {
+		if err := BuildWingIndex(brainDir, w); err != nil {
+			return fmt.Errorf("index %s: %w", w, err)
 		}
 	}
 	return nil
 }
 
-func collectWingEntries(wingDir string) ([]noteEntry, error) {
+func collectWingEntries(bfs *brainfs.Brain, wingRel string) ([]noteEntry, error) {
 	var out []noteEntry
-	ents, err := os.ReadDir(wingDir)
+	halls, err := bfs.ReadDirDirs(wingRel)
 	if err != nil {
 		return nil, fmt.Errorf("read wing: %w", err)
 	}
-	for _, hallEnt := range ents {
-		if !hallEnt.IsDir() {
-			continue
-		}
-		hall := hallEnt.Name()
+	for _, hall := range halls {
 		if !IsValidHall(hall) {
 			continue
 		}
-		hallDir := filepath.Join(wingDir, hall)
-		notes, err := os.ReadDir(hallDir)
+		hallRel := wingRel + "/" + hall
+		names, err := bfs.ReadDirRegular(hallRel)
 		if err != nil {
 			return nil, fmt.Errorf("read hall %s: %w", hall, err)
 		}
-		for _, n := range notes {
-			if n.IsDir() || !strings.HasSuffix(n.Name(), ".md") || n.Name() == "_index.md" {
+		for _, name := range names {
+			if !strings.HasSuffix(name, ".md") || name == "_index.md" {
 				continue
 			}
-			slug := strings.TrimSuffix(n.Name(), ".md")
-			full := filepath.Join(hallDir, n.Name())
-			title, created := readTitleAndCreated(full, slug)
+			slug := strings.TrimSuffix(name, ".md")
+			title, created := readTitleAndCreatedIn(bfs, hallRel+"/"+name, slug)
 			out = append(out, noteEntry{Hall: hall, Slug: slug, Title: title, Created: created})
 		}
 	}
@@ -117,9 +124,40 @@ func readTitleAndCreated(path, slug string) (string, string) {
 		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
+}
 
-	title, created := "", ""
-	scanner := bufio.NewScanner(f)
+// readTitleAndCreatedIn is readTitleAndCreated through the brain root,
+// regular files only (hyperguild#157).
+func readTitleAndCreatedIn(bfs *brainfs.Brain, rel, slug string) (string, string) {
+	content, err := bfs.ReadRegular(rel)
+	if err != nil {
+		return slug, ""
+	}
+	title, created := parseTitleAndCreated(bytes.NewReader(content))
+	if created == "" {
+		if info, err := bfs.Lstat(rel); err == nil {
+			created = info.ModTime().UTC().Format("2006-01-02")
+		}
+	}
+	return titleOrSlug(title, slug), created
+}
+
+func titleOrSlug(title, slug string) string {
+	if title == "" {
+		return strings.ReplaceAll(slug, "-", " ")
+	}
+	return title
+}
+
+func parseTitleAndCreated(r io.Reader) (title, created string) {
+	scanner := bufio.NewScanner(r)
 	inFrontmatter := false
 	for scanner.Scan() {
 		line := scanner.Text()
@@ -149,13 +187,5 @@ func readTitleAndCreated(path, slug string) (string, string) {
 			}
 		}
 	}
-	if title == "" {
-		title = strings.ReplaceAll(slug, "-", " ")
-	}
-	if created == "" {
-		if info, err := os.Stat(path); err == nil {
-			created = info.ModTime().UTC().Format("2006-01-02")
-		}
-	}
 	return title, created
 }

ingestion/internal/brain/index_root_test.go

@@ -0,0 +1,132 @@
+package brain_test
+
+import (
+	"os"
+	"path/filepath"
+	"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"
+)
+
+func readIndex(t *testing.T, brainDir, wing string) string {
+	t.Helper()
+	b, _ := os.ReadFile(filepath.Join(brainDir, "wiki", wing, "_index.md"))
+	return string(b)
+}
+
+// hyperguild#157 slice 5: BuildWingIndex listed wiki/<wing>/<hall>/ with
+// os.ReadDir and opened each note by path, so a symlinked note put the
+// target's title into _index.md, and a FIFO hung the index build.
+func TestBuildWingIndexRefusesSymlinkedNotesAndSurvivesSwapRaces(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\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(facts, "leak.md")))
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(b, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md")))
+
+	require.NoError(t, brain.BuildWingIndex(b, "w"))
+	idx := readIndex(t, b, "w")
+	assert.Contains(t, idx, "zqinside", "positive control")
+	assert.NotContains(t, idx, brainfstest.Sentinel)
+	assert.NotContains(t, idx, "leak")
+	assert.NotContains(t, idx, "inlink")
+
+	p := filepath.Join(facts, "r.md")
+	read := func() string {
+		_ = brain.BuildWingIndex(b, "w")
+		return readIndex(t, b, "w")
+	}
+	brainfstest.AssertNoLeak(t, p, "---\ntitle: zqinside\n---\n", 1500*time.Millisecond, read)
+	brainfstest.AssertNoLeakFrom(t, p, "---\ntitle: zqinside\n---\n", inBrain, 1500*time.Millisecond, read)
+	brainfstest.AssertNoHang(t, p, "---\ntitle: zqinside\n---\n", 1500*time.Millisecond, 6*time.Second, func() { _ = read() })
+}
+
+// A symlinked hall is skipped while a real hall next to it is indexed; a
+// symlinked wing is refused and nothing is written into its target.
+func TestBuildWingIndexSkipsASymlinkedHallAndRefusesASymlinkedWing(t *testing.T) {
+	b := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "raw", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(b, "raw", "facts", "r.md"), []byte("---\ntitle: zqrawonly\n---\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "w", "decisions"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(b, "wiki", "w", "decisions", "d.md"), []byte("---\ntitle: zqrealhall\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "facts"), filepath.Join(b, "wiki", "w", "facts")))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(b, "wiki", "alias")))
+
+	require.NoError(t, brain.BuildWingIndex(b, "w"))
+	idx, err := os.ReadFile(filepath.Join(b, "wiki", "w", "_index.md"))
+	require.NoError(t, err, "the wing index is written")
+	assert.Contains(t, string(idx), "zqrealhall", "the real hall is indexed")
+	assert.NotContains(t, string(idx), "zqrawonly", "the symlinked hall is not")
+
+	assert.Error(t, brain.BuildWingIndex(b, "alias"))
+	_, err = os.Stat(filepath.Join(b, "raw", "_index.md"))
+	assert.True(t, os.IsNotExist(err), "an index was written into the symlinked wing's target")
+}
+
+// BuildAllWingIndexes indexes the real wings and skips a symlinked one.
+func TestBuildAllWingIndexesSkipsASymlinkedWing(t *testing.T) {
+	b := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "w", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(b, "wiki", "w", "facts", "n.md"), []byte("---\ntitle: zqrealwing\n---\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "raw", "facts"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(b, "wiki", "alias")))
+
+	require.NoError(t, brain.BuildAllWingIndexes(b))
+	idx, err := os.ReadFile(filepath.Join(b, "wiki", "w", "_index.md"))
+	require.NoError(t, err)
+	assert.Contains(t, string(idx), "zqrealwing")
+	_, err = os.Stat(filepath.Join(b, "raw", "_index.md"))
+	assert.True(t, os.IsNotExist(err))
+}
+
+// A link to a symlinked note does not resolve: only regular files count as
+// entries, so StripUnresolvedLinks unwraps it.
+func TestStripUnresolvedLinksDoesNotCountASymlinkedNoteAsAnEntry(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, "real.md"), []byte("x"), 0o644))
+	brainfstest.WriteSentinelAt(t, filepath.Join(b, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "ghost.md")))
+	out, unlinked, err := brain.StripUnresolvedLinks(b, "see [[real]] and [[ghost]]")
+	require.NoError(t, err)
+	assert.Contains(t, out, "[[real]]", "positive control")
+	assert.NotContains(t, out, "[[ghost]]")
+	assert.Contains(t, unlinked, "ghost")
+}
+
+// A linked tree (knowledge/ or wiki/) that is not a real directory is
+// skipped, not an error: StripUnresolvedLinks runs before every brain_write,
+// and an error there loses the learning.
+func TestStripUnresolvedLinksSkipsALinkedTreeThatIsNotARealDirectory(t *testing.T) {
+	for name, mk := range map[string]func(t *testing.T, b string){
+		"symlink to an in-brain dir": func(t *testing.T, b string) {
+			require.NoError(t, os.MkdirAll(filepath.Join(b, "raw", "k"), 0o755))
+			require.NoError(t, os.Symlink(filepath.Join("raw", "k"), filepath.Join(b, "knowledge")))
+		},
+		"dangling symlink": func(t *testing.T, b string) {
+			require.NoError(t, os.Symlink("nowhere", filepath.Join(b, "knowledge")))
+		},
+		"regular file": func(t *testing.T, b string) {
+			require.NoError(t, os.WriteFile(filepath.Join(b, "knowledge"), []byte("x"), 0o644))
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			b := t.TempDir()
+			require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "w", "facts"), 0o755))
+			require.NoError(t, os.WriteFile(filepath.Join(b, "wiki", "w", "facts", "real.md"), []byte("x"), 0o644))
+			mk(t, b)
+			out, _, err := brain.StripUnresolvedLinks(b, "learning [[real]] and [[gone]]")
+			require.NoError(t, err)
+			assert.Contains(t, out, "[[real]]", "links into wiki/ still resolve")
+			assert.NotContains(t, out, "[[gone]]")
+		})
+	}
+}

ingestion/internal/brain/linkcheck.go

@@ -1,12 +1,16 @@
 package brain
 
 import (
+	"errors"
 	"fmt"
-	"os"
-	"path/filepath"
+	"io/fs"
+	"log/slog"
+	"path"
 	"regexp"
 	"sort"
 	"strings"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 )
 
 // wikilinkRE matches [[target]] and [[target|Display Text]].
@@ -98,29 +102,40 @@ var linkedTrees = []string{"knowledge", "wiki"}
 // one the audit will also resolve.
 func entryIndex(brainDir string) (map[string]struct{}, error) {
 	index := map[string]struct{}{}
+	// Walked through the brain root (hyperguild#157): only regular files
+	// count as entries, so a symlinked .md name cannot make a link resolve.
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return nil, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
 	for _, dir := range linkedTrees {
-		root := filepath.Join(brainDir, dir)
-		if _, err := os.Stat(root); os.IsNotExist(err) {
+		if _, err := bfs.Lstat(dir); errors.Is(err, fs.ErrNotExist) {
 			continue
-		} else if err != nil {
-			return nil, fmt.Errorf("stat %s: %w", dir, err)
 		}
-		err := filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
-			if err != nil {
-				return err
-			}
-			if d.IsDir() || !strings.HasSuffix(path, ".md") {
+		var walkErr error
+		err := bfs.WalkRegular(dir, func(rel string) error {
+			if !strings.HasSuffix(rel, ".md") {
 				return nil
 			}
-			rel, err := filepath.Rel(brainDir, path)
-			if err != nil {
-				return err
-			}
-			rel = filepath.ToSlash(rel)
-			index[strings.TrimSuffix(filepath.Base(rel), ".md")] = struct{}{}
+			index[strings.TrimSuffix(path.Base(rel), ".md")] = struct{}{}
 			index[strings.TrimPrefix(strings.TrimSuffix(rel, ".md"), "wiki/")] = struct{}{}
 			return nil
+		}, func(rel string, err error) {
+			// A linked tree that is not a real directory (a symlink, a
+			// file) is skipped, as filepath.WalkDir did: this runs before
+			// every brain_write, and an error here loses the learning.
+			if rel == dir && errors.Is(err, brainfs.ErrNotRegular) {
+				slog.Warn("link check: skipping a linked tree that is not a real directory", "dir", dir)
+				return
+			}
+			if walkErr == nil {
+				walkErr = fmt.Errorf("%s: %w", rel, err)
+			}
 		})
+		if err == nil {
+			err = walkErr
+		}
 		if err != nil {
 			return nil, fmt.Errorf("walk %s: %w", dir, err)
 		}

ingestion/internal/brain/tunnel.go

@@ -4,9 +4,12 @@ import (
 	"bufio"
 	"fmt"
 	"os"
+	"path"
 	"path/filepath"
 	"strings"
 	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 )
 
 // seeAlsoHeader is the markdown heading used to group cross-wing links.
@@ -197,6 +200,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 +218,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 +287,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 +302,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 +328,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,9 +104,47 @@ 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.
+func (b *Brain) ReadDirDirs(relDir string) ([]string, error) {
+	relDir = filepath.ToSlash(relDir)
+	if err := b.realDir(relDir); err != nil {
+		return nil, err
+	}
+	ents, err := fs.ReadDir(b.root.FS(), relDir)
+	if err != nil {
+		return nil, err
+	}
+	var names []string
+	for _, e := range ents {
+		if e.Type().IsDir() {
+			names = append(names, e.Name())
+		}
+	}
+	return names, nil
+}
+
 // ReadRegular reads a brain-relative path, refusing anything that is not a
 // regular file, both before the open and on the opened handle.
 func (b *Brain) ReadRegular(rel string) ([]byte, error) {
+	if err := cleanRel(rel); err != nil {
+		return nil, err
+	}
+	if err := b.realDir(path.Dir(rel)); err != nil {
+		return nil, err
+	}
 	fi, err := b.root.Lstat(rel)
 	if err != nil {
 		return nil, err
@@ -133,6 +171,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
@@ -228,3 +272,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

@@ -262,3 +262,117 @@ func TestReadRegularNeverReturnsAnInBrainFileSwappedInBehindASymlink(t *testing.
 	assert.Zero(t, leaks)
 	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))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "other"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "other"), filepath.Join(dir, "a", "linked")))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "a", "f.md"), []byte("f"), 0o644))
+	require.NoError(t, os.Symlink("a", filepath.Join(dir, "alias")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	names, err := b.ReadDirDirs("a")
+	require.NoError(t, err)
+	assert.Equal(t, []string{"real"}, names)
+	_, 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

@@ -27,7 +27,7 @@ const outsideContent = "---\ntitle: " + Sentinel + "\naliases:\n  - " + Sentinel
 	"\n\n" + Sentinel + " [[" + Sentinel + "]]\n"
 
 // Outside writes a file outside any brain dir containing Sentinel.
-func Outside(t *testing.T) string {
+func Outside(t testing.TB) string {
 	t.Helper()
 	p := filepath.Join(t.TempDir(), "secret.md")
 	if err := os.WriteFile(p, []byte(outsideContent), 0o644); err != nil {
@@ -42,9 +42,12 @@ var swapSeq atomic.Int64
 // a symlink to outside or a FIFO into path, until the test ends. FIFOs get a
 // writer held open until the swapper exits, so a reader that skips the
 // handle check parks forever instead of reading EOF. The swapper is stopped
-// and awaited before t.TempDir cleanup.
-func StartSwap(t *testing.T, path, inside, outside string, fifo bool) {
+// and awaited before t.TempDir cleanup. It returns the number of symlinks
+// or FIFOs actually renamed into path so far, so a caller can tell a race
+// that ran from one whose every swap failed (hyperguild#177).
+func StartSwap(t testing.TB, path, inside, outside string, fifo bool) *atomic.Int64 {
 	t.Helper()
+	var swaps atomic.Int64
 	var stop atomic.Bool
 	var wg sync.WaitGroup
 	wg.Add(1)
@@ -67,22 +70,26 @@ func StartSwap(t *testing.T, path, inside, outside string, fifo bool) {
 		}()
 		for i := 0; !stop.Load(); i++ {
 			_ = os.Remove(tmp)
+			var made error
 			switch {
 			case i%2 == 0:
 				_ = os.WriteFile(tmp, []byte(inside), 0o644)
 			case fifo:
-				if err := syscall.Mkfifo(tmp, 0o644); err == nil {
+				if made = syscall.Mkfifo(tmp, 0o644); made == nil {
 					if w, err := os.OpenFile(tmp, os.O_RDWR, 0); err == nil {
 						writers = append(writers, w)
 					}
 				}
 			default:
-				_ = os.Symlink(link, tmp)
+				made = os.Symlink(link, tmp)
+			}
+			if err := os.Rename(tmp, path); err == nil && made == nil && i%2 == 1 {
+				swaps.Add(1)
 			}
-			_ = os.Rename(tmp, path)
 		}
 	}()
 	t.Cleanup(func() { stop.Store(true); wg.Wait() })
+	return &swaps
 }
 
 // WriteSentinelAt writes a file carrying Sentinel at p (creating its
@@ -107,18 +114,41 @@ func AssertNoLeak(t *testing.T, path, inside string, d time.Duration, read func(
 	AssertNoLeakFrom(t, path, inside, Outside(t), d, read)
 }
 
+// InsideMarker must appear in the inside note's content and in read's
+// output whenever read saw that note: the floor below counts such reads.
+const InsideMarker = "inside"
+
 // AssertNoLeakFrom is AssertNoLeak with the symlink pointing at target, e.g.
 // a file elsewhere in the brain written with WriteSentinelAt.
-func AssertNoLeakFrom(t *testing.T, path, inside, target string, d time.Duration, read func() string) {
+//
+// Beyond "no Sentinel in any output" it sets two floors, because without
+// them the assertion passes when nothing was tested (hyperguild#177): at
+// least one symlink must have been swapped into path, and at least one read
+// must have returned InsideMarker (a reader that always errors returns
+// nothing, and so never leaks).
+func AssertNoLeakFrom(t testing.TB, path, inside, target string, d time.Duration, read func() string) {
 	t.Helper()
-	StartSwap(t, path, inside, target, false)
-	leaks, iters := 0, 0
+	if !strings.Contains(inside, InsideMarker) {
+		t.Fatalf("inside content must contain %q", InsideMarker)
+	}
+	swaps := StartSwap(t, path, inside, target, false)
+	leaks, iters, insideReads := 0, 0, 0
 	for deadline := time.Now().Add(d); time.Now().Before(deadline); iters++ {
-		leaks += strings.Count(read(), Sentinel)
+		out := read()
+		leaks += strings.Count(out, Sentinel)
+		if strings.Contains(out, InsideMarker) {
+			insideReads++
+		}
 	}
 	if leaks > 0 {
 		t.Fatalf("outside file leaked %d times in %d iterations", 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)
+	}
+	if insideReads == 0 {
+		t.Fatalf("no read in %d iterations returned the inside note (%q): the reader read nothing", iters, InsideMarker)
+	}
 }
 
 // AssertNoHang loops read for d while a FIFO swapper (held writers) runs on

ingestion/internal/brainfs/brainfstest/brainfstest_test.go

@@ -0,0 +1,79 @@
+package brainfstest
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"syscall"
+	"testing"
+	"time"
+)
+
+// recordingTB stands in for the test under AssertNoLeakFrom so a fatal
+// there can be observed instead of failing this test. Fatalf ends the
+// calling goroutine the way testing.T does.
+type recordingTB struct {
+	testing.TB
+	failed bool
+	msg    string
+}
+
+func (r *recordingTB) Fatalf(format string, args ...any) {
+	r.failed, r.msg = true, fmt.Sprintf(format, args...)
+	runtime.Goexit()
+}
+
+func runAssert(t *testing.T, path, target string, read func() string) *recordingTB {
+	t.Helper()
+	r := &recordingTB{TB: t}
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		AssertNoLeakFrom(r, path, "inside", target, 200*time.Millisecond, read)
+	}()
+	<-done
+	return r
+}
+
+// hyperguild#177: with every swap failing, no leak can occur, so the leak
+// assertion passed without testing anything.
+func TestAssertNoLeakFromFailsWhenNoSymlinkSwapSucceeds(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "missing-dir", "r.md")
+	r := runAssert(t, path, Outside(t), func() string { return "inside" })
+	if !r.failed {
+		t.Fatal("AssertNoLeakFrom passed with zero successful symlink swaps")
+	}
+}
+
+// hyperguild#177: a reader that always errors returns nothing, so it never
+// leaks either.
+func TestAssertNoLeakFromFailsWhenNoReadReturnsTheInsideNote(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "r.md")
+	r := runAssert(t, path, Outside(t), func() string { return "" })
+	if !r.failed {
+		t.Fatal("AssertNoLeakFrom passed with zero reads returning the inside note")
+	}
+}
+
+// Positive control: a reader that refuses symlinks and reads regular files
+// passes, so the floors do not fail a working reader.
+func TestAssertNoLeakFromPassesAReaderThatRefusesSymlinks(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "r.md")
+	read := func() string {
+		f, err := os.OpenFile(path, os.O_RDONLY|noFollow, 0)
+		if err != nil {
+			return ""
+		}
+		defer func() { _ = f.Close() }()
+		b := make([]byte, 64)
+		n, _ := f.Read(b)
+		return string(b[:n])
+	}
+	r := runAssert(t, path, Outside(t), read)
+	if r.failed {
+		t.Fatalf("a symlink-refusing reader failed: %s", r.msg)
+	}
+}
+
+const noFollow = syscall.O_NOFOLLOW

ingestion/internal/search/brainroot_test.go

@@ -93,16 +93,20 @@ func TestQueryDoesNotFollowASymlinkedWingUnderAWingAndHallRoot(t *testing.T) {
 // bypass of readOpened hung Query after 5 iterations).
 // startSwap runs swapInto until the test ends and waits for it before
 // t.TempDir's cleanup (hyperguild#162).
-func startSwap(t *testing.T, path, outside string, fifo bool) {
+// It returns the count of symlinks or FIFOs actually renamed into path
+// (hyperguild#177: a swapper whose every swap fails tests nothing).
+func startSwap(t *testing.T, path, outside string, fifo bool) *atomic.Int64 {
 	t.Helper()
 	var stop atomic.Bool
+	var swaps atomic.Int64
 	var wg sync.WaitGroup
 	wg.Add(1)
-	go func() { defer wg.Done(); swapInto(path, outside, fifo, &stop) }()
+	go func() { defer wg.Done(); swapInto(path, outside, fifo, &stop, &swaps) }()
 	t.Cleanup(func() { stop.Store(true); wg.Wait() })
+	return &swaps
 }
 
-func swapInto(path, outside string, fifo bool, stop *atomic.Bool) {
+func swapInto(path, outside string, fifo bool, stop *atomic.Bool, swaps *atomic.Int64) {
 	tmp := path + ".swap"
 	// Writers stay open until the swapper exits, so a reader parked on a
 	// FIFO stays parked (closing one would hand the reader EOF and hide the
@@ -115,33 +119,46 @@ func swapInto(path, outside string, fifo bool, stop *atomic.Bool) {
 	}()
 	for i := 0; !stop.Load(); i++ {
 		_ = os.Remove(tmp)
+		var made error
 		switch {
 		case i%2 == 0:
 			_ = os.WriteFile(tmp, []byte("# r\n\nzqinside "+"zqracenote"), 0o644)
 		case fifo:
-			if err := syscall.Mkfifo(tmp, 0o644); err == nil {
+			if made = syscall.Mkfifo(tmp, 0o644); made == nil {
 				if w, err := os.OpenFile(tmp, os.O_RDWR, 0); err == nil {
 					writers = append(writers, w)
 				}
 			}
 		default:
-			_ = os.Symlink(outside, tmp)
+			made = os.Symlink(outside, tmp)
+		}
+		if err := os.Rename(tmp, path); err == nil && made == nil && i%2 == 1 {
+			swaps.Add(1)
 		}
-		_ = os.Rename(tmp, path)
 	}
 }
 
 func TestQueryLeaksNothingUnderASymlinkSwapRace(t *testing.T) {
 	brain, facts, outside := searchBrain(t)
-	startSwap(t, filepath.Join(facts, "r.md"), outside, false)
-	leaks, iters := 0, 0
+	swaps := startSwap(t, filepath.Join(facts, "r.md"), outside, false)
+	leaks, iters, insideReads := 0, 0, 0
 	for deadline := time.Now().Add(1500 * time.Millisecond); time.Now().Before(deadline); iters++ {
-		rs, _ := Query(brain, QueryOptions{Query: sentinel157, Limit: 10})
+		rs, err := Query(brain, QueryOptions{Query: sentinel157, Limit: 10})
+		require.NoError(t, err)
 		leaks += leaked(rs)
+		// Positive control (hyperguild#177): a Query that always errors
+		// returns nothing and so never leaks.
+		rs, err = Query(brain, QueryOptions{Query: "zqracenote", Limit: 10})
+		require.NoError(t, err)
+		if len(rs) > 0 {
+			insideReads++
+		}
 	}
 	if leaks > 0 {
 		t.Fatalf("outside file leaked %d times in %d iterations", leaks, iters)
 	}
+	require.Positive(t, swaps.Load(), "no symlink was swapped in: the race did not run")
+	require.Positive(t, insideReads, "no Query returned the inside note")
 }
 
 func TestQueryDoesNotHangUnderAFIFOSwapRace(t *testing.T) {

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

@@ -1,75 +0,0 @@
-// Package startupretry retries a startup dependency that may not be serving
-// yet, instead of exiting on its first failure.
-//
-// It exists for the cold-boot ordering race (#83): on a cluster restart the
-// ingestion pod can reach OIDC discovery before dex is answering, gets a 502
-// from ingress, and dies — after having already connected postgres, backfilled
-// the graph and ingested session batches, all of which the restart redoes.
-// Nothing is misconfigured in that scenario; the pod simply started first.
-//
-// The budget is bounded on purpose. Retrying forever would turn a genuine
-// misconfiguration (wrong issuer URL, bad audience) into a process that looks
-// healthy and never serves, which is harder to diagnose than a crash loop.
-package startupretry
-
-import (
-	"context"
-	"fmt"
-	"time"
-)
-
-// Policy bounds the retry: at most Attempts calls, with the delay doubling
-// from Base and capped at Max.
-type Policy struct {
-	Attempts int           // total calls, including the first; < 1 means 1
-	Base     time.Duration // delay before the second attempt
-	Max      time.Duration // ceiling for the doubling delay
-}
-
-// Do calls fn until it succeeds, the attempt budget is spent, or ctx ends.
-//
-// The returned error wraps the last failure, so callers keep the diagnosis
-// they would have had without the retry.
-func Do[T any](ctx context.Context, p Policy, fn func(context.Context) (T, error)) (T, error) {
-	var zero T
-
-	attempts := p.Attempts
-	if attempts < 1 {
-		attempts = 1
-	}
-
-	delay := p.Base
-	var lastErr error
-
-	for i := range attempts {
-		if err := ctx.Err(); err != nil {
-			return zero, fmt.Errorf("startupretry: %w", err)
-		}
-
-		v, err := fn(ctx)
-		if err == nil {
-			return v, nil
-		}
-		lastErr = err
-
-		if i == attempts-1 {
-			break
-		}
-
-		if delay <= 0 {
-			delay = time.Second
-		}
-		if p.Max > 0 && delay > p.Max {
-			delay = p.Max
-		}
-
-		select {
-		case <-ctx.Done():
-			return zero, fmt.Errorf("startupretry: %w", ctx.Err())
-		case <-time.After(delay):
-		}
-		delay *= 2
-	}
-
-	return zero, fmt.Errorf("startupretry: gave up after %d attempts: %w", attempts, lastErr)
-}

ingestion/internal/startupretry/startupretry_test.go

@@ -1,142 +0,0 @@
-// ingestion/internal/startupretry/startupretry_test.go
-package startupretry
-
-import (
-	"context"
-	"errors"
-	"testing"
-	"time"
-)
-
-func fastPolicy(attempts int) Policy {
-	return Policy{Attempts: attempts, Base: time.Millisecond, Max: 2 * time.Millisecond}
-}
-
-func TestDo_ReturnsImmediatelyOnFirstSuccess(t *testing.T) {
-	calls := 0
-	got, err := Do(context.Background(), fastPolicy(5), func(context.Context) (string, error) {
-		calls++
-		return "ready", nil
-	})
-	if err != nil {
-		t.Fatalf("Do: %v", err)
-	}
-	if got != "ready" {
-		t.Errorf("got %q, want %q", got, "ready")
-	}
-	if calls != 1 {
-		t.Errorf("calls = %d, want 1", calls)
-	}
-}
-
-func TestDo_SurvivesTransientFailuresThenSucceeds(t *testing.T) {
-	// The observed cold-boot race: dex is not serving yet, ingress answers
-	// 502 for the first few attempts, then discovery works.
-	calls := 0
-	got, err := Do(context.Background(), fastPolicy(5), func(context.Context) (string, error) {
-		calls++
-		if calls < 4 {
-			return "", errors.New("oidc discovery: status 502")
-		}
-		return "ready", nil
-	})
-	if err != nil {
-		t.Fatalf("Do returned %v — a transient 502 must not be fatal", err)
-	}
-	if got != "ready" {
-		t.Errorf("got %q, want %q", got, "ready")
-	}
-	if calls != 4 {
-		t.Errorf("calls = %d, want 4", calls)
-	}
-}
-
-func TestDo_GivesUpAfterTheAttemptBudgetAndReportsTheLastError(t *testing.T) {
-	// A genuinely broken issuer must still fail — retrying forever would turn
-	// a config error into a silent hang, which is worse than crash-looping.
-	last := errors.New("oidc discovery: status 404")
-	calls := 0
-
-	_, err := Do(context.Background(), fastPolicy(3), func(context.Context) (string, error) {
-		calls++
-		return "", last
-	})
-
-	if !errors.Is(err, last) {
-		t.Fatalf("err = %v, want it to wrap the last failure", err)
-	}
-	if calls != 3 {
-		t.Errorf("calls = %d, want 3 (the attempt budget)", calls)
-	}
-}
-
-func TestDo_StopsPromptlyWhenTheContextIsCancelled(t *testing.T) {
-	ctx, cancel := context.WithCancel(context.Background())
-	calls := 0
-
-	done := make(chan struct{})
-	var err error
-	go func() {
-		defer close(done)
-		_, err = Do(ctx, Policy{Attempts: 100, Base: 50 * time.Millisecond, Max: time.Second},
-			func(context.Context) (string, error) {
-				calls++
-				if calls == 1 {
-					cancel()
-				}
-				return "", errors.New("still down")
-			})
-	}()
-
-	select {
-	case <-done:
-	case <-time.After(2 * time.Second):
-		t.Fatal("Do did not return after context cancellation")
-	}
-	if !errors.Is(err, context.Canceled) {
-		t.Errorf("err = %v, want context.Canceled", err)
-	}
-}
-
-func TestDo_BacksOffAndIsCappedByMax(t *testing.T) {
-	var delays []time.Duration
-	p := Policy{Attempts: 5, Base: 10 * time.Millisecond, Max: 25 * time.Millisecond}
-
-	last := time.Now()
-	_, _ = Do(context.Background(), p, func(context.Context) (string, error) {
-		now := time.Now()
-		delays = append(delays, now.Sub(last))
-		last = now
-		return "", errors.New("down")
-	})
-
-	// delays[0] is the first call (no wait); the rest are the sleeps.
-	if len(delays) != 5 {
-		t.Fatalf("attempts = %d, want 5", len(delays))
-	}
-	if delays[1] >= delays[2] {
-		t.Errorf("backoff is not growing: %v then %v", delays[1], delays[2])
-	}
-	for i, d := range delays[1:] {
-		if d > 2*p.Max {
-			t.Errorf("delay %d = %v, exceeds the Max cap %v with slack", i+1, d, p.Max)
-		}
-	}
-}
-
-func TestPolicy_ZeroValueStillMakesOneAttempt(t *testing.T) {
-	// A caller that forgets to configure the policy must not silently get a
-	// no-op that returns a nil validator and a nil error.
-	calls := 0
-	_, err := Do(context.Background(), Policy{}, func(context.Context) (string, error) {
-		calls++
-		return "", errors.New("down")
-	})
-
-	if calls != 1 {
-		t.Errorf("calls = %d, want 1", calls)
-	}
-	if err == nil {
-		t.Error("err = nil, want the failure surfaced")
-	}
-}

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
 
@@ -133,13 +138,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 {
@@ -168,7 +192,76 @@ func Watch(ctx context.Context, brainDir string, interval time.Duration, n Notif
 					". Readers may follow symlinks out of the brain; fix 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)
+		}
 	}
 }
 

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)")
+}