test(tunnel): pin the raced read, the walk error and the _index.md skip (#174)

Review round 1 on PR #186:

- The swap test's static note had the same title as the raced note, so
  the harness's "inside was read" floor passed without reading r.md
  (skipping r.md stayed green). The static note now has its own title.
- An unreadable directory under wiki/ reaches the walk-error path, and
  swallowing that error stayed green. New test asserts the error.
- The FIFO test now runs with and without a writer held open.
- _index.md skip had no test; new test.
- index.go: the double blank line left by removing readTitleAndCreated.

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

ingestion/cmd/server/jwt_validator_test.go

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

ingestion/cmd/server/main.go

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

ingestion/cmd/server/routes.go

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

ingestion/cmd/server/routes_observability_test.go

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

ingestion/cmd/server/routes_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/metrics"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 )
 
@@ -21,20 +22,29 @@ func okHandler(body string) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { _, _ = w.Write([]byte(body)) })
 }
 
-// testMux builds the router exactly as main does: buildMux with the full
+// testMux builds the router through buildMux, the function main calls, with
-// public set main registers (stub handlers) and real bearer config.
+// every allowlisted public pattern (stub handlers), a stub MCP server and a
-// hyperguild#149: the REST API is authenticated as a whole; the PR #152
+// static token only: no JWT validator and no resourceMetadataURL (the tests
-// review showed a test of a COPY of the router let main.go regress unseen.
+// in jwt_validator_test.go pass those). It does not use main's own restAuth
+// or public map (hyperguild#182). hyperguild#149: the REST API is
+// authenticated as a whole; the PR #152 review showed a test of a COPY of
+// the router let main.go regress unseen.
 func testMux(t *testing.T) http.Handler {
 	t.Helper()
-	h := testHandler(t)
+	mux, _ := testMuxAndRegistry(t)
+	return mux
+}
+
+func testMuxAndRegistry(t *testing.T) (http.Handler, *metrics.Registry) {
+	t.Helper()
 	public := map[string]http.Handler{}
 	for p := range publicRoutes {
 		public[p] = okHandler("public " + p)
 	}
-	mux, err := buildMux(restAuth{token: routesTok, realm: "brain"}, h, public)
+	reg := metrics.New()
+	mux, err := buildMux(restAuth{token: routesTok, realm: "brain"}, testHandler(t), okHandler("mcp"), reg, public)
 	require.NoError(t, err)
-	return mux
+	return mux, reg
 }
 
 func testHandler(t *testing.T) *api.Handler {
@@ -79,8 +89,9 @@ func TestBuildMuxAuthenticatesAnUnregisteredPath(t *testing.T) {
 }
 
 // buildMux registers public handlers as given, without adding auth: each
-// public route owns its own (bearer on /mcp, HMAC on the webhook, client
+// public route owns its own (bearer/JWT on /capture, HMAC on the webhook,
-// secret on /oauth/token) or is meant to be open (/metrics, OAuth metadata).
+// client secret on /oauth/token) or is meant to be open (OAuth metadata).
+// /mcp and /metrics are not public routes: buildMux builds them itself.
 func TestBuildMuxDoesNotWrapPublicRoutes(t *testing.T) {
 	r := testMux(t)
 	for p := range publicRoutes {
@@ -98,14 +109,53 @@ func TestBuildMuxDoesNotWrapPublicRoutes(t *testing.T) {
 // over the authenticated catch-all (more specific pattern), so it is refused.
 func TestBuildMuxRefusesAPublicPatternOffTheAllowlist(t *testing.T) {
 	h := api.NewHandler(t.TempDir(), slog.New(slog.NewTextHandler(os.Stderr, nil)), pipeline.Config{})
-	for _, p := range []string{"POST /query", "GET /pending", "/", "POST /metrics"} {
+	// "/mcp" and "GET /metrics" are built by buildMux itself (hyperguild#154):
-		_, err := buildMux(restAuth{token: routesTok, realm: "brain"}, h, map[string]http.Handler{p: okHandler("x")})
+	// 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/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
 	}
-
+	rel = t.Rel
-	prior, err := os.ReadFile(abs)
+	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_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/detect_root_test.go

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

ingestion/internal/brain/index.go

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

ingestion/internal/brain/tunnel.go

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

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

@@ -249,3 +249,41 @@ 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. Intermediate in-brain symlinks are still followed (os.Root keeps
+// the write inside the brain; hyperguild#167).
+func (b *Brain) WriteRegular(rel string, data []byte) error {
+	rel = filepath.ToSlash(rel)
+	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

@@ -263,6 +263,52 @@ func TestReadRegularNeverReturnsAnInBrainFileSwappedInBehindASymlink(t *testing.
 	assert.Positive(t, ok, "positive control: the regular file is read")
 }
 
+func TestWriteRegularRefusesFinalSymlinksFIFOsEscapesAndMissingFilesAndRewritesRegularFiles(t *testing.T) {
+	dir := t.TempDir()
+	outside := filepath.Join(t.TempDir(), "o.md")
+	require.NoError(t, os.WriteFile(outside, []byte("untouched"), 0o644))
+	require.NoError(t, os.Symlink(outside, filepath.Join(dir, "l.md")))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(dir, "f.md"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "n.md"), []byte("old content"), 0o644))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	assert.Error(t, b.WriteRegular("l.md", []byte("x")))
+	got, _ := os.ReadFile(outside)
+	assert.Equal(t, "untouched", string(got))
+
+	// A symlink to another file inside the brain: os.Root would allow it,
+	// only O_NOFOLLOW refuses it.
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "in.md"), []byte("inside"), 0o644))
+	require.NoError(t, os.Symlink("in.md", filepath.Join(dir, "il.md")))
+	assert.Error(t, b.WriteRegular("il.md", []byte("x")))
+	got, _ = os.ReadFile(filepath.Join(dir, "in.md"))
+	assert.Equal(t, "inside", string(got))
+
+	// A reader held open, so a non-blocking write open would succeed. The
+	// Lstat type check refuses the FIFO first; the handle check and
+	// O_NONBLOCK matter only if it is swapped in after the Lstat.
+	r, err := os.OpenFile(filepath.Join(dir, "f.md"), os.O_RDONLY|syscall.O_NONBLOCK, 0)
+	require.NoError(t, err)
+	defer func() { _ = r.Close() }()
+	done := make(chan error, 1)
+	go func() { done <- b.WriteRegular("f.md", []byte("x")) }()
+	select {
+	case err := <-done:
+		assert.Error(t, err)
+	case <-time.After(3 * time.Second):
+		t.Fatal("WriteRegular hung on a FIFO")
+	}
+
+	assert.Error(t, b.WriteRegular("../"+filepath.Base(filepath.Dir(outside))+"/o.md", []byte("x")))
+	assert.Error(t, b.WriteRegular("missing.md", []byte("x")), "does not create files")
+
+	require.NoError(t, b.WriteRegular("n.md", []byte("new")))
+	got, _ = os.ReadFile(filepath.Join(dir, "n.md"))
+	assert.Equal(t, "new", string(got), "truncated and rewritten")
+}
+
 func TestReadDirDirsListsOnlyRealSubdirsAndRefusesSymlinkedComponents(t *testing.T) {
 	dir := t.TempDir()
 	require.NoError(t, os.MkdirAll(filepath.Join(dir, "a", "real"), 0o755))

ingestion/internal/session/id_test.go

@@ -0,0 +1,92 @@
+package session
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// 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")
+	}
+}

ingestion/internal/session/session.go

@@ -9,6 +9,8 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"regexp"
+	"syscall"
 	"time"
 )
 
@@ -42,13 +44,32 @@ 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 := checkID(sessionID); err != nil {
+		return err
+	}
 	if err := os.MkdirAll(sessionsDir, 0o755); err != nil {
 		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)
+	f, err := os.OpenFile(path, 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)
 	}
@@ -70,6 +91,9 @@ func Append(sessionsDir, sessionID string, entry Entry) error {
 
 // Read returns all entries for sessionID. Returns empty slice if no log exists.
 func Read(sessionsDir, sessionID string) ([]Entry, error) {
+	if err := checkID(sessionID); err != nil {
+		return nil, err
+	}
 	path := filepath.Join(sessionsDir, sessionID+".jsonl")
 	f, err := os.Open(path)
 	if errors.Is(err, fs.ErrNotExist) {

ingestion/internal/symlinkguard/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)")
+}