test(watcher): a marker link planted during the run is refused and not retried (#158)

Review round 2 on PR #195: the marker writes had no test, so reverting
them to by-path writes, or the refusal to log-only, stayed green. The
link is planted from inside the fake model call, between the walk's
Lstat and the marker write, for both markers and both an outside and
an in-brain relative target; red on all four flips. The marker-entry
skip is now checked for .failed too.

Also pins cleanRel's acceptance of a backslash as a filename byte in
brainfs itself, and stops the buildAndWrite control claiming writes it
does not count.

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

ingestion/cmd/server/main.go

@@ -17,6 +17,7 @@ import (
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/audit"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/capturehttp"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
@@ -89,11 +90,15 @@ func (s *claudeSink) Ingest(ctx context.Context, b claudewatcher.Batch) error {
 		sb.WriteString("\n\n")
 	}
 	slug := "session-" + b.Host + "-" + b.SessionID
-	dest := filepath.Join(s.brainDir, "archive", "claude-sessions", b.Host, slug+".md")
+	dest := "archive/claude-sessions/" + b.Host + "/" + slug + ".md"
-	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+	// Written through the brain root, never through a symlinked directory
-		return fmt.Errorf("create claude-sessions archive dir: %w", err)
+	// or file (hyperguild#158).
+	bfs, err := brainfs.Open(s.brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
 	}
-	if err := os.WriteFile(dest, []byte(sb.String()), 0o644); err != nil {
+	defer func() { _ = bfs.Close() }()
+	if err := bfs.PutRegular(dest, []byte(sb.String())); err != nil {
 		return fmt.Errorf("write claude session archive: %w", err)
 	}
 	s.logger.Debug("claude session archived (non-indexed)", "path", dest)

ingestion/cmd/server/main_test.go

@@ -76,3 +76,27 @@ func TestAlertingWarnings(t *testing.T) {
 		})
 	}
 }
+
+// hyperguild#158: the claude-session archive was written with os.MkdirAll +
+// os.WriteFile by path, so a symlinked archive directory redirected it.
+func TestClaudeSinkDoesNotWriteThroughASymlinkedArchiveDir(t *testing.T) {
+	for name, mk := range map[string]func(t *testing.T, dir string) (link, target string){
+		"outside": func(t *testing.T, _ string) (string, string) { o := t.TempDir(); return o, o },
+		"in-brain": func(t *testing.T, dir string) (string, string) {
+			require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
+			return filepath.Join("..", "raw"), filepath.Join(dir, "raw")
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			dir := t.TempDir()
+			link, target := mk(t, dir)
+			require.NoError(t, os.Symlink(link, filepath.Join(dir, "archive")))
+			sink := &claudeSink{brainDir: dir, logger: slog.New(slog.NewTextHandler(os.Stderr, nil))}
+			err := sink.Ingest(context.Background(), claudewatcher.Batch{Host: "koala", SessionID: "abc",
+				Turns: []claudewatcher.Turn{{Type: "assistant", Content: "x"}}})
+			assert.Error(t, err)
+			ents, _ := os.ReadDir(target)
+			assert.Empty(t, ents, "the archive was written at the link's target")
+		})
+	}
+}

ingestion/internal/brainfs/brainfs.go

@@ -109,7 +109,7 @@ func (b *Brain) ReadDirRegular(relDir string) ([]string, error) {
 // 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, "\\") {
+	if rel == "" || path.Clean(rel) != rel || !filepath.IsLocal(rel) {
 		return fmt.Errorf("%q: not a clean brain-relative path: %w", rel, ErrNotRegular)
 	}
 	return nil
@@ -243,6 +243,27 @@ func (b *Brain) RealParent(rel string) error {
 	return b.realDir(path.Dir(rel))
 }
 
+// PutFile opens the brain dir as a root and calls PutRegular, for one-off
+// writers that hold no Brain.
+func PutFile(brainDir, rel string, data []byte) error {
+	b, err := Open(brainDir)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = b.Close() }()
+	return b.PutRegular(rel, data)
+}
+
+// AppendFile opens the brain dir as a root and calls AppendRegular.
+func AppendFile(brainDir, rel string, data []byte) error {
+	b, err := Open(brainDir)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = b.Close() }()
+	return b.AppendRegular(rel, data)
+}
+
 // mkdirReal makes sure every component of rel exists as a real directory,
 // creating missing ones through the root; an existing component that is
 // not a real directory is ErrNotRegular.

ingestion/internal/brainfs/brainfs_test.go

@@ -529,3 +529,20 @@ func TestCreateRegularCreatesOnlyNewFilesThroughRealDirectories(t *testing.T) {
 	got, _ = os.ReadFile(filepath.Join(dir, "wiki", "new", "facts", "n.md"))
 	assert.Equal(t, "one", string(got))
 }
+
+// On Linux a backslash is an ordinary filename byte, not a separator, so a
+// name containing one stays a single in-root component (hyperguild#158: the
+// watcher retried such a note forever while cleanRel refused it).
+func TestReadAndPutRegularTreatABackslashAsAFilenameByte(t *testing.T) {
+	dir := t.TempDir()
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+	require.NoError(t, b.PutRegular(`a\..\b.md`, []byte("x")))
+	got, err := os.ReadFile(filepath.Join(dir, `a\..\b.md`))
+	require.NoError(t, err, "the name was not kept as one component")
+	assert.Equal(t, "x", string(got))
+	got, err = b.ReadRegular(`a\..\b.md`)
+	require.NoError(t, err)
+	assert.Equal(t, "x", string(got))
+}

ingestion/internal/extract/callsites_test.go

@@ -88,7 +88,6 @@ func TestNoPackageReferencesExtractTextOutsideExtract(t *testing.T) {
 // osOpenAllowed names the functions in guarded files that may call os.Open*
 // on a path that is not a raw/ read.
 var osOpenAllowed = map[string]bool{
-	"internal/watcher/watcher.go:appendWatcherLog": true, // ingest log append, not a raw/ read
 	// Text reads by path; outside this package only TextIn's temp copy reaches
 	// it (TestNoPackageReferencesExtractTextOutsideExtract enforces that).
 	"internal/extract/extract.go:Text": true,

ingestion/internal/pipeline/backfill.go

@@ -7,8 +7,6 @@ import (
 	"fmt"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"io/fs"
-	"os"
-	"path/filepath"
 	"strings"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/wiki"
@@ -90,8 +88,7 @@ func BackfillRefs(ctx context.Context, brainDir string) (int, error) {
 	}
 
 	for relPath, page := range pending {
-		dest := filepath.Join(brainDir, filepath.FromSlash(relPath))
+		if err := bfs.PutRegular(relPath, []byte(page.Content)); err != nil {
-		if err := os.WriteFile(dest, []byte(page.Content), 0o644); err != nil {
 			return 0, fmt.Errorf("write %s: %w", relPath, err)
 		}
 	}

ingestion/internal/pipeline/pipeline.go

@@ -9,8 +9,6 @@ import (
 	"fmt"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"io/fs"
-	"os"
-	"path/filepath"
 	"strings"
 	"time"
 
@@ -128,10 +126,6 @@ func buildAndWrite(ctx context.Context, rawPages []RawPage, sourceSlug, date, br
 	var written []string
 	for _, page := range merged {
 		if !dryRun {
-			dest := filepath.Join(brainDir, filepath.FromSlash(page.Path))
-			if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
-				return Result{}, fmt.Errorf("mkdir for %s: %w", page.Path, err)
-			}
 			content, conflicts, err := reviseOrCreate(brainDir, page)
 			if err != nil {
 				return Result{}, err
@@ -150,7 +144,9 @@ func buildAndWrite(ctx context.Context, rawPages []RawPage, sourceSlug, date, br
 			if err != nil {
 				return Result{}, fmt.Errorf("stamp %s: %w", page.Path, err)
 			}
-			if err := os.WriteFile(dest, []byte(stamped), 0o644); err != nil {
+			// Written through the brain root, never through a symlinked
+			// directory or page (hyperguild#158).
+			if err := writeBrainFile(brainDir, page.Path, []byte(stamped)); err != nil {
 				return Result{}, fmt.Errorf("write %s: %w", page.Path, err)
 			}
 		}
@@ -201,6 +197,17 @@ func readSourcePage(brainDir, sourceSlug string) string {
 	return string(raw)
 }
 
+// writeBrainFile creates or replaces one brain-relative file through the
+// brain root (hyperguild#158).
+func writeBrainFile(brainDir, rel string, data []byte) error {
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = bfs.Close() }()
+	return bfs.PutRegular(rel, data)
+}
+
 // readBrainFile reads one brain-relative file through the brain root,
 // regular files only (hyperguild#157).
 func readBrainFile(brainDir, rel string) ([]byte, error) {

ingestion/internal/pipeline/root_test.go

@@ -165,3 +165,53 @@ func TestBackfillRefsDoesNotCopyAPageSwappedInBehindASymlink(t *testing.T) {
 	require.Contains(t, read(), "[[s|S]]", "positive control: the regular page gets the source ref")
 	brainfstest.AssertNoLeakFrom(t, page, inside, target, 3*time.Second, read)
 }
+
+// hyperguild#158: BackfillRefs read a regular concept page, a symlink could
+// be swapped in, and os.WriteFile then followed it and overwrote the link's
+// target. The target is not restored between rounds here, so any
+// write-through shows.
+func TestBackfillRefsNeverWritesThroughAPageSwappedForASymlink(t *testing.T) {
+	brain := t.TempDir()
+	mkdirs(t, brain, "wiki/sources", "wiki/concepts", "raw")
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "sources", "s.md"), []byte("---\ntitle: S\n---\n[[c|C]]\n"), 0o644))
+	page := filepath.Join(brain, "wiki", "concepts", "c.md")
+	target := filepath.Join(brain, "raw", "secret.md")
+	require.NoError(t, os.WriteFile(target, []byte("untouched"), 0o644))
+	inside := "---\ntitle: C\n---\nbody\n"
+	require.NoError(t, os.WriteFile(page, []byte(inside), 0o644))
+	brainfstest.StartSwap(t, page, inside, target, false)
+	ok := 0
+	for deadline := time.Now().Add(2 * time.Second); time.Now().Before(deadline); {
+		if _, err := BackfillRefs(context.Background(), brain); err == nil {
+			ok++
+		}
+	}
+	got, _ := os.ReadFile(target)
+	assert.Equal(t, "untouched", string(got), "BackfillRefs wrote through a swapped-in symlink")
+	assert.Positive(t, ok, "positive control: some backfills ran")
+}
+
+// hyperguild#158: buildAndWrite wrote each page with os.WriteFile by path, so
+// a page read as regular and swapped for a symlink before the write was
+// written through. The target is not restored between rounds, so any
+// write-through shows.
+func TestBuildAndWriteNeverWritesThroughAPageSwappedForASymlink(t *testing.T) {
+	brain := t.TempDir()
+	mkdirs(t, brain, "wiki/sources", "wiki/concepts", "wiki/entities", "raw")
+	page := filepath.Join(brain, "wiki", "concepts", "zq-concept.md")
+	target := filepath.Join(brain, "raw", "secret.md")
+	require.NoError(t, os.WriteFile(target, []byte("untouched"), 0o644))
+	inside := "---\ntitle: Zq Concept\n---\nbody\n"
+	require.NoError(t, os.WriteFile(page, []byte(inside), 0o644))
+	pages := []RawPage{{Title: "Zq Concept", Type: "concept", Content: "## About\n\nmore\n"}}
+	brainfstest.StartSwap(t, page, inside, target, false)
+	ok := 0
+	for deadline := time.Now().Add(2 * time.Second); time.Now().Before(deadline); {
+		if _, err := RunRaw(context.Background(), brain, "zq source", pages, false); err == nil {
+			ok++
+		}
+	}
+	got, _ := os.ReadFile(target)
+	assert.Equal(t, "untouched", string(got), "buildAndWrite wrote through a swapped-in symlink")
+	assert.Positive(t, ok, "positive control: some runs returned without error")
+}

ingestion/internal/watcher/watcher.go

@@ -3,15 +3,18 @@ package watcher
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"log/slog"
 	"os"
 	"path/filepath"
 	"strings"
+	"sync"
 	"time"
 	"unicode"
 
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/extract"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 )
@@ -109,14 +112,28 @@ func processDir(ctx context.Context, cfg Config, date string) []error {
 		}
 
 		// Skip files that have already been processed or permanently failed.
-		if _, err := os.Stat(path + ".processed"); err == nil {
+		// Any entry at the marker path counts (Lstat, not Stat): a dangling
+		// marker symlink made os.Stat report nothing and the note was
+		// reprocessed every interval (hyperguild#158).
+		if _, err := os.Lstat(path + ".processed"); err == nil {
 			return nil
 		}
-		if _, err := os.Stat(path + ".failed"); err == nil {
+		if _, err := os.Lstat(path + ".failed"); err == nil {
+			return nil
+		}
+		// A note whose archive copy or marker was refused is not retried
+		// until it changes: a refusal has no marker to stop the next round,
+		// and each round can cost an LLM call (hyperguild#158).
+		info, ierr := d.Info()
+		if ierr == nil && refusedUnchanged(path, info) {
 			return nil
 		}
 
 		if err := processFile(ctx, cfg, root, rawDir, path, date); err != nil {
+			if ierr == nil && errors.Is(err, brainfs.ErrNotRegular) {
+				rememberRefused(path, info)
+				slog.Error("watcher: note refused; not retried until it changes", "file", filepath.Base(path), "error", err)
+			}
 			errs = append(errs, fmt.Errorf("process %s: %w", filepath.Base(path), err))
 		}
 		return nil
@@ -145,16 +162,15 @@ func processFile(ctx context.Context, cfg Config, root *os.Root, rawDir, path, d
 
 	_, runErr := pipeline.Run(ctx, cfg.Pipeline, cfg.BrainDir, content, source, false)
 	if runErr != nil {
-		// Copy to failed/ and leave a .failed marker so we don't retry.
+		// Copy to failed/ and leave a .failed marker so we don't retry. Both
-		failedDir := filepath.Join(cfg.BrainDir, "raw", "failed")
+		// written through the brain root (hyperguild#158).
-		if mkErr := os.MkdirAll(failedDir, 0o755); mkErr != nil {
+		if cpErr := copyFromRoot(root, rel, cfg.BrainDir, "raw/failed/"+filename); cpErr != nil {
-			return fmt.Errorf("mkdir failed dir: %w", mkErr)
-		}
-		dest := filepath.Join(failedDir, filename)
-		if cpErr := copyFromRoot(root, rel, dest); cpErr != nil {
 			return fmt.Errorf("copy to failed: %w", cpErr)
 		}
-		if mkErr := os.WriteFile(path+".failed", []byte(runErr.Error()), 0o644); mkErr != nil {
+		if mkErr := putBrainFile(cfg.BrainDir, "raw/"+filepath.ToSlash(rel)+".failed", []byte(runErr.Error())); mkErr != nil {
+			if errors.Is(mkErr, brainfs.ErrNotRegular) {
+				return fmt.Errorf("write .failed marker: %w", mkErr)
+			}
 			slog.Error("watcher: failed to write .failed marker", "error", mkErr)
 		}
 
@@ -168,21 +184,21 @@ func processFile(ctx context.Context, cfg Config, root *os.Root, rawDir, path, d
 	}
 
 	// Copy to processed/YYYY-MM-DD/ and leave a .processed marker so we don't re-ingest.
-	processedDir := filepath.Join(cfg.BrainDir, "raw", "processed", date)
+	// Written through the brain root (hyperguild#158).
-	if err := os.MkdirAll(processedDir, 0o755); err != nil {
+	dest := "raw/processed/" + date + "/" + filename
-		return fmt.Errorf("mkdir processed dir: %w", err)
+	if _, err := os.Lstat(filepath.Join(cfg.BrainDir, filepath.FromSlash(dest))); err == nil {
-	}
-	dest := filepath.Join(processedDir, filename)
-	if _, err := os.Stat(dest); err == nil {
 		// Archive copy already exists; append timestamp to avoid overwriting.
 		ext := filepath.Ext(filename)
 		base := strings.TrimSuffix(filename, ext)
-		dest = filepath.Join(processedDir, base+"-"+time.Now().UTC().Format("150405")+ext)
+		dest = "raw/processed/" + date + "/" + base + "-" + time.Now().UTC().Format("150405") + ext
 	}
-	if err := copyFromRoot(root, rel, dest); err != nil {
+	if err := copyFromRoot(root, rel, cfg.BrainDir, dest); err != nil {
 		return fmt.Errorf("copy to processed: %w", err)
 	}
-	if err := os.WriteFile(path+".processed", []byte(date), 0o644); err != nil {
+	if err := putBrainFile(cfg.BrainDir, "raw/"+filepath.ToSlash(rel)+".processed", []byte(date)); err != nil {
+		if errors.Is(err, brainfs.ErrNotRegular) {
+			return fmt.Errorf("write .processed marker: %w", err)
+		}
 		slog.Error("watcher: failed to write .processed marker", "error", err)
 	}
 
@@ -190,6 +206,32 @@ func processFile(ctx context.Context, cfg Config, root *os.Root, rawDir, path, d
 	return nil
 }
 
+// refused remembers notes whose archive copy or marker write was refused,
+// by path, with the size and mtime they had, for the life of the process.
+var refused sync.Map
+
+type refusedStamp struct {
+	size  int64
+	mtime time.Time
+}
+
+func rememberRefused(path string, info os.FileInfo) {
+	refused.Store(path, refusedStamp{size: info.Size(), mtime: info.ModTime()})
+}
+
+func refusedUnchanged(path string, info os.FileInfo) bool {
+	v, ok := refused.Load(path)
+	if !ok {
+		return false
+	}
+	st := v.(refusedStamp)
+	if st.size == info.Size() && st.mtime.Equal(info.ModTime()) {
+		return true
+	}
+	refused.Delete(path)
+	return false
+}
+
 // deriveSource turns a filename into a human-readable source name.
 // "shape-up-book.md" → "Shape Up Book"
 func deriveSource(filename string) string {
@@ -214,23 +256,22 @@ func appendWatcherLog(brainDir, filename string, runErr error, date string) erro
 	entry := fmt.Sprintf("## %s — watcher error\n\n- **File:** %s\n- **Error:** %s\n\n",
 		date, filename, runErr.Error())
 
-	logPath := filepath.Join(brainDir, "log.md")
+	if err := brainfs.AppendFile(brainDir, "log.md", []byte(entry)); err != nil {
-	f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
-	if err != nil {
-		return fmt.Errorf("open log: %w", err)
-	}
-
-	if _, err = f.WriteString(entry); err != nil {
-		f.Close() //nolint:errcheck
 		return fmt.Errorf("write log: %w", err)
 	}
-	return f.Close()
+	return nil
+}
+
+// putBrainFile creates or replaces a brain-relative file through the brain
+// root, never through a symlinked directory or file (hyperguild#158).
+func putBrainFile(brainDir, rel string, data []byte) error {
+	return brainfs.PutFile(brainDir, rel, data)
 }
 
 // copyFromRoot archives a raw/ file read through the root, refusing anything
 // that is not a regular file, so a swapped-in symlink cannot copy an outside
 // file into raw/processed/ or raw/failed/ (hyperguild#153).
-func copyFromRoot(root *os.Root, rel, dst string) error {
+func copyFromRoot(root *os.Root, rel, brainDir, dstRel string) error {
 	fi, err := root.Lstat(rel)
 	if err != nil {
 		return err
@@ -243,13 +284,9 @@ func copyFromRoot(root *os.Root, rel, dst string) error {
 		return err
 	}
 	defer func() { _ = in.Close() }()
-	out, err := os.Create(dst)
+	data, err := io.ReadAll(in)
 	if err != nil {
 		return err
 	}
-	if _, err := io.Copy(out, in); err != nil {
+	return putBrainFile(brainDir, dstRel, data)
-		_ = out.Close()
-		return err
-	}
-	return out.Close()
 }

ingestion/internal/watcher/writes_redirect_test.go

@@ -0,0 +1,186 @@
+package watcher
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
+)
+
+func okPipeline() pipeline.Config {
+	return pipeline.Config{Complete: func(context.Context, string, string) (string, error) {
+		b, _ := json.Marshal([]pipeline.RawPage{{Title: "X", Type: "source", Subtype: "article", Content: "## S\n\nx\n"}})
+		return string(b), nil
+	}, Schema: "# Schema"}
+}
+
+func failingPipeline() pipeline.Config {
+	return pipeline.Config{Complete: func(context.Context, string, string) (string, error) {
+		return "", errors.New("model down")
+	}, Schema: "# Schema"}
+}
+
+// hyperguild#158: the watcher wrote the archive copy under raw/processed or
+// raw/failed, and its log.md entry, by path, so a symlinked archive
+// directory or log redirected the write elsewhere in the brain or outside
+// it. (A pre-planted marker symlink makes the watcher skip the note, so the
+// marker write itself is reachable only by a race.)
+func TestProcessDirDoesNotWriteThroughASymlinkedArchiveDir(t *testing.T) {
+	for name, pcfg := range map[string]pipeline.Config{"processed": okPipeline(), "failed": failingPipeline()} {
+		t.Run(name, func(t *testing.T) {
+			brainDir := setupBrainDir(t)
+			outside := t.TempDir()
+			victim := filepath.Join(brainDir, "wiki", "concepts", "v.md")
+			require.NoError(t, os.WriteFile(victim, []byte("untouched"), 0o644))
+			require.NoError(t, os.WriteFile(filepath.Join(brainDir, "raw", "n.md"), []byte("note"), 0o644))
+			require.NoError(t, os.Symlink(outside, filepath.Join(brainDir, "raw", name)))
+			_ = processDir(context.Background(), Config{BrainDir: brainDir, Interval: time.Hour, Pipeline: pcfg}, "2026-10-05")
+			got, _ := os.ReadFile(victim)
+			assert.Equal(t, "untouched", string(got))
+			ents, _ := os.ReadDir(outside)
+			assert.Empty(t, ents, "the archive copy was written outside the brain")
+		})
+	}
+}
+
+func TestProcessDirWritesMarkersAndArchiveInRealDirectories(t *testing.T) {
+	brainDir := setupBrainDir(t)
+	require.NoError(t, os.WriteFile(filepath.Join(brainDir, "raw", "n.md"), []byte("note"), 0o644))
+	errs := processDir(context.Background(), Config{BrainDir: brainDir, Interval: time.Hour, Pipeline: okPipeline()}, "2026-10-05")
+	assert.Empty(t, errs)
+	_, err := os.Stat(filepath.Join(brainDir, "raw", "n.md.processed"))
+	assert.NoError(t, err, "positive control: marker written")
+	_, err = os.Stat(filepath.Join(brainDir, "raw", "processed", "2026-10-05", "n.md"))
+	assert.NoError(t, err, "positive control: archive copy written")
+}
+
+// The log.md entry for a failed note is appended through the brain root: with
+// a real raw/failed (so the archive copy succeeds and the log is reached), a
+// symlinked log.md is not written through.
+func TestProcessDirDoesNotAppendTheLogThroughASymlink(t *testing.T) {
+	brainDir := setupBrainDir(t)
+	victim := filepath.Join(brainDir, "wiki", "concepts", "v.md")
+	require.NoError(t, os.WriteFile(victim, []byte("untouched"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(brainDir, "raw", "n.md"), []byte("note"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("wiki", "concepts", "v.md"), filepath.Join(brainDir, "log.md")))
+	_ = processDir(context.Background(), Config{BrainDir: brainDir, Interval: time.Hour, Pipeline: failingPipeline()}, "2026-10-05")
+	_, err := os.Stat(filepath.Join(brainDir, "raw", "failed", "n.md"))
+	require.NoError(t, err, "positive control: the archive copy was written, so the log append was reached")
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched", string(got), "the log was appended through a symlink")
+}
+
+// A marker path holding anything (here a dangling symlink) counts as a
+// marker: the note is skipped and nothing is created at the link's target.
+// (os.Stat followed the link, saw nothing, and processed the note again.)
+func TestProcessDirTreatsAnyEntryAtTheMarkerPathAsAMarker(t *testing.T) {
+	for _, kind := range []string{"processed", "failed"} {
+		t.Run(kind, func(t *testing.T) {
+			brainDir := setupBrainDir(t)
+			outside := filepath.Join(t.TempDir(), "created")
+			require.NoError(t, os.WriteFile(filepath.Join(brainDir, "raw", "n.md"), []byte("note"), 0o644))
+			require.NoError(t, os.Symlink(outside, filepath.Join(brainDir, "raw", "n.md."+kind)))
+			calls := 0
+			cfg := Config{BrainDir: brainDir, Interval: time.Hour, Pipeline: pipeline.Config{
+				Complete: func(context.Context, string, string) (string, error) { calls++; return "[]", nil }, Schema: "# Schema"}}
+			_ = processDir(context.Background(), cfg, "2026-10-05")
+			assert.Zero(t, calls, "the note was processed despite an entry at its marker path")
+			_, err := os.Lstat(outside)
+			assert.True(t, os.IsNotExist(err), "a file was created at the marker link's target")
+		})
+	}
+}
+
+// The marker write itself is reachable while pipeline.Run is in flight
+// (in production, an LLM call): a link planted at the marker path then is
+// refused, and the note is remembered, so removing the link (as
+// symlinkguard does) does not make the watcher call the model again.
+func TestProcessDirRefusesAMarkerLinkPlantedDuringTheRunAndDoesNotRetry(t *testing.T) {
+	for _, kind := range []string{"processed", "failed"} {
+		for _, target := range []string{"outside", "in-brain"} {
+			t.Run(kind+"/"+target, func(t *testing.T) {
+				brainDir := setupBrainDir(t)
+				raw := filepath.Join(brainDir, "raw")
+				marker := filepath.Join(raw, "n.md."+kind)
+				require.NoError(t, os.WriteFile(filepath.Join(raw, "n.md"), []byte("note"), 0o644))
+				// The in-brain target is relative, so os.Root itself would
+				// follow it; only the regular-file check refuses it.
+				victim := filepath.Join(raw, "victim")
+				link := filepath.Join(t.TempDir(), "created")
+				if target == "in-brain" {
+					require.NoError(t, os.WriteFile(victim, []byte("untouched"), 0o644))
+					link = "victim"
+				}
+				ok := okPipeline().Complete
+				calls := 0
+				cfg := Config{BrainDir: brainDir, Interval: time.Hour, Pipeline: pipeline.Config{Schema: "# Schema",
+					Complete: func(ctx context.Context, sys, user string) (string, error) {
+						calls++
+						require.NoError(t, os.Symlink(link, marker))
+						if kind == "failed" {
+							return "", errors.New("model down")
+						}
+						return ok(ctx, sys, user)
+					}}}
+				for i := 0; i < 3; i++ {
+					errs := processDir(context.Background(), cfg, "2026-10-05")
+					if i == 0 {
+						require.NotEmpty(t, errs, "the planted link was not refused")
+					}
+					_ = os.Remove(marker)
+				}
+				assert.Equal(t, 1, calls, "the note was retried after its marker write was refused")
+				if target == "in-brain" {
+					got, err := os.ReadFile(victim)
+					require.NoError(t, err)
+					assert.Equal(t, "untouched", string(got), "the marker was written through the link")
+				} else {
+					_, err := os.Lstat(link)
+					assert.True(t, os.IsNotExist(err), "the marker was written through the link")
+				}
+			})
+		}
+	}
+}
+
+// A refused archive copy must not retry every interval: the note is
+// remembered and skipped until it changes (a symlinked raw/failed cost one
+// LLM call per round before).
+func TestProcessDirDoesNotRetryANoteWhoseArchiveCopyIsRefused(t *testing.T) {
+	brainDir := setupBrainDir(t)
+	require.NoError(t, os.WriteFile(filepath.Join(brainDir, "raw", "n.md"), []byte("note"), 0o644))
+	require.NoError(t, os.Symlink(t.TempDir(), filepath.Join(brainDir, "raw", "failed")))
+	calls := 0
+	cfg := Config{BrainDir: brainDir, Interval: time.Hour, Pipeline: pipeline.Config{
+		Complete: func(context.Context, string, string) (string, error) { calls++; return "", errors.New("model down") }, Schema: "# Schema"}}
+	for i := 0; i < 3; i++ {
+		_ = processDir(context.Background(), cfg, "2026-10-05")
+	}
+	assert.Equal(t, 1, calls, "the refused note was retried every round")
+
+	// Once the note changes it is tried again.
+	require.NoError(t, os.WriteFile(filepath.Join(brainDir, "raw", "n.md"), []byte("note, edited"), 0o644))
+	future := time.Now().Add(2 * time.Second)
+	require.NoError(t, os.Chtimes(filepath.Join(brainDir, "raw", "n.md"), future, future))
+	_ = processDir(context.Background(), cfg, "2026-10-05")
+	assert.Equal(t, 2, calls, "positive control: a changed note is tried again")
+}
+
+// A note whose name has a backslash is legal on Linux and must be processed
+// (cleanRel refused it, so it was never archived or marked).
+func TestProcessDirProcessesANoteWithABackslashInItsName(t *testing.T) {
+	brainDir := setupBrainDir(t)
+	require.NoError(t, os.WriteFile(filepath.Join(brainDir, "raw", "a\\b.md"), []byte("note"), 0o644))
+	errs := processDir(context.Background(), Config{BrainDir: brainDir, Interval: time.Hour, Pipeline: okPipeline()}, "2026-10-05")
+	assert.Empty(t, errs)
+	_, err := os.Stat(filepath.Join(brainDir, "raw", "a\\b.md.processed"))
+	assert.NoError(t, err)
+}