fix: pipeline, backfill, watcher and archive writes go through the brain root (#158 part B)

The remaining writers created or rewrote brain files by path:
- pipeline buildAndWrite: os.MkdirAll + os.WriteFile of every page.
- BackfillRefs: os.WriteFile of each concept page; a page swapped for a
  symlink after the read was written through (the race test overwrote an
  in-brain target before this change).
- watcher: the raw/processed and raw/failed archive copies (os.Create),
  the .processed/.failed markers and the log.md entry (os.OpenFile).
- cmd/server: the claude-session archive.

All now go through brainfs PutRegular/AppendRegular (new package-level
PutFile/AppendFile for one-off writers: the watcher's call-site lint bans
.Open calls in that file so raw/ reads stay on OpenRegular).

Stacked on #189 (needs PutRegular/AppendRegular).

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

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 := os.WriteFile(dest, []byte(page.Content), 0o644); err != nil {
+		if err := bfs.PutRegular(relPath, []byte(page.Content)); 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,28 @@ 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")
+}