fix(ingestion): close the PR #159 review findings on the symlink tripwire

- Startup passed on ANY scan error: WalkDir stopped at the first
  unreadable dir and Scan discarded what it had found, while search
  kept walking and served a planted symlink. Scan now records
  unreadable dirs and keeps going; startup refuses on symlinks or
  unreadable dirs and only lets a missing brain dir pass.
- Watch went silent while a scan error persisted, and marked a set as
  reported before Notify, so an ntfy outage lost the alert. It now
  alerts on unreadable dirs and scan errors too, and records a set as
  reported only after Notify succeeds (retried each tick).
- Only the root .git is skipped; a nested .git is scanned.
- A non-positive BRAIN_SYMLINK_SCAN_INTERVAL fell into time.NewTicker
  and crashlooped the server; it now falls back to the default.
- Findings are quoted in alerts, so a newline in a name cannot merge
  two sets; alertingWarnings names the tripwire when ntfy is unset.
- Test names match what they assert (two-set dedupe, symlinked entries
  inside a symlinked root, nested .git).

Flipped: startup ignoring unreadable dirs, .git skipped at any depth,
and no retry each turn a test red. Watch tests stable over -count=10
and under -race.

Refs #157

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

ingestion/internal/symlinkguard/symlinkguard.go

@@ -2,9 +2,9 @@
 // a Syncthing sendreceive folder and Syncthing syncs symlinks; several brain
 // readers (search, vectorstore, context, graph) follow a symlink out of the
 // brain and would index or return whatever it points to. Until every reader
-// reads through an os.Root, any symlink inside the brain is treated as an
-// incident: the server refuses to start on one (main), and Watch reports one
-// that appears while it runs.
+// reads through an os.Root, a symlink inside the brain, or a directory the
+// scan cannot read (which could hide one), is an incident: the server refuses
+// to start on one (main), and Watch reports one that appears while it runs.
 package symlinkguard
 
 import (
@@ -15,77 +15,131 @@ import (
 	"os"
 	"path/filepath"
 	"sort"
+	"strconv"
 	"strings"
 	"time"
 )
 
+// DefaultInterval is used when Watch is given a non-positive interval.
+const DefaultInterval = 5 * time.Minute
+
 // Notifier is the out-of-band alert sink (audit.Notifier satisfies it).
 type Notifier interface {
 	Notify(ctx context.Context, msg string) error
 }
 
-// Scan returns the brain-relative paths of every symlink inside brainDir,
-// skipping .git. brainDir itself may be a symlink (a volume mount); it is
-// resolved first, and only entries inside it are checked. WalkDir never
-// descends a symlinked directory, so each link is reported, not followed.
-func Scan(brainDir string) ([]string, error) {
+// Result is what a scan found: symlinks, and directories it could not read
+// (each of which could hide a symlink). Paths are brain-relative.
+type Result struct {
+	Symlinks   []string
+	Unreadable []string
+}
+
+// Clean reports whether the scan found nothing to act on.
+func (r Result) Clean() bool { return len(r.Symlinks) == 0 && len(r.Unreadable) == 0 }
+
+// String describes the findings for a log line or alert. Paths are quoted, so
+// a name containing a newline cannot blur two findings together.
+func (r Result) String() string {
+	q := func(xs []string) string {
+		out := make([]string, len(xs))
+		for i, x := range xs {
+			out[i] = strconv.Quote(x)
+		}
+		return strings.Join(out, ", ")
+	}
+	var parts []string
+	if len(r.Symlinks) > 0 {
+		parts = append(parts, fmt.Sprintf("%d symlink(s): %s", len(r.Symlinks), q(r.Symlinks)))
+	}
+	if len(r.Unreadable) > 0 {
+		parts = append(parts, fmt.Sprintf("%d unreadable dir(s): %s", len(r.Unreadable), q(r.Unreadable)))
+	}
+	return strings.Join(parts, "; ")
+}
+
+// Scan walks the brain dir and reports every symlink in it and every
+// directory it could not read, continuing past both. Only the ROOT .git is
+// skipped (it is brain-sync's, and no reader walks it); a nested .git is
+// scanned like any other directory. brainDir itself may be a symlink (a
+// volume mount); it is resolved first. The error is non-nil only when the
+// root cannot be resolved, wrapping os.ErrNotExist when it is missing.
+func Scan(brainDir string) (Result, error) {
 	root, err := filepath.EvalSymlinks(brainDir)
 	if err != nil {
-		return nil, fmt.Errorf("resolve brain dir: %w", err)
+		return Result{}, fmt.Errorf("resolve brain dir: %w", err)
 	}
-	var found []string
-	err = filepath.WalkDir(root, func(p string, d fs.DirEntry, err error) error {
+	var r Result
+	rootGit := filepath.Join(root, ".git")
+	_ = filepath.WalkDir(root, func(p string, d fs.DirEntry, err error) error {
+		rel, _ := filepath.Rel(root, p)
+		rel = filepath.ToSlash(rel)
 		if err != nil {
-			return err
+			if p == root {
+				return err
+			}
+			r.Unreadable = append(r.Unreadable, rel)
+			if d != nil && d.IsDir() {
+				return filepath.SkipDir
+			}
+			return nil
 		}
-		if d.IsDir() && d.Name() == ".git" {
+		if d.IsDir() && p == rootGit {
 			return filepath.SkipDir
 		}
 		if d.Type()&os.ModeSymlink != 0 {
-			rel, _ := filepath.Rel(root, p)
-			found = append(found, filepath.ToSlash(rel))
+			r.Symlinks = append(r.Symlinks, rel)
 		}
 		return nil
 	})
-	if err != nil {
-		return nil, fmt.Errorf("scan brain dir: %w", err)
-	}
-	sort.Strings(found)
-	return found, nil
+	sort.Strings(r.Symlinks)
+	sort.Strings(r.Unreadable)
+	return r, nil
 }
 
-// Watch rescans every interval and notifies once per distinct set of
-// symlinks found, until ctx ends. A scan error is logged, not fatal.
+// Watch rescans every interval (DefaultInterval if non-positive) until ctx
+// ends, and notifies once per distinct non-clean result. A result counts as
+// reported only after Notify succeeds, so an alert lost to a notifier outage
+// is retried on the next tick.
 func Watch(ctx context.Context, brainDir string, interval time.Duration, n Notifier) {
+	if interval <= 0 {
+		interval = DefaultInterval
+	}
 	t := time.NewTicker(interval)
 	defer t.Stop()
-	last := ""
+	reported := ""
 	for {
 		select {
 		case <-ctx.Done():
 			return
 		case <-t.C:
 		}
-		found, err := Scan(brainDir)
-		if err != nil {
-			slog.Warn("symlink tripwire scan failed", "err", err)
+		r, err := Scan(brainDir)
+		var key, msg string
+		switch {
+		case err != nil:
+			key = "error: " + err.Error()
+			msg = "brain symlink tripwire (hyperguild#157): cannot scan the brain dir: " + err.Error()
+		case r.Clean():
+			reported = ""
+			continue
+		default:
+			key = r.String()
+			msg = "brain symlink tripwire (hyperguild#157): " + key +
+				". Readers may follow symlinks out of the brain; remove them."
+		}
+		if key == reported {
 			continue
 		}
-		key := strings.Join(found, "\n")
-		if key == last {
+		slog.Error("brain symlink tripwire", "finding", key)
+		if n == nil {
+			reported = key
 			continue
 		}
-		last = key
-		if len(found) == 0 {
+		if err := n.Notify(ctx, msg); err != nil {
+			slog.Warn("symlink tripwire notify failed; will retry", "err", err)
 			continue
 		}
-		msg := fmt.Sprintf("brain symlink tripwire (hyperguild#157): %d symlink(s) in the brain dir; "+
-			"readers may follow them out of the brain. Remove them: %s", len(found), strings.Join(found, ", "))
-		slog.Error("brain symlink tripwire", "count", len(found), "paths", found)
-		if n != nil {
-			if err := n.Notify(ctx, msg); err != nil {
-				slog.Warn("symlink tripwire notify failed", "err", err)
-			}
-		}
+		reported = key
 	}
 }