chore(context): restore the root rules in AGENTS.md and system-prompt.txt (#200) (#201)

Co-authored-by: Mathias <mthbqv@gmail.com>

.context/PROJECT.md

@@ -84,3 +84,15 @@ When acting as a coding agent on this project:
 4. Never modify files outside the project root without explicit permission
 5. When adding a dependency, explain why in the commit message
 6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
+
+## `main` is protected: ship by PR (local-dev#42, decided 2026-10-08)
+
+Gitea refuses direct pushes to `main` in this repo, and a PR merges only after its CI status (`CI / Lint / Test / Vet (pull_request)`) passes.
+**Why:** local-dev rule 5's reviewed lane (risk/medium+ is reviewed by a human) was enforced on the merge tools
+(`tbd_ship`, `pr_merge`: gitea-mcp v0.17.0/v0.18.0, merge only for an issue labelled exactly `risk/low` with green CI)
+but not on a direct commit to `main`, which bypassed it. This overrides rule 5's "risk/low commits straight to main"
+for this repo; control code is where the lane matters.
+**How:** `tbd_ship` for a one-file change, or branch -> PR -> `pr_merge` (name the `risk/low` issue); above `risk/low`
+open the PR and a human merges it in the Gitea UI after review. Tags are not protected. CD jobs push image tags to
+the **infra** repo with deploy keys, never to this repo's `main`. Undo (Mathias only): Settings -> Branches, or
+`PATCH /repos/mathias/hyperguild/branch_protections/main {"enable_push": true}`.

.context/system-prompt.txt

@@ -164,6 +164,63 @@ These rules apply to every task across every project, regardless of harness.
    the thing it was named for was exploitable. If you cannot name the mechanism,
    you do not yet know what the test observes.
 
+10. **Short sessions, one rc per repo, edit only in a locked worktree of the repo
+   you are changing** (ADR-0002, accepted 2026-10-06).
+   - One session per issue or task, ending with rule 6's close ritual. Related
+     issues may share a session only when they share a worktree and an owner.
+     State that must outlive the session goes in an issue, not the chat.
+   - Start `claude rc` in the repo you will edit (`infra`, `trucker-ecommerce`,
+     `hyperguild`, ...), not in `~/dev`: the rc worktree is a worktree of the
+     launch directory's repo, so launched from `~/dev` it protects nothing you
+     edit (measured: 73% of edits landed in shared checkouts). Start it only
+     while working there.
+   - Keep at most one thin `~/dev` coordinator session. It files issues and hands
+     out tasks; it reads and edits no sub-repo code.
+   - Split cross-repo work per repo. The contract between the halves lives in an
+     issue on each repo.
+   - Edit in a worktree of that repo, locked at creation:
+     `scripts/wt.sh add <repo> <task>` does it (fetch, `wt/<task>` from origin/main, lock);
+     `scripts/wt.sh done <repo>-<task>` removes it after the push and refuses dirty or
+     unpushed work. By hand: `git worktree add ~/worktrees/<name> -b <branch> origin/main`
+     then `git worktree lock --reason "manual: <purpose>" ~/worktrees/<name>`.
+   - Before working a repo another session may touch, announce your issue list to
+     that session (`SendMessage`) and ask for theirs.
+   - Auto-memory is keyed by cwd, so a repo rc starts without it. Cross-repo
+     working rules live in brain (`wiki/homelab/decisions/2026-10-06-062416-auto.md`, wing homelab, hall
+     decisions) and the section below, not in per-directory memory.
+
+## Standing footguns
+
+Each cost real time once. Detail and evidence: brain `wiki/homelab/decisions/2026-10-06-062416-auto.md` (title standing-working-rules).
+
+- **Gate then commit with `&&`, never `;`.** "Green" means exit code 0 and
+  `grep -c FAIL` is 0, not a filtered grep.
+- **Stage by path, never `git add -A` or `git add .`** (they stage from the repo
+  root and swept in other sessions' work twice). Check `git status --porcelain` first.
+- **Before committing in a shared checkout:** `git branch --show-current`.
+- **Before tagging:** `git fetch origin --tags`, then `git describe --tags --abbrev=0 <sha>`
+  and `git tag --sort=-v:refname | head`; go above both. Never take the last tag
+  from a report.
+- **Run only what the project's gate runs.** No repo-wide formatter unless the gate
+  runs it.
+- **Reproduce a CI red at the cited commit before applying an issue's prescribed fix.**
+- **Read an issue's comments (`issue_list_comments`), not just its body, before working it.**
+- **A comment naming a control ("behind branch protection") is not evidence; query
+  the control.** A working detector can hide a missing preventer.
+- **On koala the MCP servers are `mcp__plugin_skills_{brain,gitea,infra}__*`.** The
+  per-turn auth reminder is not evidence; call the tool or run `claude mcp list`.
+  Brain writes always pass `wing` + `hall`.
+- **`cat /etc/hostname` before assuming which host you are on.**
+- **Never run bare `git remote -v` or `git config --list`** (url.insteadOf expands
+  into a live token); use `git config --get remote.origin.url`.
+- **On koala `sudo` is denied outright; k8s exec, env dumps and flux reconcile need
+  per-action approval; decrypting a SOPS file and printing in one Bash call is
+  hook-blocked.** Do the repo-side work and hand the host-side step over in an issue.
+- **`set -o pipefail` plus an optional `grep | head | awk` dies on no match:** append `|| true`.
+- **Gitea `file_write_branch` takes plain text, not base64.**
+- **`OP_SERVICE_ACCOUNT_TOKEN` in the shell is read-only for `op`.** Operational
+  secrets go in the AgentSecrets vault via `set -a; . ~/.op-agent-write.env; set +a`.
+
 ## CAD sprint patterns
 
 Two CAD sprint archetypes (defs: brain `wiki/homelab/decisions/continuous-agentic-development-cad-concept-2026-06-16`):
@@ -244,25 +301,20 @@ Three machines on Tailscale:
 
 All development repos live at `~/dev/` (softlink from `~/Documents/local-dev/`).
 
-Organized in thematic folders:
+Organized by **role**, because the role decides which rules apply (ADR-0003):
 
-| Folder | Focus | Count |
+| Folder | Role | Rules that key off it |
-|--------|-------|-------|
+|--------|------|-----------------------|
-| `GO/` | Go web frameworks, API integrations, learning projects | ~10 |
+| `platform/` | infra, brain, hyperguild, gitea-mcp, dispatch, shared tooling | control code (rule 8), GitOps review lane |
-| `AI/` | ML research, AI frameworks (FinRL, DSPy, crawl4ai) | ~6 |
+| `products/` | tapir, cobalt-dingo, openbanking-api, ... | ordinary trunk-based work |
-| `AGENTS/` | Autonomous agents, coding agents, MCP servers, infra | ~15 |
+| `clients/` | client work | local models only, never cloud APIs (Client work rules) |
-| `QKX/` | Invoice processing, financial automation, payment systems | ~13 |
+| `spikes/` | throwaway | no ceremony |
-| `XT/` | Climate data, sustainability (Klimatkollen, Garbo) | ~2 |
 
-See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
+New projects are born into a role folder (`task new-project -- <name> <client|personal>
-
+<role-folder>`); a client tag requires `clients/` and `clients/` requires a client tag.
-### Key active projects
+Existing repos still sit in the old `AGENTS/` and `AI/` folders until they are moved one by
-
+one (ADR-0003 step 3). `~/dev/PROJECT_SUMMARY.md` (generated) lists every repo and where it
-- **super-koala** (`AGENTS/`) — multi-component agent stack with LangGraph, DSPy, MCP
+is. How a session runs on koala (worktrees, rc per repo, the reaper, memory): `docs/working-on-koala.md`.
-- **azure-tiger** (`QKX/`) — invoice extraction → ISO 20022 payment instructions
-- **gocrwl** (`AGENTS/`) — Go web crawler with containerized deployment
-- **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
-- **klimatkollen** (`XT/`) — Swedish municipal climate data platform
 
 ## Knowledge base — actively use it
 
@@ -514,4 +566,16 @@ When acting as a coding agent on this project:
 5. When adding a dependency, explain why in the commit message
 6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
 
+## `main` is protected: ship by PR (local-dev#42, decided 2026-10-08)
+
+Gitea refuses direct pushes to `main` in this repo, and a PR merges only after its CI status (`CI / Lint / Test / Vet (pull_request)`) passes.
+**Why:** local-dev rule 5's reviewed lane (risk/medium+ is reviewed by a human) was enforced on the merge tools
+(`tbd_ship`, `pr_merge`: gitea-mcp v0.17.0/v0.18.0, merge only for an issue labelled exactly `risk/low` with green CI)
+but not on a direct commit to `main`, which bypassed it. This overrides rule 5's "risk/low commits straight to main"
+for this repo; control code is where the lane matters.
+**How:** `tbd_ship` for a one-file change, or branch -> PR -> `pr_merge` (name the `risk/low` issue); above `risk/low`
+open the PR and a human merges it in the Gitea UI after review. Tags are not protected. CD jobs push image tags to
+the **infra** repo with deploy keys, never to this repo's `main`. Undo (Mathias only): Settings -> Branches, or
+`PATCH /repos/mathias/hyperguild/branch_protections/main {"enable_push": true}`.
+
 ---

AGENTS.md

@@ -159,6 +159,63 @@ These rules apply to every task across every project, regardless of harness.
    the thing it was named for was exploitable. If you cannot name the mechanism,
    you do not yet know what the test observes.
 
+10. **Short sessions, one rc per repo, edit only in a locked worktree of the repo
+   you are changing** (ADR-0002, accepted 2026-10-06).
+   - One session per issue or task, ending with rule 6's close ritual. Related
+     issues may share a session only when they share a worktree and an owner.
+     State that must outlive the session goes in an issue, not the chat.
+   - Start `claude rc` in the repo you will edit (`infra`, `trucker-ecommerce`,
+     `hyperguild`, ...), not in `~/dev`: the rc worktree is a worktree of the
+     launch directory's repo, so launched from `~/dev` it protects nothing you
+     edit (measured: 73% of edits landed in shared checkouts). Start it only
+     while working there.
+   - Keep at most one thin `~/dev` coordinator session. It files issues and hands
+     out tasks; it reads and edits no sub-repo code.
+   - Split cross-repo work per repo. The contract between the halves lives in an
+     issue on each repo.
+   - Edit in a worktree of that repo, locked at creation:
+     `scripts/wt.sh add <repo> <task>` does it (fetch, `wt/<task>` from origin/main, lock);
+     `scripts/wt.sh done <repo>-<task>` removes it after the push and refuses dirty or
+     unpushed work. By hand: `git worktree add ~/worktrees/<name> -b <branch> origin/main`
+     then `git worktree lock --reason "manual: <purpose>" ~/worktrees/<name>`.
+   - Before working a repo another session may touch, announce your issue list to
+     that session (`SendMessage`) and ask for theirs.
+   - Auto-memory is keyed by cwd, so a repo rc starts without it. Cross-repo
+     working rules live in brain (`wiki/homelab/decisions/2026-10-06-062416-auto.md`, wing homelab, hall
+     decisions) and the section below, not in per-directory memory.
+
+## Standing footguns
+
+Each cost real time once. Detail and evidence: brain `wiki/homelab/decisions/2026-10-06-062416-auto.md` (title standing-working-rules).
+
+- **Gate then commit with `&&`, never `;`.** "Green" means exit code 0 and
+  `grep -c FAIL` is 0, not a filtered grep.
+- **Stage by path, never `git add -A` or `git add .`** (they stage from the repo
+  root and swept in other sessions' work twice). Check `git status --porcelain` first.
+- **Before committing in a shared checkout:** `git branch --show-current`.
+- **Before tagging:** `git fetch origin --tags`, then `git describe --tags --abbrev=0 <sha>`
+  and `git tag --sort=-v:refname | head`; go above both. Never take the last tag
+  from a report.
+- **Run only what the project's gate runs.** No repo-wide formatter unless the gate
+  runs it.
+- **Reproduce a CI red at the cited commit before applying an issue's prescribed fix.**
+- **Read an issue's comments (`issue_list_comments`), not just its body, before working it.**
+- **A comment naming a control ("behind branch protection") is not evidence; query
+  the control.** A working detector can hide a missing preventer.
+- **On koala the MCP servers are `mcp__plugin_skills_{brain,gitea,infra}__*`.** The
+  per-turn auth reminder is not evidence; call the tool or run `claude mcp list`.
+  Brain writes always pass `wing` + `hall`.
+- **`cat /etc/hostname` before assuming which host you are on.**
+- **Never run bare `git remote -v` or `git config --list`** (url.insteadOf expands
+  into a live token); use `git config --get remote.origin.url`.
+- **On koala `sudo` is denied outright; k8s exec, env dumps and flux reconcile need
+  per-action approval; decrypting a SOPS file and printing in one Bash call is
+  hook-blocked.** Do the repo-side work and hand the host-side step over in an issue.
+- **`set -o pipefail` plus an optional `grep | head | awk` dies on no match:** append `|| true`.
+- **Gitea `file_write_branch` takes plain text, not base64.**
+- **`OP_SERVICE_ACCOUNT_TOKEN` in the shell is read-only for `op`.** Operational
+  secrets go in the AgentSecrets vault via `set -a; . ~/.op-agent-write.env; set +a`.
+
 ## CAD sprint patterns
 
 Two CAD sprint archetypes (defs: brain `wiki/homelab/decisions/continuous-agentic-development-cad-concept-2026-06-16`):
@@ -239,25 +296,20 @@ Three machines on Tailscale:
 
 All development repos live at `~/dev/` (softlink from `~/Documents/local-dev/`).
 
-Organized in thematic folders:
+Organized by **role**, because the role decides which rules apply (ADR-0003):
 
-| Folder | Focus | Count |
+| Folder | Role | Rules that key off it |
-|--------|-------|-------|
+|--------|------|-----------------------|
-| `GO/` | Go web frameworks, API integrations, learning projects | ~10 |
+| `platform/` | infra, brain, hyperguild, gitea-mcp, dispatch, shared tooling | control code (rule 8), GitOps review lane |
-| `AI/` | ML research, AI frameworks (FinRL, DSPy, crawl4ai) | ~6 |
+| `products/` | tapir, cobalt-dingo, openbanking-api, ... | ordinary trunk-based work |
-| `AGENTS/` | Autonomous agents, coding agents, MCP servers, infra | ~15 |
+| `clients/` | client work | local models only, never cloud APIs (Client work rules) |
-| `QKX/` | Invoice processing, financial automation, payment systems | ~13 |
+| `spikes/` | throwaway | no ceremony |
-| `XT/` | Climate data, sustainability (Klimatkollen, Garbo) | ~2 |
 
-See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
+New projects are born into a role folder (`task new-project -- <name> <client|personal>
-
+<role-folder>`); a client tag requires `clients/` and `clients/` requires a client tag.
-### Key active projects
+Existing repos still sit in the old `AGENTS/` and `AI/` folders until they are moved one by
-
+one (ADR-0003 step 3). `~/dev/PROJECT_SUMMARY.md` (generated) lists every repo and where it
-- **super-koala** (`AGENTS/`) — multi-component agent stack with LangGraph, DSPy, MCP
+is. How a session runs on koala (worktrees, rc per repo, the reaper, memory): `docs/working-on-koala.md`.
-- **azure-tiger** (`QKX/`) — invoice extraction → ISO 20022 payment instructions
-- **gocrwl** (`AGENTS/`) — Go web crawler with containerized deployment
-- **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
-- **klimatkollen** (`XT/`) — Swedish municipal climate data platform
 
 ## Knowledge base — actively use it
 
@@ -508,3 +560,15 @@ When acting as a coding agent on this project:
 4. Never modify files outside the project root without explicit permission
 5. When adding a dependency, explain why in the commit message
 6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
+
+## `main` is protected: ship by PR (local-dev#42, decided 2026-10-08)
+
+Gitea refuses direct pushes to `main` in this repo, and a PR merges only after its CI status (`CI / Lint / Test / Vet (pull_request)`) passes.
+**Why:** local-dev rule 5's reviewed lane (risk/medium+ is reviewed by a human) was enforced on the merge tools
+(`tbd_ship`, `pr_merge`: gitea-mcp v0.17.0/v0.18.0, merge only for an issue labelled exactly `risk/low` with green CI)
+but not on a direct commit to `main`, which bypassed it. This overrides rule 5's "risk/low commits straight to main"
+for this repo; control code is where the lane matters.
+**How:** `tbd_ship` for a one-file change, or branch -> PR -> `pr_merge` (name the `risk/low` issue); above `risk/low`
+open the PR and a human merges it in the Gitea UI after review. Tags are not protected. CD jobs push image tags to
+the **infra** repo with deploy keys, never to this repo's `main`. Undo (Mathias only): Settings -> Branches, or
+`PATCH /repos/mathias/hyperguild/branch_protections/main {"enable_push": true}`.

CLAUDE.md

@@ -84,3 +84,15 @@ When acting as a coding agent on this project:
 4. Never modify files outside the project root without explicit permission
 5. When adding a dependency, explain why in the commit message
 6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
+
+## `main` is protected: ship by PR (local-dev#42, decided 2026-10-08)
+
+Gitea refuses direct pushes to `main` in this repo, and a PR merges only after its CI status (`CI / Lint / Test / Vet (pull_request)`) passes.
+**Why:** local-dev rule 5's reviewed lane (risk/medium+ is reviewed by a human) was enforced on the merge tools
+(`tbd_ship`, `pr_merge`: gitea-mcp v0.17.0/v0.18.0, merge only for an issue labelled exactly `risk/low` with green CI)
+but not on a direct commit to `main`, which bypassed it. This overrides rule 5's "risk/low commits straight to main"
+for this repo; control code is where the lane matters.
+**How:** `tbd_ship` for a one-file change, or branch -> PR -> `pr_merge` (name the `risk/low` issue); above `risk/low`
+open the PR and a human merges it in the Gitea UI after review. Tags are not protected. CD jobs push image tags to
+the **infra** repo with deploy keys, never to this repo's `main`. Undo (Mathias only): Settings -> Branches, or
+`PATCH /repos/mathias/hyperguild/branch_protections/main {"enable_push": true}`.

ingestion/cmd/server/main.go

@@ -179,9 +179,12 @@ func alertingWarnings(getenv func(string) string) []string {
 	return out
 }
 
-func buildNotifier() audit.Notifier {
+// buildNotifier returns the ntfy notifier for one alert source, titled so
-	if n := audit.NewNtfyNotifier(os.Getenv("BRAIN_NTFY_URL"), os.Getenv("BRAIN_NTFY_TOKEN")); n != nil {
+// the source is recognisable (hyperguild#163), or nil when ntfy is not
-		return n
+// configured.
+func buildNotifier(getenv func(string) string, title string) audit.Notifier {
+	if n := audit.NewNtfyNotifier(getenv("BRAIN_NTFY_URL"), getenv("BRAIN_NTFY_TOKEN")); n != nil {
+		return n.WithTitle(title)
 	}
 	return nil
 }
@@ -203,7 +206,7 @@ func buildAuditSink(ctx context.Context, brainDir string, logger *slog.Logger) c
 		logger.Error("capture audit buffer init", "err", err)
 		os.Exit(1)
 	}
-	notifier := buildNotifier()
+	notifier := buildNotifier(os.Getenv, "brain-capture audit degraded")
 	reconcileInterval := time.Duration(envInt("BRAIN_AUDIT_RECONCILE_INTERVAL", 60)) * time.Second
 	audit.StartReconcile(ctx, central, buffer, notifier, reconcileInterval)
 	logger.Info("capture audit: loki+buffer sink", "loki", lokiURL, "reconcile_s", int(reconcileInterval.Seconds()))
@@ -366,7 +369,7 @@ func main() {
 
 	ctx := context.Background()
 	// hyperguild#157: report a symlink that appears in the brain while running.
-	go symlinkguard.Watch(ctx, brainDir, symlinkScanInterval(os.Getenv), buildNotifier())
+	go symlinkguard.Watch(ctx, brainDir, symlinkScanInterval(os.Getenv), buildNotifier(os.Getenv, "brain symlink tripwire"))
 
 	// Never fatal on an unreachable issuer (#83): on a cold cluster boot this
 	// pod can beat dex to serving and get a 502 from ingress, and exiting meant
@@ -546,7 +549,7 @@ func main() {
 		// capture already gets, plus an out-of-band alert. Wired here because
 		// brain_edit_root needs the capture plumbing anyway — that is what
 		// re-derives the static principal its gate checks.
-		mcpSrv.WithGovernanceObserver(auditSink, buildNotifier())
+		mcpSrv.WithGovernanceObserver(auditSink, buildNotifier(os.Getenv, "brain governance edit"))
 		logger.Info("capture enabled (REST + MCP tool)", "sovereign_principals", len(sovereign),
 			"governance_observer", true)
 	} else {

ingestion/cmd/server/routes_test.go

@@ -159,3 +159,16 @@ func TestBuildMuxObservesRequestsAndServesMetrics(t *testing.T) {
 	require.Equal(t, http.StatusOK, code)
 	assert.Contains(t, body, `path="GET /pending"`)
 }
+
+// hyperguild#185: an authenticated request to an unregistered path reached
+// the inner REST mux, which left Pattern empty, and the metrics label fell
+// back to the raw URL path: one Prometheus series per unique path any token
+// holder sends. It is now labelled with a fixed catch-all.
+func TestBuildMuxLabelsAnUnregisteredPathWithAFixedLabel(t *testing.T) {
+	r := testMux(t)
+	code, _ := do(t, r, "GET", "/zqrandom-185-segment", "Bearer "+routesTok)
+	require.Equal(t, http.StatusNotFound, code)
+	_, body := do(t, r, "GET", "/metrics", "")
+	assert.NotContains(t, body, "zqrandom-185-segment", "the raw path became a metrics label")
+	assert.Contains(t, body, `path="unmatched"`)
+}

ingestion/cmd/server/symlink_check_test.go

@@ -1,9 +1,13 @@
 package main
 
 import (
+	"context"
+	"net/http"
+	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"strings"
+	"syscall"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -63,3 +67,26 @@ func TestStartupSymlinkCheckRefusesAnUnlistableBrainRoot(t *testing.T) {
 	t.Cleanup(func() { _ = os.Chmod(brain, 0o755) })
 	assert.Error(t, startupSymlinkCheck(brain))
 }
+
+// hyperguild#179: a FIFO in the brain is refused at startup with a clear
+// message, instead of hanging or exiting later in a reader.
+func TestStartupSymlinkCheckRefusesABrainWithAFIFO(t *testing.T) {
+	brain := t.TempDir()
+	require.NoError(t, syscall.Mkfifo(filepath.Join(brain, "classification.yaml"), 0o644))
+	err := startupSymlinkCheck(brain)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "classification.yaml")
+}
+
+// hyperguild#163: each alert source gets its own ntfy title.
+func TestBuildNotifierUsesTheGivenTitle(t *testing.T) {
+	var got string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { got = r.Header.Get("Title") }))
+	defer srv.Close()
+	env := map[string]string{"BRAIN_NTFY_URL": srv.URL}
+	n := buildNotifier(func(k string) string { return env[k] }, "brain symlink tripwire")
+	require.NotNil(t, n)
+	require.NoError(t, n.Notify(context.Background(), "m"))
+	assert.Equal(t, "brain symlink tripwire", got)
+	assert.Nil(t, buildNotifier(func(string) string { return "" }, "x"), "no ntfy URL, no notifier")
+}

ingestion/go.mod

@@ -68,7 +68,7 @@ require (
 	github.com/segmentio/asm v1.2.0 // indirect
 	golang.org/x/crypto v0.51.0 // indirect
 	golang.org/x/sync v0.21.0 // indirect
-	golang.org/x/sys v0.45.0 // indirect
+	golang.org/x/sys v0.45.0
 	golang.org/x/text v0.39.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1
 )

ingestion/internal/api/handler.go

@@ -12,6 +12,7 @@ import (
 	"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/pipeline"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/search"
@@ -227,14 +228,22 @@ func writeHallNote(brainDir string, opts WriteNoteOptions) (string, error) {
 	// The directory is created only once the note is known to be writable:
 	// a refused write leaves nothing behind, not even an empty hall dir
 	// (brain#21; provenance refusal joins the envelope refusal here).
-	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+	// Created through the brain root, never through a symlinked wing or
-		return "", fmt.Errorf("create hall dir: %w", err)
+	// hall directory (hyperguild#188).
+	rel, err := filepath.Rel(brainDir, dest)
+	if err != nil {
+		return "", fmt.Errorf("note path: %w", err)
 	}
-	if err := os.WriteFile(dest, []byte(final), 0o644); err != nil {
+	rel = filepath.ToSlash(rel)
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return "", fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	if err := bfs.PutRegular(rel, []byte(final)); err != nil {
 		return "", fmt.Errorf("write: %w", err)
 	}
-	rel, _ := filepath.Rel(brainDir, dest)
+	return rel, nil
-	return filepath.ToSlash(rel), nil
 }
 
 // scalarValues flattens frontmatter fields to key -> scalar value for

ingestion/internal/api/promote.go

@@ -127,18 +127,18 @@ func PromoteNote(brainDir string, opts PromoteOptions) (string, error) {
 	}
 	fm.set("promoted_at", now)
 
-	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+	// Write-then-delete: the source survives any write failure. Both go
-		return "", fmt.Errorf("create wing dir: %w", err)
+	// through the brain root (hyperguild#188).
-	}
-	// Write-then-delete: the source survives any write failure.
 	promoted, err := StampProvenance(fm.render()+body, opts.Origin, opts.WrittenBy)
 	if err != nil {
 		return "", err
 	}
-	if err := os.WriteFile(dest, []byte(promoted), 0o644); err != nil {
+	// Created with O_EXCL: a note that appeared after the collision check
+	// above is never overwritten.
+	if err := createBrainFile(brainDir, dest, []byte(promoted)); err != nil {
 		return "", fmt.Errorf("write promoted note: %w", err)
 	}
-	if err := os.Remove(src); err != nil {
+	if err := removeBrainFile(brainDir, src); err != nil {
 		return "", fmt.Errorf("promoted note written but source removal failed: %w", err)
 	}
 
@@ -196,14 +196,12 @@ func RejectNote(brainDir string, opts RejectOptions) (string, error) {
 		fm.set("reject_reason", opts.Reason)
 	}
 
-	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+	// Write-then-delete: the source survives any write failure. Both go
-		return "", fmt.Errorf("create rejected dir: %w", err)
+	// through the brain root (hyperguild#188).
-	}
+	if err := createBrainFile(brainDir, dest, []byte(fm.render()+body)); err != nil {
-	// Write-then-delete: the source survives any write failure.
-	if err := os.WriteFile(dest, []byte(fm.render()+body), 0o644); err != nil {
 		return "", fmt.Errorf("write rejected note: %w", err)
 	}
-	if err := os.Remove(src); err != nil {
+	if err := removeBrainFile(brainDir, src); err != nil {
 		return "", fmt.Errorf("rejected note written but source removal failed: %w", err)
 	}
 

ingestion/internal/api/promote_redirect_test.go

@@ -0,0 +1,87 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// hyperguild#188: promote and reject wrote the destination with
+// os.MkdirAll + os.WriteFile by path, so a symlinked wing (promote) or a
+// symlinked raw/rejected (reject) redirected the note; the raw source was
+// then removed.
+func TestPromoteAndRejectRefuseASymlinkedDestinationDirectory(t *testing.T) {
+	brain := t.TempDir()
+	outside := t.TempDir()
+	raw := filepath.Join(brain, "raw")
+	require.NoError(t, os.MkdirAll(raw, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(raw, "2026-10-05-n.md"), []byte("---\ntitle: n\n---\nbody\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(outside, filepath.Join(brain, "wiki", "lw")))
+	require.NoError(t, os.Symlink(outside, filepath.Join(raw, "rejected")))
+
+	_, err := api.PromoteNote(brain, api.PromoteOptions{Filename: "2026-10-05-n.md", Wing: "lw", Hall: "facts"})
+	assert.Error(t, err)
+	_, err = api.RejectNote(brain, api.RejectOptions{Filename: "2026-10-05-n.md"})
+	assert.Error(t, err)
+	ents, _ := os.ReadDir(outside)
+	assert.Empty(t, ents, "a note was written outside the brain")
+	_, err = os.Stat(filepath.Join(raw, "2026-10-05-n.md"))
+	assert.NoError(t, err, "the raw source is kept when the write is refused")
+
+	require.NoError(t, os.Remove(filepath.Join(raw, "rejected")))
+	_, err = api.PromoteNote(brain, api.PromoteOptions{Filename: "2026-10-05-n.md", Wing: "w", Hall: "facts"})
+	require.NoError(t, err, "positive control: promote into a real wing")
+}
+
+// StampProvenanceFile read and rewrote the note by path (provenance.ApplyFile).
+func TestStampProvenanceFileRefusesANoteBehindASymlinkedDirectory(t *testing.T) {
+	brain := t.TempDir()
+	victim := filepath.Join(brain, "raw", "facts", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("---\ntitle: v\n---\nuntouched\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki", "w"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "facts"), filepath.Join(brain, "wiki", "w", "alias")))
+	assert.Error(t, api.StampProvenanceFile(brain, "wiki/w/alias/v.md", "static", "x"))
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "---\ntitle: v\n---\nuntouched\n", string(got))
+
+	real := filepath.Join(brain, "wiki", "w", "facts", "r.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(real), 0o755))
+	require.NoError(t, os.WriteFile(real, []byte("---\ntitle: r\n---\nbody\n"), 0o644))
+	require.NoError(t, api.StampProvenanceFile(brain, "wiki/w/facts/r.md", "static", "x"), "positive control")
+	got, _ = os.ReadFile(real)
+	assert.Contains(t, string(got), "written_by: x")
+}
+
+// The same through an in-brain symlinked wing and raw/rejected, which
+// os.Root alone would follow.
+func TestPromoteAndRejectRefuseAnInBrainSymlinkedDestinationDirectory(t *testing.T) {
+	brain := t.TempDir()
+	raw := filepath.Join(brain, "raw")
+	require.NoError(t, os.MkdirAll(raw, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(raw, "2026-10-05-n.md"), []byte("---\ntitle: n\n---\nbody\n"), 0o644))
+	target := filepath.Join(brain, "archive")
+	require.NoError(t, os.MkdirAll(target, 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "archive"), filepath.Join(brain, "wiki", "lw")))
+	require.NoError(t, os.Symlink(filepath.Join("..", "archive"), filepath.Join(raw, "rejected")))
+
+	_, err := api.PromoteNote(brain, api.PromoteOptions{Filename: "2026-10-05-n.md", Wing: "lw", Hall: "facts"})
+	assert.Error(t, err)
+	_, err = api.RejectNote(brain, api.RejectOptions{Filename: "2026-10-05-n.md"})
+	assert.Error(t, err)
+	ents, _ := os.ReadDir(target)
+	assert.Empty(t, ents, "a note was written at the in-brain link's target")
+	_, err = os.Stat(filepath.Join(raw, "2026-10-05-n.md"))
+	assert.NoError(t, err, "the raw source is kept")
+
+	require.NoError(t, os.Remove(filepath.Join(raw, "rejected")))
+	_, err = api.RejectNote(brain, api.RejectOptions{Filename: "2026-10-05-n.md"})
+	require.NoError(t, err, "positive control: reject into a real raw/rejected")
+}

ingestion/internal/api/provenance.go

@@ -1,6 +1,10 @@
 package api
 
 import (
+	"fmt"
+	"path/filepath"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/provenance"
 )
 
@@ -11,11 +15,61 @@ func StampProvenance(content, origin, writtenBy string) (string, error) {
 	return provenance.Apply(content, provenance.Stamp{Origin: origin, WrittenBy: writtenBy})
 }
 
-// StampProvenanceFile applies StampProvenance to a brain-relative note path.
+// StampProvenanceFile applies StampProvenance to a brain-relative note path,
+// read and rewritten through the brain root (hyperguild#158).
 func StampProvenanceFile(brainDir, relPath, origin, writtenBy string) error {
-	_, abs, err := resolveWithin(brainDir, relPath)
+	rel, _, err := resolveWithin(brainDir, relPath)
 	if err != nil {
 		return err
 	}
-	return provenance.ApplyFile(abs, provenance.Stamp{Origin: origin, WrittenBy: writtenBy})
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	b, err := bfs.ReadRegular(rel)
+	if err != nil {
+		return fmt.Errorf("read for provenance: %w", err)
+	}
+	out, err := provenance.Apply(string(b), provenance.Stamp{Origin: origin, WrittenBy: writtenBy})
+	if err != nil {
+		return err
+	}
+	if out == string(b) {
+		return nil
+	}
+	if err := bfs.WriteRegular(rel, []byte(out)); err != nil {
+		return fmt.Errorf("write provenance: %w", err)
+	}
+	return nil
+}
+
+// createBrainFile creates the file at abs (inside brainDir) through the
+// brain root and fails if anything is already there.
+func createBrainFile(brainDir, abs string, data []byte) error {
+	rel, err := filepath.Rel(brainDir, abs)
+	if err != nil {
+		return err
+	}
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	return bfs.CreateRegular(filepath.ToSlash(rel), data)
+}
+
+// removeBrainFile removes the file at abs (inside brainDir) through the
+// brain root.
+func removeBrainFile(brainDir, abs string) error {
+	rel, err := filepath.Rel(brainDir, abs)
+	if err != nil {
+		return err
+	}
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	return bfs.Remove(filepath.ToSlash(rel))
 }

ingestion/internal/api/readnote_root_test.go

@@ -23,6 +23,13 @@ func TestReadNoteRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) {
 	_, body, _, err := api.ReadNote(brain, "wiki/w/facts/leak.md")
 	assert.Error(t, err)
 	assert.NotContains(t, body, brainfstest.Sentinel)
+	// A link to a file elsewhere in the brain: os.Root allows it, only the
+	// regular-file check refuses it (hyperguild#171).
+	brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md")))
+	_, body, _, err = api.ReadNote(brain, "wiki/w/facts/inlink.md")
+	assert.Error(t, err)
+	assert.NotContains(t, body, brainfstest.Sentinel)
 
 	p := filepath.Join(facts, "r.md")
 	require.NoError(t, os.WriteFile(p, []byte("---\nx: y\n---\ninside"), 0o644))
@@ -39,5 +46,7 @@ func TestReadNoteRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) {
 		return s
 	}
 	brainfstest.AssertNoLeak(t, p, "---\nx: y\n---\ninside", 1500*time.Millisecond, read)
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	brainfstest.AssertNoLeakFrom(t, p, "---\nx: y\n---\ninside", inBrain, 1500*time.Millisecond, read)
 	brainfstest.AssertNoHang(t, p, "---\nx: y\n---\ninside", 1500*time.Millisecond, 6*time.Second, func() { _ = read() })
 }

ingestion/internal/api/update_redirect_test.go

@@ -0,0 +1,36 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+)
+
+// hyperguild#173: a directory symlink inside wiki/ that points elsewhere in
+// the brain redirected brain_update's write (os.Root follows in-root
+// intermediate symlinks). Every directory above the note must be real.
+func TestUpdateNoteRefusesANoteBehindASymlinkedDirectory(t *testing.T) {
+	brain := t.TempDir()
+	victim := filepath.Join(brain, "raw", "facts", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("---\ntitle: v\n---\nuntouched\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki", "w"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "facts"), filepath.Join(brain, "wiki", "w", "alias")))
+
+	_, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: "wiki/w/alias/v.md", Content: "replaced"})
+	assert.ErrorIs(t, err, brainfs.ErrNotRegular)
+	got, _ := os.ReadFile(victim)
+	assert.Contains(t, string(got), "untouched")
+
+	real := filepath.Join(brain, "wiki", "w", "facts", "r.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(real), 0o755))
+	require.NoError(t, os.WriteFile(real, []byte("---\ntitle: r\n---\nold\n"), 0o644))
+	_, _, _, err = api.UpdateNote(brain, api.UpdateNoteOptions{Path: "wiki/w/facts/r.md", Content: "new"})
+	require.NoError(t, err, "positive control: a note in a real directory is updated")
+}

ingestion/internal/api/write_keeps_learning_test.go

@@ -0,0 +1,34 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// hyperguild#178: an unreadable directory under wiki/ made the link check
+// fail and brain_write refuse the note, losing the learning. The note is now
+// written with its links as given.
+func TestWriteNoteKeepsTheLearningWhenTheLinkCheckCannotIndex(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root ignores directory permissions")
+	}
+	brain := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki", "w", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "w", "facts", "real.md"), []byte("x"), 0o644))
+	locked := filepath.Join(brain, "wiki", "other", "locked")
+	require.NoError(t, os.MkdirAll(locked, 0o755))
+	require.NoError(t, os.Chmod(locked, 0o000))
+	t.Cleanup(func() { _ = os.Chmod(locked, 0o755) })
+
+	rel, err := api.WriteNote(brain, api.WriteNoteOptions{Wing: "w", Hall: "facts", Filename: "n", Content: "learning [[real]] and [[gone]]"})
+	require.NoError(t, err)
+	got, err := os.ReadFile(filepath.Join(brain, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "[[gone]]", "links kept as given when the index is partial")
+}

ingestion/internal/api/write_redirect_test.go

@@ -0,0 +1,43 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// hyperguild#188: brain_write created a new note with os.MkdirAll +
+// os.WriteFile by path, so a symlinked wing directory redirected the note
+// elsewhere in the brain or outside it.
+func TestWriteNoteRefusesASymlinkedWing(t *testing.T) {
+	for name, target := range map[string]func(t *testing.T, brain string) string{
+		"in-brain": func(t *testing.T, brain string) string {
+			require.NoError(t, os.MkdirAll(filepath.Join(brain, "raw"), 0o755))
+			return filepath.Join("..", "raw")
+		},
+		"outside": func(t *testing.T, _ string) string { return t.TempDir() },
+	} {
+		t.Run(name, func(t *testing.T) {
+			brain := t.TempDir()
+			require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki"), 0o755))
+			link := target(t, brain)
+			require.NoError(t, os.Symlink(link, filepath.Join(brain, "wiki", "lw")))
+			_, err := api.WriteNote(brain, api.WriteNoteOptions{Wing: "lw", Hall: "facts", Filename: "n", Content: "learning"})
+			assert.Error(t, err)
+			resolved := link
+			if !filepath.IsAbs(resolved) {
+				resolved = filepath.Join(brain, "wiki", link)
+			}
+			_, serr := os.Stat(filepath.Join(resolved, "facts"))
+			assert.True(t, os.IsNotExist(serr), "a hall was created at the link's target")
+
+			_, err = api.WriteNote(brain, api.WriteNoteOptions{Wing: "w", Hall: "facts", Filename: "n", Content: "learning"})
+			require.NoError(t, err, "positive control: a real wing is written")
+		})
+	}
+}

ingestion/internal/audit/ntfy.go

@@ -13,9 +13,14 @@ import (
 type NtfyNotifier struct {
 	topicURL string
 	token    string
+	title    string
 	http     *http.Client
 }
 
+// defaultNtfyTitle is the title of a notifier built without WithTitle: the
+// capture audit's degraded-state alert, its first user.
+const defaultNtfyTitle = "brain-capture audit degraded"
+
 // NewNtfyNotifier constructs a notifier for the given ntfy topic URL
 // (e.g. https://ntfy.sh/my-topic). token is an optional bearer for
 // protected ntfy instances; it is held here and only sent in the
@@ -27,17 +32,31 @@ func NewNtfyNotifier(topicURL, token string) *NtfyNotifier {
 	return &NtfyNotifier{
 		topicURL: strings.TrimRight(topicURL, "/"),
 		token:    token,
+		title:    defaultNtfyTitle,
 		http:     &http.Client{Timeout: 10 * time.Second},
 	}
 }
 
+// WithTitle returns a copy that sends title as the ntfy Title header, so each
+// alert source (the capture audit, the symlink tripwire, governance edits)
+// is recognisable on the phone (hyperguild#163). A nil notifier (ntfy not
+// configured) stays nil.
+func (n *NtfyNotifier) WithTitle(title string) *NtfyNotifier {
+	if n == nil {
+		return nil
+	}
+	c := *n
+	c.title = title
+	return &c
+}
+
 // Notify posts a message to the ntfy topic.
 func (n *NtfyNotifier) Notify(ctx context.Context, msg string) error {
 	req, err := http.NewRequestWithContext(ctx, http.MethodPost, n.topicURL, strings.NewReader(msg))
 	if err != nil {
 		return err
 	}
-	req.Header.Set("Title", "brain-capture audit degraded")
+	req.Header.Set("Title", n.title)
 	req.Header.Set("Priority", "high")
 	req.Header.Set("Tags", "warning,brain")
 	if n.token != "" {

ingestion/internal/audit/ntfy_title_test.go

@@ -0,0 +1,29 @@
+package audit
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// hyperguild#163: every alert went out titled "brain-capture audit
+// degraded", including the symlink tripwire's and governance alerts.
+func TestNtfyNotifierSendsItsOwnTitle(t *testing.T) {
+	var got []string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		got = append(got, r.Header.Get("Title"))
+	}))
+	defer srv.Close()
+	base := NewNtfyNotifier(srv.URL, "")
+	require.NoError(t, base.Notify(context.Background(), "m"))
+	require.NoError(t, base.WithTitle("brain symlink tripwire").Notify(context.Background(), "m"))
+	require.NoError(t, base.Notify(context.Background(), "m"))
+	assert.Equal(t, []string{"brain-capture audit degraded", "brain symlink tripwire", "brain-capture audit degraded"}, got,
+		"WithTitle returns a copy; the base keeps its default title")
+	var nilN *NtfyNotifier
+	assert.Nil(t, nilN.WithTitle("x"), "nil (ntfy not configured) stays nil")
+}

ingestion/internal/brain/index.go

@@ -7,8 +7,6 @@ import (
 	"fmt"
 	"io"
 	"io/fs"
-	"os"
-	"path/filepath"
 	"sort"
 	"strings"
 	"time"
@@ -32,7 +30,6 @@ func BuildWingIndex(brainDir, wing string) error {
 	if w == "" {
 		return fmt.Errorf("invalid wing %q", wing)
 	}
-	wingDir := filepath.Join(brainDir, "wiki", w)
 	// Listed and read through the brain root (hyperguild#157): a wing or
 	// hall that is a symlink is not followed, and notes are regular files.
 	bfs, err := brainfs.Open(brainDir)
@@ -63,8 +60,9 @@ func BuildWingIndex(brainDir, wing string) error {
 		fmt.Fprintf(&b, "| %s | [%s](%s/%s.md) | %s |\n", e.Hall, e.Title, e.Hall, e.Slug, e.Created)
 	}
 
-	dest := filepath.Join(wingDir, "_index.md")
+	// Written through the brain root, never through a symlinked _index.md
-	return os.WriteFile(dest, []byte(b.String()), 0o644)
+	// (hyperguild#158).
+	return bfs.PutRegular("wiki/"+w+"/_index.md", []byte(b.String()))
 }
 
 // BuildAllWingIndexes regenerates _index.md for every wing under brain/wiki/.

ingestion/internal/brain/linkcheck.go

@@ -47,7 +47,12 @@ var (
 func StripUnresolvedLinks(brainDir, content string) (string, []string, error) {
 	index, err := entryIndex(brainDir)
 	if err != nil {
-		return "", nil, err
+		// A partial index cannot tell an invented link from one into the
+		// part it could not read, so unwrap nothing, and do not refuse the
+		// write either: this runs before every brain_write, and a refused
+		// write is a lost learning (hyperguild#178).
+		slog.Warn("link check skipped: cannot index the brain", "err", err)
+		return content, nil, nil
 	}
 	if len(index) == 0 {
 		return content, nil, nil

ingestion/internal/brain/linkcheck_fallback_test.go

@@ -0,0 +1,41 @@
+package brain_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+)
+
+// hyperguild#178: StripUnresolvedLinks runs before every brain_write and
+// brain_update. An unreadable directory under knowledge/ or wiki/ made it
+// error, the write was refused and the learning lost. When the link index
+// cannot be built, the content is now returned unchanged (no link is
+// unwrapped, none is invented) and no error stops the write.
+func TestStripUnresolvedLinksKeepsContentWhenTheIndexCannotBeBuilt(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", "real.md"), []byte("x"), 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) })
+
+	in := "learning [[real]] and [[gone]]"
+	out, unlinked, err := brain.StripUnresolvedLinks(b, in)
+	require.NoError(t, err)
+	assert.Equal(t, in, out, "content unchanged: no link unwrapped on a partial index")
+	assert.Empty(t, unlinked)
+
+	require.NoError(t, os.Chmod(locked, 0o755))
+	out, _, err = brain.StripUnresolvedLinks(b, in)
+	require.NoError(t, err)
+	assert.NotContains(t, out, "[[gone]]", "positive control: with a readable tree the strip runs")
+}

ingestion/internal/brain/tunnel.go

@@ -5,7 +5,6 @@ import (
 	"errors"
 	"fmt"
 	"io/fs"
-	"os"
 	"path"
 	"path/filepath"
 	"strings"
@@ -176,35 +175,23 @@ func logFuzzyCandidates(brainDir, sourcePath string, cs []TunnelCandidate) error
 	if len(cs) == 0 {
 		return nil
 	}
-	rawDir := filepath.Join(brainDir, "raw")
+	// Appended through the brain root, never through a symlinked raw/ or
-	if err := os.MkdirAll(rawDir, 0o755); err != nil {
+	// log file (hyperguild#158).
-		return err
+	bfs, err := brainfs.Open(brainDir)
-	}
-	stamp := time.Now().UTC().Format("2006-01-02")
-	path := filepath.Join(rawDir, "tunnel-candidates-"+stamp+".md")
-	existed := fileExists(path)
-	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
 	if err != nil {
-		return err
+		return fmt.Errorf("open brain: %w", err)
-	}
-	defer func() { _ = f.Close() }()
-	if !existed {
-		if _, err := f.WriteString("# Tunnel candidates " + stamp + "\n\nFuzzy cross-wing matches surfaced by AutoTunnel. Review and promote to a tunnel via `brain_tunnel` if relevant.\n\n"); err != nil {
-			return err
 	}
+	defer func() { _ = bfs.Close() }()
+	stamp := time.Now().UTC().Format("2006-01-02")
+	rel := "raw/tunnel-candidates-" + stamp + ".md"
+	var buf strings.Builder
+	if _, err := bfs.Lstat(rel); errors.Is(err, fs.ErrNotExist) {
+		buf.WriteString("# Tunnel candidates " + stamp + "\n\nFuzzy cross-wing matches surfaced by AutoTunnel. Review and promote to a tunnel via `brain_tunnel` if relevant.\n\n")
 	}
 	for _, c := range cs {
-		line := fmt.Sprintf("- `%s` ↔ `%s` (term: %q)\n", sourcePath, c.TargetPath, c.MatchedTerm)
+		fmt.Fprintf(&buf, "- `%s` ↔ `%s` (term: %q)\n", sourcePath, c.TargetPath, c.MatchedTerm)
-		if _, err := f.WriteString(line); err != nil {
-			return err
 	}
-	}
+	return bfs.AppendRegular(rel, []byte(buf.String()))
-	return nil
-}
-
-func fileExists(p string) bool {
-	_, err := os.Stat(p)
-	return err == nil
 }
 
 // WriteTunnel appends a bidirectional wikilink between sourcePath and

ingestion/internal/brain/tunnel_redirect_test.go

@@ -0,0 +1,38 @@
+package brain_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+)
+
+// hyperguild#173: brain_tunnel's write followed a directory symlink inside
+// wiki/ that points elsewhere in the brain.
+func TestWriteTunnelRefusesATargetBehindASymlinkedDirectory(t *testing.T) {
+	b := t.TempDir()
+	src := filepath.Join(b, "wiki", "a", "facts", "s.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(src), 0o755))
+	require.NoError(t, os.WriteFile(src, []byte("x\n"), 0o644))
+	victim := filepath.Join(b, "raw", "facts", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "b"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "facts"), filepath.Join(b, "wiki", "b", "facts")))
+
+	assert.ErrorIs(t, brain.WriteTunnel(b, "wiki/a/facts/s.md", "wiki/b/facts/v.md"), brainfs.ErrNotRegular)
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched\n", string(got))
+	got, _ = os.ReadFile(src)
+	assert.Equal(t, "x\n", string(got), "the source is not rewritten either")
+
+	real := filepath.Join(b, "wiki", "c", "facts", "t.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(real), 0o755))
+	require.NoError(t, os.WriteFile(real, []byte("t\n"), 0o644))
+	require.NoError(t, brain.WriteTunnel(b, "wiki/a/facts/s.md", "wiki/c/facts/t.md"), "positive control: a tunnel between real directories is written")
+}

ingestion/internal/brain/writers_redirect_test.go

@@ -0,0 +1,52 @@
+package brain_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+)
+
+// hyperguild#158: BuildWingIndex wrote wiki/<wing>/_index.md with
+// os.WriteFile, so a symlinked _index.md was written through.
+func TestBuildWingIndexDoesNotWriteThroughASymlinkedIndex(t *testing.T) {
+	b := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "w", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(b, "wiki", "w", "facts", "n.md"), []byte("---\ntitle: zqn\n---\n"), 0o644))
+	victim := filepath.Join(b, "raw", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "v.md"), filepath.Join(b, "wiki", "w", "_index.md")))
+	assert.Error(t, brain.BuildWingIndex(b, "w"))
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched", string(got))
+
+	require.NoError(t, os.Remove(filepath.Join(b, "wiki", "w", "_index.md")))
+	require.NoError(t, brain.BuildWingIndex(b, "w"), "positive control")
+	idx, _ := os.ReadFile(filepath.Join(b, "wiki", "w", "_index.md"))
+	assert.Contains(t, string(idx), "zqn")
+}
+
+// AutoTunnel's fuzzy-candidate log appended to raw/tunnel-candidates-*.md
+// with os.OpenFile, so a symlinked raw/ (or log file) was written through.
+func TestAutoTunnelDoesNotAppendTheCandidateLogThroughASymlinkedRaw(t *testing.T) {
+	b := t.TempDir()
+	outside := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "a", "facts"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "b", "facts"), 0o755))
+	// "zq widget" matches as a substring of "zq widgets", a fuzzy candidate.
+	require.NoError(t, os.WriteFile(filepath.Join(b, "wiki", "b", "facts", "t.md"), []byte("---\ntitle: Zq Widget\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(outside, filepath.Join(b, "raw")))
+	_ = brain.AutoTunnel(b, "wiki/a/facts/s.md", "about zq widgets")
+	ents, _ := os.ReadDir(outside)
+	assert.Empty(t, ents, "the candidate log was written outside the brain")
+
+	require.NoError(t, os.Remove(filepath.Join(b, "raw")))
+	require.NoError(t, brain.AutoTunnel(b, "wiki/a/facts/s.md", "about zq widgets"))
+	logs, _ := filepath.Glob(filepath.Join(b, "raw", "tunnel-candidates-*.md"))
+	assert.Len(t, logs, 1, "positive control: the fuzzy candidate is logged in the real raw/")
+}

ingestion/internal/brainfs/brainfs.go

@@ -104,6 +104,17 @@ func (b *Brain) ReadDirRegular(relDir string) ([]string, error) {
 	return names, nil
 }
 
+// cleanRel refuses a path that is not clean and local. realDir checks the
+// cleaned parent, so the I/O must use that same path: os.Root resolves ".."
+// after following a symlink, and a ".." after a symlinked directory would
+// otherwise pass the check and redirect the read or write.
+func cleanRel(rel string) error {
+	if rel == "" || path.Clean(rel) != rel || !filepath.IsLocal(rel) || strings.Contains(rel, "\\") {
+		return fmt.Errorf("%q: not a clean brain-relative path: %w", rel, ErrNotRegular)
+	}
+	return nil
+}
+
 // ReadDirDirs lists the real subdirectories directly in a brain-relative
 // directory, by name. Every component of relDir must be a real directory
 // (ErrNotRegular otherwise); symlinks to directories are left out.
@@ -125,9 +136,149 @@ func (b *Brain) ReadDirDirs(relDir string) ([]string, error) {
 	return names, nil
 }
 
+// PutRegular creates or replaces a regular file at a brain-relative path,
+// for creating writes (hyperguild#188, #158). Missing parent directories are
+// created one component at a time through the root, and every existing
+// component must be a real directory, so a symlinked directory cannot
+// redirect the write elsewhere in the brain or outside it. An existing file
+// is replaced only if it is regular (WriteRegular's checks); a new file is
+// created with O_EXCL and confirmed to be the file that was opened. A
+// directory swapped in after the checks is the #167 residual.
+func (b *Brain) PutRegular(rel string, data []byte) error {
+	if err := cleanRel(rel); err != nil {
+		return err
+	}
+	if err := b.mkdirReal(path.Dir(rel)); err != nil {
+		return err
+	}
+	if _, err := b.root.Lstat(rel); err == nil {
+		return b.WriteRegular(rel, data)
+	} else if !errors.Is(err, fs.ErrNotExist) {
+		return err
+	}
+	return b.createNew(rel, data)
+}
+
+// CreateRegular creates a new regular file at a brain-relative path, with
+// PutRegular's parent rules, and fails with fs.ErrExist if anything is
+// already there: for writers that must never overwrite (promote, reject).
+func (b *Brain) CreateRegular(rel string, data []byte) error {
+	if err := cleanRel(rel); err != nil {
+		return err
+	}
+	if err := b.mkdirReal(path.Dir(rel)); err != nil {
+		return err
+	}
+	return b.createNew(rel, data)
+}
+
+// createNew creates rel with O_EXCL and writes data only after confirming
+// the path is the regular file it created.
+func (b *Brain) createNew(rel string, data []byte) error {
+	f, err := b.root.OpenFile(rel, os.O_WRONLY|os.O_CREATE|os.O_EXCL|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0o644)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = f.Close() }()
+	hfi, herr := f.Stat()
+	lfi, lerr := b.root.Lstat(rel)
+	if herr != nil || lerr != nil || !lfi.Mode().IsRegular() || !os.SameFile(lfi, hfi) {
+		return fmt.Errorf("%s: changed while creating: %w", rel, ErrNotRegular)
+	}
+	if _, err := f.Write(data); err != nil {
+		return err
+	}
+	return f.Close()
+}
+
+// AppendRegular appends data to a regular file at a brain-relative path,
+// creating it (and missing parent directories, as PutRegular does) if it is
+// absent. It writes only after confirming the path is the regular file it
+// opened, so a final symlink or special file, or one swapped in, is refused.
+func (b *Brain) AppendRegular(rel string, data []byte) error {
+	if err := cleanRel(rel); err != nil {
+		return err
+	}
+	if err := b.mkdirReal(path.Dir(rel)); err != nil {
+		return err
+	}
+	if fi, err := b.root.Lstat(rel); err == nil && !fi.Mode().IsRegular() {
+		return fmt.Errorf("%s: %w", rel, ErrNotRegular)
+	} else if err != nil && !errors.Is(err, fs.ErrNotExist) {
+		return err
+	}
+	f, err := b.root.OpenFile(rel, os.O_WRONLY|os.O_APPEND|os.O_CREATE|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0o644)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = f.Close() }()
+	hfi, herr := f.Stat()
+	lfi, lerr := b.root.Lstat(rel)
+	if herr != nil || lerr != nil || !lfi.Mode().IsRegular() || !os.SameFile(lfi, hfi) {
+		return fmt.Errorf("%s: changed while opening: %w", rel, ErrNotRegular)
+	}
+	if _, err := f.Write(data); err != nil {
+		return err
+	}
+	return f.Close()
+}
+
+// Remove removes the file at a clean brain-relative path through the root,
+// refusing a path behind a symlinked directory. A final symlink is removed
+// itself, never its target.
+func (b *Brain) Remove(rel string) error {
+	if err := b.RealParent(rel); err != nil {
+		return err
+	}
+	return b.root.Remove(rel)
+}
+
+// RealParent returns ErrNotRegular unless rel is clean and every directory
+// above it is a real directory, for writers that do their own I/O (an atomic
+// rename) but must not be redirected by a symlinked directory.
+func (b *Brain) RealParent(rel string) error {
+	if err := cleanRel(rel); err != nil {
+		return err
+	}
+	return b.realDir(path.Dir(rel))
+}
+
+// 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.
+func (b *Brain) mkdirReal(rel string) error {
+	if rel == "." {
+		return nil
+	}
+	prefix := ""
+	for _, part := range strings.Split(rel, "/") {
+		prefix = path.Join(prefix, part)
+		fi, err := b.root.Lstat(prefix)
+		if errors.Is(err, fs.ErrNotExist) {
+			if err := b.root.Mkdir(prefix, 0o755); err != nil && !errors.Is(err, fs.ErrExist) {
+				return err
+			}
+			fi, err = b.root.Lstat(prefix)
+		}
+		if err != nil {
+			return err
+		}
+		if !fi.IsDir() {
+			return fmt.Errorf("%s: component %s is not a directory: %w", rel, prefix, ErrNotRegular)
+		}
+	}
+	return nil
+}
+
 // ReadRegular reads a brain-relative path, refusing anything that is not a
 // regular file, both before the open and on the opened handle.
 func (b *Brain) ReadRegular(rel string) ([]byte, error) {
+	if err := cleanRel(rel); err != nil {
+		return nil, err
+	}
+	if err := b.realDir(path.Dir(rel)); err != nil {
+		return nil, err
+	}
 	fi, err := b.root.Lstat(rel)
 	if err != nil {
 		return nil, err
@@ -154,6 +305,12 @@ func (b *Brain) readOpened(rel string) ([]byte, error) { return b.readOpenedMax(
 // ReadRegularMax is ReadRegular with a size limit, checked on the opened
 // handle before reading (max < 0 means no limit).
 func (b *Brain) ReadRegularMax(rel string, max int64) ([]byte, error) {
+	if err := cleanRel(rel); err != nil {
+		return nil, err
+	}
+	if err := b.realDir(path.Dir(rel)); err != nil {
+		return nil, err
+	}
 	fi, err := b.root.Lstat(rel)
 	if err != nil {
 		return nil, err
@@ -256,10 +413,20 @@ func (b *Brain) WalkRegular(relDir string, fn func(rel string) error, onErr func
 // 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 open. Every directory above the file must be a real directory
-// the write inside the brain; hyperguild#167).
+// (hyperguild#173); a directory swapped in after that check is the #167
+// residual.
 func (b *Brain) WriteRegular(rel string, data []byte) error {
-	rel = filepath.ToSlash(rel)
+	if err := cleanRel(rel); err != nil {
+		return err
+	}
+	// Every directory above the file must be real: os.Root follows an
+	// in-brain intermediate symlink, which would redirect the write
+	// elsewhere in the brain (hyperguild#173). A swap after this check is
+	// the #167 residual.
+	if err := b.realDir(path.Dir(rel)); err != nil {
+		return err
+	}
 	lfi, err := b.root.Lstat(rel)
 	if err != nil {
 		return err

ingestion/internal/brainfs/brainfs_test.go

@@ -218,7 +218,7 @@ func TestReadDirRegularListsOnlyRegularFilesAndRefusesSymlinkedComponents(t *tes
 // A final component swapped for a symlink to another regular file in the
 // brain between the Lstat and the open: os.Root follows in-root links, so
 // only comparing the two (os.SameFile) refuses it.
-func TestReadRegularNeverReturnsAnInBrainFileSwappedInBehindASymlink(t *testing.T) {
+func TestReadRegularDoesNotReturnAnInBrainFileSwappedInBehindASymlink(t *testing.T) {
 	dir := t.TempDir()
 	require.NoError(t, os.WriteFile(filepath.Join(dir, "s.md"), []byte("zqsamefilesentinel"), 0o644))
 	p := filepath.Join(dir, "r.md")
@@ -326,3 +326,206 @@ func TestReadDirDirsListsOnlyRealSubdirsAndRefusesSymlinkedComponents(t *testing
 	_, err = b.ReadDirDirs("alias")
 	assert.ErrorIs(t, err, ErrNotRegular)
 }
+
+// hyperguild#173: a file reached through a symlinked directory inside the
+// brain is refused for reads and writes, so a caller-supplied path cannot be
+// redirected to another part of the brain.
+func TestReadAndWriteRegularRefuseAFileBehindASymlinkedDirectory(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "raw", "v.md"), []byte("untouched"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(dir, "wiki", "alias")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	_, err = b.ReadRegular("wiki/alias/v.md")
+	assert.ErrorIs(t, err, ErrNotRegular)
+	_, err = b.ReadRegularMax("wiki/alias/v.md", 100)
+	assert.ErrorIs(t, err, ErrNotRegular)
+	assert.ErrorIs(t, b.WriteRegular("wiki/alias/v.md", []byte("x")), ErrNotRegular)
+	got, _ := os.ReadFile(filepath.Join(dir, "raw", "v.md"))
+	assert.Equal(t, "untouched", string(got))
+	got, err = b.ReadRegular("raw/v.md")
+	require.NoError(t, err, "positive control: the real path still reads")
+	assert.Equal(t, "untouched", string(got))
+}
+
+// realDir checks the cleaned parent, so the I/O must use that same clean
+// path: os.Root resolves ".." after following a symlink, and a ".." placed
+// after a symlinked directory would otherwise pass the check and redirect.
+func TestReadAndWriteRegularRefuseAPathThatIsNotClean(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "raw", "v.md"), []byte("untouched"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw", "facts"), filepath.Join(dir, "wiki", "alias")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	for _, rel := range []string{"wiki/alias/../v.md", "./raw/v.md", "raw//v.md", "/raw/v.md"} {
+		got, err := b.ReadRegular(rel)
+		assert.ErrorIs(t, err, ErrNotRegular, rel)
+		assert.NotContains(t, string(got), "untouched", rel)
+		_, err = b.ReadRegularMax(rel, 100)
+		assert.ErrorIs(t, err, ErrNotRegular, rel)
+		assert.ErrorIs(t, b.WriteRegular(rel, []byte("OVERWRITTEN")), ErrNotRegular, rel)
+	}
+	got, _ := os.ReadFile(filepath.Join(dir, "raw", "v.md"))
+	assert.Equal(t, "untouched", string(got))
+}
+
+// hyperguild#188: PutRegular creates or replaces a regular file through the
+// root. Missing parent directories are created; an existing component that
+// is not a real directory, a final symlink or special file, and an unclean
+// path are refused, and nothing is created at a link's target.
+func TestPutRegularCreatesOrReplacesOnlyThroughRealDirectories(t *testing.T) {
+	dir := t.TempDir()
+	outside := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(dir, "wiki", "inwing")))
+	require.NoError(t, os.Symlink(outside, filepath.Join(dir, "wiki", "outwing")))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "raw", "v.md"), []byte("untouched"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki", "w"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "v.md"), filepath.Join(dir, "wiki", "w", "link.md")))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(dir, "wiki", "w", "f.md"), 0o644))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	for _, rel := range []string{"wiki/inwing/facts/n.md", "wiki/outwing/facts/n.md", "wiki/w/link.md", "wiki/w/f.md", "wiki/w/../../raw/v.md", "/abs.md"} {
+		assert.ErrorIs(t, b.PutRegular(rel, []byte("x")), ErrNotRegular, rel)
+	}
+	ents, _ := os.ReadDir(outside)
+	assert.Empty(t, ents, "nothing created outside the brain")
+	_, err = os.Stat(filepath.Join(dir, "raw", "facts"))
+	assert.True(t, os.IsNotExist(err), "nothing created through the in-brain link")
+	got, _ := os.ReadFile(filepath.Join(dir, "raw", "v.md"))
+	assert.Equal(t, "untouched", string(got))
+
+	require.NoError(t, b.PutRegular("wiki/new/facts/n.md", []byte("one")), "positive control: create with missing parents")
+	got, _ = os.ReadFile(filepath.Join(dir, "wiki", "new", "facts", "n.md"))
+	assert.Equal(t, "one", string(got))
+	require.NoError(t, b.PutRegular("wiki/new/facts/n.md", []byte("two")), "positive control: replace")
+	got, _ = os.ReadFile(filepath.Join(dir, "wiki", "new", "facts", "n.md"))
+	assert.Equal(t, "two", string(got))
+}
+
+func TestAppendRegularCreatesOrAppendsOnlyThroughRealDirectories(t *testing.T) {
+	dir := t.TempDir()
+	outside := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "raw", "v.md"), []byte("untouched"), 0o644))
+	require.NoError(t, os.Symlink(outside, filepath.Join(dir, "outdir")))
+	require.NoError(t, os.Symlink("raw", filepath.Join(dir, "indir")))
+	require.NoError(t, os.Symlink(filepath.Join("raw", "v.md"), filepath.Join(dir, "log.md")))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(dir, "f.md"), 0o644))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	for _, rel := range []string{"outdir/l.md", "indir/v.md", "log.md", "f.md", "raw/../log.md"} {
+		assert.ErrorIs(t, b.AppendRegular(rel, []byte("x")), ErrNotRegular, rel)
+	}
+	ents, _ := os.ReadDir(outside)
+	assert.Empty(t, ents)
+	got, _ := os.ReadFile(filepath.Join(dir, "raw", "v.md"))
+	assert.Equal(t, "untouched", string(got))
+
+	require.NoError(t, b.AppendRegular("logs/a.md", []byte("one\n")), "positive control: create")
+	require.NoError(t, b.AppendRegular("logs/a.md", []byte("two\n")), "positive control: append")
+	got, _ = os.ReadFile(filepath.Join(dir, "logs", "a.md"))
+	assert.Equal(t, "one\ntwo\n", string(got))
+}
+
+func TestRealParentRefusesASymlinkedDirectoryOrUncleanPath(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(dir, "wiki", "alias")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+	assert.ErrorIs(t, b.RealParent("wiki/alias/x.md"), ErrNotRegular)
+	assert.ErrorIs(t, b.RealParent("wiki/../raw/x.md"), ErrNotRegular)
+	assert.NoError(t, b.RealParent("wiki/x.md"), "positive control")
+}
+
+// cleanRel must refuse an unclean path on its own: here the ".." resolves,
+// after a symlinked directory, to a real regular file, so only the clean
+// check stands between the call and that file.
+func TestAppendRegularRefusesAnUncleanPathThatResolvesToARealFile(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw", "keep"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "raw", "v.md"), []byte("untouched"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("raw", "keep"), filepath.Join(dir, "indir")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+	assert.ErrorIs(t, b.AppendRegular("indir/../v.md", []byte("x")), ErrNotRegular)
+	assert.ErrorIs(t, b.PutRegular("indir/../v.md", []byte("x")), ErrNotRegular)
+	got, _ := os.ReadFile(filepath.Join(dir, "raw", "v.md"))
+	assert.Equal(t, "untouched", string(got))
+}
+
+func TestRemoveRefusesAPathBehindASymlinkedDirectoryAndRemovesOnlyTheLink(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "raw", "v.md"), []byte("keep"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(dir, "wiki", "alias")))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw", "v.md"), filepath.Join(dir, "wiki", "link.md")))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "wiki", "n.md"), []byte("n"), 0o644))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	assert.ErrorIs(t, b.Remove("wiki/alias/v.md"), ErrNotRegular)
+	_, err = os.Stat(filepath.Join(dir, "raw", "v.md"))
+	assert.NoError(t, err, "the file behind the symlinked directory is kept")
+	require.NoError(t, b.Remove("wiki/link.md"))
+	_, err = os.Stat(filepath.Join(dir, "raw", "v.md"))
+	assert.NoError(t, err, "removing a final symlink never removes its target")
+	require.NoError(t, b.Remove("wiki/n.md"), "positive control")
+	_, err = os.Stat(filepath.Join(dir, "wiki", "n.md"))
+	assert.True(t, os.IsNotExist(err))
+}
+
+// CreateRegular is the only write path for promote and reject: it creates
+// missing parents through the root, refuses an in-brain symlinked parent and
+// an unclean path, and never replaces anything already there (fs.ErrExist,
+// content unchanged), including a dangling link.
+func TestCreateRegularCreatesOnlyNewFilesThroughRealDirectories(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw", "keep"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(dir, "wiki", "inwing")))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "raw", "v.md"), []byte("untouched"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("raw", "keep"), filepath.Join(dir, "indir")))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "wiki", "exists.md"), []byte("original"), 0o644))
+	require.NoError(t, os.Symlink("nowhere.md", filepath.Join(dir, "wiki", "dangling.md")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	assert.ErrorIs(t, b.CreateRegular("wiki/inwing/facts/n.md", []byte("x")), ErrNotRegular)
+	_, err = os.Stat(filepath.Join(dir, "raw", "facts"))
+	assert.True(t, os.IsNotExist(err), "nothing created through the in-brain link")
+	assert.ErrorIs(t, b.CreateRegular("indir/../v.md", []byte("x")), ErrNotRegular)
+	got, _ := os.ReadFile(filepath.Join(dir, "raw", "v.md"))
+	assert.Equal(t, "untouched", string(got))
+
+	assert.ErrorIs(t, b.CreateRegular("wiki/exists.md", []byte("x")), fs.ErrExist)
+	got, _ = os.ReadFile(filepath.Join(dir, "wiki", "exists.md"))
+	assert.Equal(t, "original", string(got))
+	assert.ErrorIs(t, b.CreateRegular("wiki/dangling.md", []byte("x")), fs.ErrExist)
+	_, err = os.Stat(filepath.Join(dir, "wiki", "nowhere.md"))
+	assert.True(t, os.IsNotExist(err), "nothing created at the dangling link's target")
+
+	require.NoError(t, b.CreateRegular("wiki/new/facts/n.md", []byte("one")), "positive control: create with missing parents")
+	got, _ = os.ReadFile(filepath.Join(dir, "wiki", "new", "facts", "n.md"))
+	assert.Equal(t, "one", string(got))
+}

ingestion/internal/brainfs/brainfstest/brainfstest.go

@@ -1,8 +1,10 @@
 // Package brainfstest is the shared harness for hyperguild#157's swap-race
-// tests: it keeps swapping a regular note, a symlink to an outside file, or a
+// tests: it keeps swapping a regular note, a symlink to a sentinel target file
-// FIFO (with a writer held open) into a path while a reader under test loops.
+// (outside the brain, or inside it for hyperguild#171), or a FIFO (with a
-// It observes two things: no sentinel byte from the outside file reaches the
+// writer held open) into a path while a reader under test loops.
-// reader's output, and the reader returns within a timeout. It does not cover
+// It observes two things, over a sampled window only: no sentinel byte from
+// the target reaches the reader's output, and the reader returns within a
+// timeout. It does not cover
 // hard links, other paths into the reader, or races it does not generate.
 package brainfstest
 
@@ -18,7 +20,7 @@ import (
 	"time"
 )
 
-// Sentinel marks the outside file's contents.
+// Sentinel marks the target file's contents.
 const Sentinel = "zqbrainfssentinelonefiftyseven"
 
 // outsideContent carries Sentinel in every field a reader might extract: the
@@ -141,7 +143,7 @@ func AssertNoLeakFrom(t testing.TB, path, inside, target string, d time.Duration
 		}
 	}
 	if leaks > 0 {
-		t.Fatalf("outside file leaked %d times in %d iterations", leaks, iters)
+		t.Fatalf("symlink target %s leaked %d times in %d iterations", target, leaks, iters)
 	}
 	if n := swaps.Load(); n == 0 {
 		t.Fatalf("no symlink was swapped into %s in %d iterations: the race did not run", path, iters)

ingestion/internal/classification/classification.go

@@ -16,9 +16,10 @@
 package classification
 
 import (
+	"errors"
 	"fmt"
-	"os"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
-	"path/filepath"
+	"io/fs"
 	"strings"
 
 	"gopkg.in/yaml.v3"
@@ -110,9 +111,20 @@ type rawConfig struct {
 func Load(brainDir string) (*Config, error) {
 	cfg := &Config{wings: map[string]Level{}, repos: map[string]Level{}}
 
-	data, err := os.ReadFile(filepath.Join(brainDir, "classification.yaml"))
+	// Read through the brain root, regular files only (hyperguild#157): a
+	// symlinked or special file is not trusted as the config, which is a hard
+	// error like a malformed one.
+	bfs, err := brainfs.Open(brainDir)
+	if errors.Is(err, fs.ErrNotExist) {
+		return cfg, nil
+	}
 	if err != nil {
-		if os.IsNotExist(err) {
+		return nil, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	data, err := bfs.ReadRegular("classification.yaml")
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
 			return cfg, nil
 		}
 		return nil, fmt.Errorf("read classification.yaml: %w", err)

ingestion/internal/classification/root_test.go

@@ -0,0 +1,46 @@
+package classification
+
+import (
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// hyperguild#157 slice 6: Load read classification.yaml with os.ReadFile. It
+// sets the I1 sovereignty levels; a symlinked file must not be trusted as the
+// config (a hard error, as for a malformed file), and a FIFO must not hang
+// startup.
+func TestLoadRefusesASymlinkedOrFIFOClassificationFile(t *testing.T) {
+	ok := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(ok, "classification.yaml"), []byte("wings:\n  w: confidential\n"), 0o644))
+	_, err := Load(ok)
+	require.NoError(t, err, "positive control")
+
+	linked := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(linked, "real.yaml"), []byte("wings:\n  w: public\n"), 0o644))
+	require.NoError(t, os.Symlink("real.yaml", filepath.Join(linked, "classification.yaml")))
+	_, err = Load(linked)
+	assert.Error(t, err, "an in-brain symlink is not trusted as the config")
+
+	fifo := t.TempDir()
+	require.NoError(t, syscall.Mkfifo(filepath.Join(fifo, "classification.yaml"), 0o644))
+	w, err := os.OpenFile(filepath.Join(fifo, "classification.yaml"), os.O_RDWR, 0)
+	require.NoError(t, err)
+	defer func() { _ = w.Close() }()
+	done := make(chan error, 1)
+	go func() { _, err := Load(fifo); done <- err }()
+	select {
+	case err := <-done:
+		assert.Error(t, err)
+	case <-time.After(3 * time.Second):
+		t.Fatal("Load hung on a FIFO")
+	}
+
+	_, err = Load(t.TempDir())
+	assert.NoError(t, err, "an absent file is still not an error")
+}

ingestion/internal/mcp/readexcerpt_root_test.go

@@ -21,6 +21,11 @@ func TestReadExcerptRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) {
 	require.NoError(t, os.MkdirAll(facts, 0o755))
 	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(facts, "leak.md")))
 	assert.NotContains(t, readExcerpt(brain, "wiki/w/facts/leak.md", 500), brainfstest.Sentinel)
+	// A link to a file elsewhere in the brain: os.Root allows it, only the
+	// regular-file check refuses it (hyperguild#171).
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md")))
+	assert.NotContains(t, readExcerpt(brain, "wiki/w/facts/inlink.md", 500), brainfstest.Sentinel)
 
 	p := filepath.Join(facts, "r.md")
 	require.NoError(t, os.WriteFile(p, []byte("---\nx: y\n---\ninside"), 0o644))
@@ -28,6 +33,9 @@ func TestReadExcerptRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) {
 	brainfstest.AssertNoLeak(t, p, "---\nx: y\n---\ninside", 1500*time.Millisecond, func() string {
 		return readExcerpt(brain, "wiki/w/facts/r.md", 500)
 	})
+	brainfstest.AssertNoLeakFrom(t, p, "---\nx: y\n---\ninside", inBrain, 1500*time.Millisecond, func() string {
+		return readExcerpt(brain, "wiki/w/facts/r.md", 500)
+	})
 	brainfstest.AssertNoHang(t, p, "---\nx: y\n---\ninside", 1500*time.Millisecond, 6*time.Second, func() {
 		_ = readExcerpt(brain, "wiki/w/facts/r.md", 500)
 	})

ingestion/internal/metrics/metrics.go

@@ -83,8 +83,9 @@ func (r *Registry) Observe(path, status string, d time.Duration) {
 
 // Middleware wraps next, observing every request's duration + status.
 // The metric label `path` uses the request's Pattern (Go 1.22+ ServeMux),
-// falling back to the URL path if no Pattern is set. Pattern keeps
+// or the fixed label "unmatched" if no Pattern is set: falling back to the
-// cardinality bounded (one series per route, not one per unique URL).
+// raw URL path gave any caller one series per unique path (hyperguild#185).
+// Pattern keeps cardinality bounded (one series per route).
 func (r *Registry) Middleware(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
 		rec := &statusRecorder{ResponseWriter: w, code: http.StatusOK}
@@ -92,7 +93,7 @@ func (r *Registry) Middleware(next http.Handler) http.Handler {
 		next.ServeHTTP(rec, req)
 		path := req.Pattern
 		if path == "" {
-			path = req.URL.Path
+			path = "unmatched"
 		}
 		r.Observe(path, statusClass(rec.code), time.Since(start))
 	})

ingestion/internal/metrics/metrics_test.go

@@ -71,11 +71,16 @@ func TestMiddleware_RecordsTiming(t *testing.T) {
 	t.Parallel()
 
 	r := New()
-	handler := r.Middleware(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+	// Routed through a ServeMux, as in production: the mux sets the
+	// request's Pattern, which is the label (an unrouted request is
+	// "unmatched", hyperguild#185).
+	mux := http.NewServeMux()
+	mux.HandleFunc("/query", func(w http.ResponseWriter, _ *http.Request) {
 		time.Sleep(2 * time.Millisecond)
 		w.WriteHeader(http.StatusOK)
 		_, _ = io.WriteString(w, "ok")
-	}))
+	})
+	handler := r.Middleware(mux)
 
 	srv := httptest.NewServer(handler)
 	defer srv.Close()
@@ -117,3 +122,19 @@ func TestStatusRecorder_DefaultsTo200(t *testing.T) {
 		t.Errorf("code %d, want 200", rec.Code)
 	}
 }
+
+// A request with no matched Pattern is labelled "unmatched", never with its
+// raw URL path (unbounded cardinality, hyperguild#185).
+func TestMiddleware_LabelsAnUnmatchedRequestWithAFixedLabel(t *testing.T) {
+	r := New()
+	h := r.Middleware(http.NotFoundHandler())
+	h.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest("GET", "/zqrandom-185-unit", nil))
+	rec := httptest.NewRecorder()
+	r.Handler().ServeHTTP(rec, httptest.NewRequest("GET", "/metrics", nil))
+	if strings.Contains(rec.Body.String(), "zqrandom-185-unit") {
+		t.Errorf("the raw path became a metrics label:\n%s", rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), `path="unmatched"`) {
+		t.Errorf("no unmatched label:\n%s", rec.Body.String())
+	}
+}

ingestion/internal/notes/edit_redirect_test.go

@@ -0,0 +1,36 @@
+package notes
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// hyperguild#188/#173: brain_edit's atomic rename must not be redirected by
+// a symlinked directory inside the brain.
+func TestEditRefusesANoteBehindASymlinkedDirectory(t *testing.T) {
+	b := t.TempDir()
+	// Edit refuses a tree that is not the sync source before any path
+	// check, so the test needs a .git to reach the symlink refusal.
+	require.NoError(t, os.MkdirAll(filepath.Join(b, ".git"), 0o755))
+	victim := filepath.Join(b, "raw", "facts", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("old text\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "w"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "facts"), filepath.Join(b, "wiki", "w", "alias")))
+	_, err := Edit(b, "wiki/w/alias/v.md", "old text", "new text", ScopeNotes)
+	assert.Error(t, err)
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "old text\n", string(got))
+
+	real := filepath.Join(b, "wiki", "w", "facts", "r.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(real), 0o755))
+	require.NoError(t, os.WriteFile(real, []byte("old text\n"), 0o644))
+	_, err = Edit(b, "wiki/w/facts/r.md", "old text", "new text", ScopeNotes)
+	require.NoError(t, err, "positive control: a note in a real directory is edited")
+	got, _ = os.ReadFile(real)
+	assert.Equal(t, "new text\n", string(got))
+}

ingestion/internal/notes/read_root_test.go

@@ -38,3 +38,31 @@ func TestReadScopedRefusesANoteOverMaxNoteBytes(t *testing.T) {
 	_, err := ReadScoped(brain, "wiki/w/facts/big.md", ScopeNotes)
 	assert.ErrorIs(t, err, ErrTooLarge)
 }
+
+// hyperguild#171 (review of #172, finding 1): os.Root alone refuses links that
+// leave the brain, so the outside-target race above stays green for a reader
+// that skips brainfs's Lstat and SameFile checks. An in-brain target (raw/,
+// outside ScopeNotes) is what tells them apart.
+func TestReadScopedDoesNotReturnAnInBrainSymlinkTargetStaticallyOrDuringASampledSwapRace(t *testing.T) {
+	brain := t.TempDir()
+	facts := filepath.Join(brain, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	target := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md")))
+	b, err := ReadScoped(brain, "wiki/w/facts/inlink.md", ScopeNotes)
+	assert.Error(t, err, "static in-brain link")
+	assert.NotContains(t, string(b), brainfstest.Sentinel, "static in-brain link")
+
+	p := filepath.Join(facts, "r.md")
+	require.NoError(t, os.WriteFile(p, []byte("inside"), 0o644))
+	b, err = ReadScoped(brain, "wiki/w/facts/r.md", ScopeNotes)
+	require.NoError(t, err)
+	assert.Equal(t, "inside", string(b), "positive control: a regular note reads")
+
+	read := func() string {
+		b, _ := ReadScoped(brain, "wiki/w/facts/r.md", ScopeNotes)
+		return string(b)
+	}
+	brainfstest.AssertNoLeakFrom(t, p, "inside", target, 1500*time.Millisecond, read)
+}

ingestion/internal/pipeline/backfill.go

@@ -3,7 +3,10 @@ package pipeline
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
@@ -23,10 +26,16 @@ func BackfillRefs(ctx context.Context, brainDir string) (int, error) {
 		return 0, fmt.Errorf("load inventory: %w", err)
 	}
 
-	sourcesDir := filepath.Join(brainDir, "wiki", "sources")
+	// Listed and read through the brain root, regular files only
-	entries, err := os.ReadDir(sourcesDir)
+	// (hyperguild#157).
+	bfs, err := brainfs.Open(brainDir)
 	if err != nil {
-		if os.IsNotExist(err) {
+		return 0, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	names, err := bfs.ReadDirRegular("wiki/sources")
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
 			return 0, nil
 		}
 		return 0, fmt.Errorf("read sources dir: %w", err)
@@ -37,20 +46,20 @@ func BackfillRefs(ctx context.Context, brainDir string) (int, error) {
 	// get both refs merged before a single write.
 	pending := make(map[string]wiki.Page)
 
-	for _, e := range entries {
+	for _, name := range names {
 		if ctx.Err() != nil {
 			return 0, ctx.Err()
 		}
-		if e.IsDir() || !strings.HasSuffix(e.Name(), ".md") {
+		if !strings.HasSuffix(name, ".md") {
 			continue
 		}
 
-		b, err := os.ReadFile(filepath.Join(sourcesDir, e.Name()))
+		b, err := bfs.ReadRegular("wiki/sources/" + name)
 		if err != nil {
 			continue
 		}
 		sourceContent := string(b)
-		sourceSlug := strings.TrimSuffix(e.Name(), ".md")
+		sourceSlug := strings.TrimSuffix(name, ".md")
 		sourceTitle := extractTitle(sourceContent)
 		if sourceTitle == "" {
 			sourceTitle = sourceSlug
@@ -70,7 +79,7 @@ func BackfillRefs(ctx context.Context, brainDir string) (int, error) {
 			// Start from already-accumulated version if we've seen this page.
 			page, seen := pending[relPath]
 			if !seen {
-				raw, err := os.ReadFile(filepath.Join(brainDir, filepath.FromSlash(relPath)))
+				raw, err := bfs.ReadRegular(relPath)
 				if err != nil {
 					continue
 				}

ingestion/internal/pipeline/pipeline.go

@@ -5,7 +5,10 @@ import (
 	"context"
 	"crypto/sha256"
 	"encoding/hex"
+	"errors"
 	"fmt"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
@@ -129,7 +132,7 @@ func buildAndWrite(ctx context.Context, rawPages []RawPage, sourceSlug, date, br
 			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(dest, page)
+			content, conflicts, err := reviseOrCreate(brainDir, page)
 			if err != nil {
 				return Result{}, err
 			}
@@ -188,14 +191,27 @@ func hashBody(content string) string {
 
 // readSourcePage returns the full on-disk content of the source page at
 // wiki/sources/<sourceSlug>.md, or "" when it doesn't exist yet.
+// It reads through the brain root, regular files only (hyperguild#157): the
+// content goes into the LLM prompt.
 func readSourcePage(brainDir, sourceSlug string) string {
-	raw, err := os.ReadFile(filepath.Join(brainDir, "wiki", "sources", sourceSlug+".md"))
+	raw, err := readBrainFile(brainDir, "wiki/sources/"+sourceSlug+".md")
 	if err != nil {
 		return ""
 	}
 	return string(raw)
 }
 
+// readBrainFile reads one brain-relative file through the brain root,
+// regular files only (hyperguild#157).
+func readBrainFile(brainDir, rel string) ([]byte, error) {
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = bfs.Close() }()
+	return bfs.ReadRegular(rel)
+}
+
 // storedSourceHash reads source_hash from the source page a previous ingest
 // wrote, or "" when there is no such page or no such field.
 //
@@ -230,10 +246,10 @@ func storedSourceHash(brainDir, sourceSlug string) string {
 // its first-ingest date on a revised page. Left deliberately — the alternative
 // is this function editing frontmatter it does not own, and no lint reads that
 // field today.
-func reviseOrCreate(dest string, page wiki.Page) (string, []string, error) {
+func reviseOrCreate(brainDir string, page wiki.Page) (string, []string, error) {
-	existing, err := os.ReadFile(dest)
+	existing, err := readBrainFile(brainDir, page.Path)
 	switch {
-	case os.IsNotExist(err):
+	case errors.Is(err, fs.ErrNotExist):
 		return page.Content, nil, nil
 	case err != nil:
 		return "", nil, fmt.Errorf("read existing %s: %w", page.Path, err)
@@ -267,7 +283,7 @@ See brain/schema.md for the full schema.
 `
 
 func loadSchema(brainDir string) string {
-	b, err := os.ReadFile(filepath.Join(brainDir, "schema.md"))
+	b, err := readBrainFile(brainDir, "schema.md")
 	if err != nil {
 		return defaultSchema
 	}

ingestion/internal/pipeline/refs.go

@@ -2,7 +2,6 @@
 package pipeline
 
 import (
-	"os"
 	"path/filepath"
 	"regexp"
 	"strings"
@@ -53,8 +52,7 @@ func injectSourceRefs(pages []wiki.Page, inventory map[wiki.PageType][]wiki.Entr
 		if !ok {
 			continue
 		}
-		diskPath := filepath.Join(brainDir, "wiki", string(pt), slug+".md")
+		b, err := readBrainFile(brainDir, "wiki/"+string(pt)+"/"+slug+".md")
-		b, err := os.ReadFile(diskPath)
 		if err != nil {
 			continue
 		}

ingestion/internal/pipeline/root_test.go

@@ -0,0 +1,167 @@
+package pipeline
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/wiki"
+)
+
+// hyperguild#157 slice 6: the pipeline read the source page, schema.md, the
+// pages it revises and the pages it adds source refs to with os.ReadFile, so
+// a symlinked file's content reached the LLM prompt and the written pages,
+// and a FIFO hung the ingest.
+
+func mkdirs(t *testing.T, brain string, dirs ...string) {
+	t.Helper()
+	for _, d := range dirs {
+		require.NoError(t, os.MkdirAll(filepath.Join(brain, filepath.FromSlash(d)), 0o755))
+	}
+}
+
+func TestReadSourcePageAndSchemaRefuseSymlinksAndSurviveSwapRaces(t *testing.T) {
+	brain := t.TempDir()
+	mkdirs(t, brain, "wiki/sources")
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "sources", "ok.md"), []byte("zqinside source"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "schema.md"), []byte("zqinside schema"), 0o644))
+	assert.Equal(t, "zqinside source", readSourcePage(brain, "ok"), "positive control")
+	assert.Equal(t, "zqinside schema", loadSchema(brain), "positive control")
+
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(brain, "wiki", "sources", "out.md")))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "s.md"), filepath.Join(brain, "wiki", "sources", "in.md")))
+	assert.NotContains(t, readSourcePage(brain, "out"), brainfstest.Sentinel)
+	assert.NotContains(t, readSourcePage(brain, "in"), brainfstest.Sentinel)
+	assert.NotContains(t, storedSourceHash(brain, "in"), brainfstest.Sentinel)
+
+	src := filepath.Join(brain, "wiki", "sources", "r.md")
+	read := func() string { return readSourcePage(brain, "r") }
+	brainfstest.AssertNoLeak(t, src, "zqinside", 1500*time.Millisecond, read)
+	brainfstest.AssertNoLeakFrom(t, src, "zqinside", inBrain, 1500*time.Millisecond, read)
+	brainfstest.AssertNoHang(t, src, "zqinside", 1500*time.Millisecond, 6*time.Second, func() { _ = read() })
+
+	schema := filepath.Join(brain, "schema.md")
+	rs := func() string { return loadSchema(brain) }
+	brainfstest.AssertNoLeakFrom(t, schema, "zqinside schema", inBrain, 1500*time.Millisecond, rs)
+	brainfstest.AssertNoHang(t, schema, "zqinside schema", 1500*time.Millisecond, 6*time.Second, func() { _ = rs() })
+}
+
+func TestReviseOrCreateRefusesASymlinkedExistingPage(t *testing.T) {
+	brain := t.TempDir()
+	mkdirs(t, brain, "wiki/concepts")
+	brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "s.md"), filepath.Join(brain, "wiki", "concepts", "c.md")))
+	page := wiki.Page{Path: "wiki/concepts/c.md", Content: "---\ntitle: C\n---\nnew\n"}
+	out, _, err := reviseOrCreate(brain, page)
+	assert.Error(t, err)
+	assert.NotContains(t, out, brainfstest.Sentinel)
+
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "concepts", "d.md"), []byte("---\ntitle: D\n---\nzqold\n"), 0o644))
+	out, _, err = reviseOrCreate(brain, wiki.Page{Path: "wiki/concepts/d.md", Content: "---\ntitle: D\n---\nnew\n"})
+	require.NoError(t, err)
+	assert.Contains(t, out, "zqold", "positive control: the existing page is read")
+	out, _, err = reviseOrCreate(brain, wiki.Page{Path: "wiki/concepts/new.md", Content: "fresh"})
+	require.NoError(t, err)
+	assert.Equal(t, "fresh", out, "positive control: a missing page is created")
+}
+
+func TestInjectSourceRefsDoesNotReadASymlinkedPage(t *testing.T) {
+	brain := t.TempDir()
+	mkdirs(t, brain, "wiki/concepts")
+	brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "s.md"), filepath.Join(brain, "wiki", "concepts", "c.md")))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "concepts", "d.md"), []byte("zqinside d"), 0o644))
+	inv := map[wiki.PageType][]wiki.Entry{wiki.PageTypeConcept: {
+		{Slug: "c", Type: wiki.PageTypeConcept}, {Slug: "d", Type: wiki.PageTypeConcept},
+	}}
+	src := wiki.Page{Path: "wiki/sources/src.md", Content: "---\ntitle: Src\n---\nsee [[c|C]] and [[d|D]]\n"}
+	out := injectSourceRefs([]wiki.Page{src}, inv, brain)
+	got := fmt.Sprintf("%+v", out)
+	assert.Contains(t, got, "zqinside d", "positive control")
+	assert.NotContains(t, got, brainfstest.Sentinel)
+}
+
+func TestBackfillRefsSkipsSymlinkedSourcesAndPages(t *testing.T) {
+	brain := t.TempDir()
+	mkdirs(t, brain, "wiki/sources", "wiki/concepts", "raw")
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "concepts", "real.md"), []byte("---\ntitle: R\n---\nbody\n"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "sources", "ok.md"), []byte("---\ntitle: zqinside\n---\n[[real|R]]\n"), 0o644))
+	// A source elsewhere in the brain whose title is the sentinel and which
+	// links the real concept with the [[slug|title]] form the pipeline follows.
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "raw", "src.md"),
+		[]byte("---\ntitle: "+brainfstest.Sentinel+"\n---\n[[real|R]]\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "src.md"), filepath.Join(brain, "wiki", "sources", "in.md")))
+	// A concept page linked by the regular source that is itself a symlink.
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "sources", "ok2.md"), []byte("---\ntitle: Two\n---\n[[lnk|L]]\n"), 0o644))
+	brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "page.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "page.md"), filepath.Join(brain, "wiki", "concepts", "lnk.md")))
+
+	_, err := BackfillRefs(context.Background(), brain)
+	require.NoError(t, err)
+	b, _ := os.ReadFile(filepath.Join(brain, "wiki", "concepts", "real.md"))
+	assert.Contains(t, string(b), "zqinside", "positive control: the regular source's ref is added")
+	assert.NotContains(t, string(b), brainfstest.Sentinel, "a symlinked source's title was written as a ref")
+	raw, _ := os.ReadFile(filepath.Join(brain, "raw", "page.md"))
+	assert.NotContains(t, string(raw), "[[ok2", "the symlinked concept page's target was rewritten")
+}
+
+// A source swapped between a regular file and a symlink to an in-brain source
+// whose title is the sentinel: the read refuses the swapped-in link, so the
+// sentinel never lands in the concept page as a ref.
+func TestBackfillRefsDoesNotWriteARefFromASourceSwappedInBehindASymlink(t *testing.T) {
+	brain := t.TempDir()
+	mkdirs(t, brain, "wiki/sources", "wiki/concepts", "raw")
+	realPage := filepath.Join(brain, "wiki", "concepts", "real.md")
+	target := filepath.Join(brain, "raw", "src.md")
+	require.NoError(t, os.WriteFile(target, []byte("---\ntitle: "+brainfstest.Sentinel+"\n---\n[[real|R]]\n"), 0o644))
+	src := filepath.Join(brain, "wiki", "sources", "r.md")
+	inside := "---\ntitle: zqinside\n---\n[[real|R]]\n"
+	read := func() string {
+		_ = os.WriteFile(realPage, []byte("---\ntitle: R\n---\nbody\n"), 0o644)
+		_, _ = BackfillRefs(context.Background(), brain)
+		b, _ := os.ReadFile(realPage)
+		return string(b)
+	}
+	require.NoError(t, os.WriteFile(src, []byte(inside), 0o644))
+	require.Contains(t, read(), "zqinside", "positive control")
+	brainfstest.AssertNoLeakFrom(t, src, inside, target, 1500*time.Millisecond, read)
+}
+
+// A concept page that is regular when the inventory lists it, then swapped
+// for a symlink to an in-brain file before BackfillRefs reads it: only the
+// page read's own check refuses it (a static symlink never gets this far,
+// because LoadInventory does not list it).
+func TestBackfillRefsDoesNotCopyAPageSwappedInBehindASymlink(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")
+	inside := "---\ntitle: C\n---\nzqinside\n"
+	read := func() string {
+		// The write path still follows a swapped-in link (#158) and can
+		// overwrite the target, so restore it each round.
+		_ = os.WriteFile(target, []byte("---\ntitle: X\n---\n"+brainfstest.Sentinel+"\n"), 0o644)
+		_, _ = BackfillRefs(context.Background(), brain)
+		f, err := os.OpenFile(page, os.O_RDONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0)
+		if err != nil {
+			return ""
+		}
+		defer func() { _ = f.Close() }()
+		b, _ := io.ReadAll(f)
+		return string(b)
+	}
+	require.NoError(t, os.WriteFile(page, []byte(inside), 0o644))
+	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)
+}

ingestion/internal/provenance/provenance.go

@@ -28,7 +28,6 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"os"
 	"regexp"
 	"strings"
 
@@ -102,25 +101,6 @@ func Apply(content string, s Stamp) (string, error) {
 	return out, nil
 }
 
-// ApplyFile applies the stamp to the note at absPath in place.
-func ApplyFile(absPath string, s Stamp) error {
-	b, err := os.ReadFile(absPath)
-	if err != nil {
-		return fmt.Errorf("read for provenance: %w", err)
-	}
-	out, err := Apply(string(b), s)
-	if err != nil {
-		return err
-	}
-	if out == string(b) {
-		return nil
-	}
-	if err := os.WriteFile(absPath, []byte(out), 0o644); err != nil {
-		return fmt.Errorf("write provenance: %w", err)
-	}
-	return nil
-}
-
 // plainGroups keeps the provably plain key groups of a frontmatter block.
 func plainGroups(block string) string {
 	lines := strings.Split(strings.TrimSuffix(block, "\n"), "\n")

ingestion/internal/search/brainroot_test.go

@@ -12,6 +12,8 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest"
 )
 
 // hyperguild#157 option 1: search walked and read the brain by path, so a
@@ -189,3 +191,49 @@ func TestHydrateRefusesASymlink(t *testing.T) {
 	assert.Error(t, err)
 	assert.NotContains(t, r.Excerpt, sentinel157)
 }
+
+// hyperguild#171: os.Root refuses links that leave the brain on its own, so
+// the outside-target cases above would stay green for a caller that read
+// without brainfs's Lstat and SameFile checks. These targets are inside the
+// brain (raw/, which is not a search root).
+func inBrainTarget(t *testing.T, brain string) string {
+	t.Helper()
+	return brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+}
+
+func TestQueryDoesNotReturnAnInBrainSymlinkTargetDuringASampledSwapRace(t *testing.T) {
+	brain, facts, _ := searchBrain(t)
+	target := inBrainTarget(t, brain)
+	read := func() string {
+		// Both terms, so the regular note is a possible hit: a reader that
+		// never returns the inside note would pass vacuously (#177 floor).
+		rs, _ := Query(brain, QueryOptions{Query: brainfstest.Sentinel + " zqinside", Limit: 10})
+		s := ""
+		for _, r := range rs {
+			s += r.Title + r.Excerpt
+		}
+		return s
+	}
+	brainfstest.AssertNoLeakFrom(t, filepath.Join(facts, "r.md"), "# r\n\nzqinside", target, 1500*time.Millisecond, read)
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md")))
+	assert.NotContains(t, read(), brainfstest.Sentinel, "static in-brain link")
+}
+
+func TestHydrateRefusesAnInBrainSymlinkAndDoesNotReturnItsTargetDuringASampledSwapRace(t *testing.T) {
+	brain, facts, _ := searchBrain(t)
+	target := inBrainTarget(t, brain)
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md")))
+	r, err := hydrate(brain, "wiki/w/facts/inlink.md")
+	assert.Error(t, err)
+	assert.NotContains(t, r.Excerpt+r.Title, brainfstest.Sentinel)
+
+	p := filepath.Join(facts, "r.md")
+	require.NoError(t, os.WriteFile(p, []byte("# r\n\nzqinside"), 0o644))
+	r, err = hydrate(brain, "wiki/w/facts/r.md")
+	require.NoError(t, err)
+	assert.Contains(t, r.Excerpt, "zqinside", "positive control: a regular note hydrates")
+	brainfstest.AssertNoLeakFrom(t, p, "# r\n\nzqinside", target, 1500*time.Millisecond, func() string {
+		r, _ := hydrate(brain, "wiki/w/facts/r.md")
+		return r.Title + r.Excerpt
+	})
+}

ingestion/internal/session/id_test.go

@@ -2,14 +2,17 @@ package session
 
 import (
 	"errors"
+	"fmt"
 	"os"
 	"path/filepath"
+	"sync/atomic"
 	"syscall"
 	"testing"
 	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"golang.org/x/sys/unix"
 )
 
 // session_log passed the caller's session_id straight into
@@ -90,3 +93,85 @@ func TestAppendReturnsPromptlyOnAFIFOLogWithNoReader(t *testing.T) {
 		t.Fatal("Append blocked on a FIFO log with no reader")
 	}
 }
+
+// hyperguild#173: session_log followed a symlinked sessions dir.
+func TestAppendRefusesASymlinkedSessionsDir(t *testing.T) {
+	root := t.TempDir()
+	elsewhere := filepath.Join(root, "elsewhere")
+	require.NoError(t, os.MkdirAll(elsewhere, 0o755))
+	dir := filepath.Join(root, "sessions")
+	require.NoError(t, os.Symlink("elsewhere", dir))
+	assert.Error(t, Append(dir, "s", Entry{SessionID: "s"}))
+	ents, _ := os.ReadDir(elsewhere)
+	assert.Empty(t, ents, "a log was created through the symlinked dir")
+}
+
+// The sessions dir is swapped (RENAME_EXCHANGE) with a symlink to a
+// directory outside the brain while Append runs. Append opens through an
+// os.Root on the sessions dir's parent, so a swap can redirect it only
+// inside that parent (the #167 residual), never outside it.
+func TestAppendNeverCreatesALogOutsideTheParentUnderADirSwapRace(t *testing.T) {
+	brain := t.TempDir()
+	outside := t.TempDir()
+	dir := filepath.Join(brain, "sessions")
+	other := filepath.Join(brain, "sessions.link")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	require.NoError(t, os.Symlink(outside, other))
+	var stop atomic.Bool
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		for !stop.Load() {
+			_ = unix.Renameat2(unix.AT_FDCWD, dir, unix.AT_FDCWD, other, unix.RENAME_EXCHANGE)
+		}
+	}()
+	ok := 0
+	for i := 0; i < 20000; i++ {
+		if Append(dir, fmt.Sprintf("s%d", i), Entry{SessionID: "s"}) == nil {
+			ok++
+		}
+	}
+	stop.Store(true)
+	<-done
+	ents, _ := os.ReadDir(outside)
+	assert.Empty(t, ents, "logs were created outside the brain")
+	assert.Positive(t, ok, "positive control: appends to the real dir succeed")
+}
+
+// The log file is swapped between a regular file and a symlink to another
+// file in the brain while Append runs: Append writes only after confirming
+// the path is the regular file it opened, so the other file never grows.
+func TestAppendNeverWritesThroughALogSwappedForASymlink(t *testing.T) {
+	brain := t.TempDir()
+	dir := filepath.Join(brain, "sessions")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	victim := filepath.Join(brain, "victim.md")
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	log := filepath.Join(dir, "s.jsonl")
+	var stop atomic.Bool
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		tmp := log + ".swap"
+		for i := 0; !stop.Load(); i++ {
+			_ = os.Remove(tmp)
+			if i%2 == 0 {
+				_ = os.WriteFile(tmp, nil, 0o644)
+			} else {
+				_ = os.Symlink(filepath.Join("..", "victim.md"), tmp)
+			}
+			_ = os.Rename(tmp, log)
+		}
+	}()
+	ok := 0
+	for i := 0; i < 20000; i++ {
+		if Append(dir, "s", Entry{SessionID: "s"}) == nil {
+			ok++
+		}
+	}
+	stop.Store(true)
+	<-done
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched\n", string(got), "a log line was written through the swapped-in symlink")
+	assert.Positive(t, ok, "positive control: appends to the regular log succeed")
+}

ingestion/internal/session/session.go

@@ -65,14 +65,42 @@ func Append(sessionsDir, sessionID string, entry Entry) error {
 	if err := checkID(sessionID); err != nil {
 		return err
 	}
-	if err := os.MkdirAll(sessionsDir, 0o755); err != nil {
+	// Opened through an os.Root on the sessions dir's parent (the brain dir),
+	// so a sessions dir swapped for a symlink after the check below can
+	// redirect the log only inside that parent, never outside it (#173; the
+	// in-brain swap is the #167 residual).
+	parentDir, name := filepath.Dir(sessionsDir), filepath.Base(sessionsDir)
+	if err := os.MkdirAll(parentDir, 0o755); err != nil {
+		return fmt.Errorf("create sessions parent: %w", err)
+	}
+	root, err := os.OpenRoot(parentDir)
+	if err != nil {
+		return fmt.Errorf("open sessions parent: %w", err)
+	}
+	defer func() { _ = root.Close() }()
+	if err := root.Mkdir(name, 0o755); err != nil && !errors.Is(err, fs.ErrExist) {
 		return fmt.Errorf("create sessions dir: %w", err)
 	}
-	path := filepath.Join(sessionsDir, sessionID+".jsonl")
+	// The sessions dir itself must be a real directory, not a symlink that
-	f, err := os.OpenFile(path, os.O_CREATE|os.O_APPEND|os.O_WRONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0o644)
+	// redirects the log elsewhere (hyperguild#173).
+	if fi, err := root.Lstat(name); err != nil {
+		return fmt.Errorf("stat sessions dir: %w", err)
+	} else if !fi.IsDir() {
+		return fmt.Errorf("sessions dir %s is not a real directory", sessionsDir)
+	}
+	logRel := name + "/" + sessionID + ".jsonl"
+	f, err := root.OpenFile(logRel, os.O_CREATE|os.O_APPEND|os.O_WRONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0o644)
 	if err != nil {
 		return fmt.Errorf("open session log: %w", err)
 	}
+	// os.Root follows an in-root final symlink even with O_NOFOLLOW, so
+	// confirm, before writing, that the path is the regular file we opened.
+	hfi, herr := f.Stat()
+	lfi, lerr := root.Lstat(logRel)
+	if herr != nil || lerr != nil || !lfi.Mode().IsRegular() || !os.SameFile(lfi, hfi) {
+		_ = f.Close()
+		return fmt.Errorf("session log %s is not a regular file", logRel)
+	}
 
 	line, err := json.Marshal(entry)
 	if err != nil {

ingestion/internal/symlinkguard/special_test.go

@@ -0,0 +1,104 @@
+package symlinkguard
+
+import (
+	"context"
+	"net"
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// hyperguild#179: the tripwire looked only for symlinks, so a FIFO (or
+// socket) in the brain passed it. A FIFO at classification.yaml then made
+// startup exit; at a note path it could hang readers that skip the handle
+// check.
+func TestScanReportsFIFOsAndSocketsAsSpecialFiles(t *testing.T) {
+	brain := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki", "w"), 0o755))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(brain, "classification.yaml"), 0o644))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(brain, "wiki", "w", "f.md"), 0o644))
+	l, err := net.Listen("unix", filepath.Join(brain, "s.sock"))
+	require.NoError(t, err)
+	defer func() { _ = l.Close() }()
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "wiki", "w", "n.md"), []byte("n"), 0o644))
+
+	r, err := Scan(brain)
+	require.NoError(t, err)
+	assert.Equal(t, []string{"classification.yaml", "s.sock", "wiki/w/f.md"}, r.Special)
+	assert.False(t, r.Clean())
+	assert.Contains(t, r.String(), "special file")
+}
+
+// Watch removes a FIFO as it removes symlinks, and leaves a regular file
+// (which Scan never reports) alone.
+func TestWatchRemovesAFIFOAndLeavesAnUnreportedRegularFile(t *testing.T) {
+	brain := t.TempDir()
+	fifo := filepath.Join(brain, "f.md")
+	require.NoError(t, syscall.Mkfifo(fifo, 0o644))
+	regular := filepath.Join(brain, "n.md")
+	require.NoError(t, os.WriteFile(regular, []byte("n"), 0o644))
+	n := &recNotifier{}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go Watch(ctx, brain, 10*time.Millisecond, n)
+	require.Eventually(t, func() bool {
+		_, err := os.Lstat(fifo)
+		return os.IsNotExist(err)
+	}, 2*time.Second, 10*time.Millisecond, "the FIFO is removed")
+	require.Eventually(t, func() bool { return n.count() >= 1 }, 2*time.Second, 10*time.Millisecond)
+	b, err := os.ReadFile(regular)
+	require.NoError(t, err)
+	assert.Equal(t, "n", string(b))
+	n.mu.Lock()
+	defer n.mu.Unlock()
+	assert.Contains(t, n.msgs[0], "f.md")
+}
+
+// removeSpecial re-checks the type: a path that is a regular file or a
+// directory at the re-check is not removed. (A swap between the re-check and
+// the unlink can still remove one; Linux has no conditional unlink. The same
+// window exists in removeSymlinks.)
+func TestRemoveSpecialRefusesRegularFilesAndDirectories(t *testing.T) {
+	brain := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "n.md"), []byte("n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "d"), 0o755))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(brain, "f.md"), 0o644))
+	removed, failed := removeSpecial(brain, []string{"n.md", "d", "f.md"})
+	assert.Equal(t, []string{"f.md"}, removed)
+	assert.Equal(t, []string{"n.md", "d"}, failed)
+	_, err := os.Stat(filepath.Join(brain, "n.md"))
+	assert.NoError(t, err)
+}
+
+// A special file Watch cannot remove (its directory is read-only) stays
+// reported: the persistent-finding alert names it.
+func TestWatchReportsASpecialFileItCannotRemove(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root ignores directory permissions")
+	}
+	brain := t.TempDir()
+	ro := filepath.Join(brain, "ro")
+	require.NoError(t, os.MkdirAll(ro, 0o755))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(ro, "f.md"), 0o644))
+	require.NoError(t, os.Chmod(ro, 0o555))
+	t.Cleanup(func() { _ = os.Chmod(ro, 0o755) })
+	n := &recNotifier{}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go Watch(ctx, brain, 10*time.Millisecond, n)
+	require.Eventually(t, func() bool { return n.count() >= 1 }, 2*time.Second, 10*time.Millisecond)
+	_, err := os.Lstat(filepath.Join(ro, "f.md"))
+	require.NoError(t, err, "the FIFO could not be removed")
+	n.mu.Lock()
+	defer n.mu.Unlock()
+	assert.Contains(t, n.msgs[0], "ro/f.md")
+	assert.Contains(t, n.msgs[0], "special file")
+	for _, m := range n.msgs {
+		assert.NotContains(t, m, "removed", "a file it could not remove was reported as removed")
+	}
+}

ingestion/internal/symlinkguard/symlinkguard.go

@@ -46,10 +46,16 @@ type Notifier interface {
 type Result struct {
 	Symlinks   []string
 	Unreadable []string
+	// Special holds FIFOs, sockets and devices (hyperguild#179): a reader
+	// that opens one by path can hang, and a FIFO at classification.yaml
+	// stops startup.
+	Special []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 }
+func (r Result) Clean() bool {
+	return len(r.Symlinks) == 0 && len(r.Unreadable) == 0 && len(r.Special) == 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.
@@ -59,6 +65,9 @@ func (r Result) String() string {
 	if len(r.Symlinks) > 0 {
 		parts = append(parts, fmt.Sprintf("%d symlink(s): %s", len(r.Symlinks), q(r.Symlinks)))
 	}
+	if len(r.Special) > 0 {
+		parts = append(parts, fmt.Sprintf("%d special file(s) (FIFO, socket or device; delete them): %s", len(r.Special), q(r.Special)))
+	}
 	if len(r.Unreadable) > 0 {
 		parts = append(parts, fmt.Sprintf("%d unreadable dir(s): %s", len(r.Unreadable), q(r.Unreadable)))
 	}
@@ -113,12 +122,16 @@ func Scan(brainDir string) (Result, error) {
 		if d.IsDir() && p == rootGit {
 			return filepath.SkipDir
 		}
-		if d.Type()&os.ModeSymlink != 0 {
+		switch {
+		case d.Type()&os.ModeSymlink != 0:
 			r.Symlinks = append(r.Symlinks, rel)
+		case !d.IsDir() && !d.Type().IsRegular():
+			r.Special = append(r.Special, rel)
 		}
 		return nil
 	})
 	sort.Strings(r.Symlinks)
+	sort.Strings(r.Special)
 	sort.Strings(r.Unreadable)
 	if walkErr != nil {
 		// Only the root's own error reaches here (deeper errors are recorded
@@ -182,14 +195,20 @@ func Watch(ctx context.Context, brainDir string, interval time.Duration, n Notif
 				q.push(fmt.Sprintf("brain symlink tripwire (hyperguild#157): removed %d symlink(s) from the brain dir: %s",
 					len(removed), Result{}.quoted(removed)))
 			}
-			key = Result{Symlinks: failed, Unreadable: r.Unreadable}.String()
+			sRemoved, sFailed := removeSpecial(brainDir, r.Special)
+			if len(sRemoved) > 0 {
+				slog.Error("brain symlink tripwire removed special files", "count", len(sRemoved))
+				q.push(fmt.Sprintf("brain symlink tripwire (hyperguild#179): removed %d special file(s) (FIFO, socket or device) from the brain dir: %s",
+					len(sRemoved), Result{}.quoted(sRemoved)))
+			}
+			key = Result{Symlinks: failed, Unreadable: r.Unreadable, Special: sFailed}.String()
 		}
 		if key != reported {
 			reported = key
 			if key != "" {
 				slog.Error("brain symlink tripwire", "finding", key)
-				q.push("brain symlink tripwire (hyperguild#157): " + key +
+				q.push("brain symlink tripwire (hyperguild#157, #179): " + key +
-					". Readers may follow symlinks out of the brain; fix them.")
+					". Symlinks can lead readers out of the brain and special files can hang them; remove them.")
 			}
 		}
 	}
@@ -322,6 +341,40 @@ func permanent(err error) bool {
 	return errors.As(err, &p) && p.Permanent()
 }
 
+// removeSpecial unlinks each brain-relative FIFO, socket or device through
+// an os.Root on the brain dir, after re-checking that it is still one: a
+// path that is a regular file, a directory or a symlink at the re-check is
+// left alone and reported as failed. The re-check narrows, but cannot close,
+// the window before the unlink (Linux has no conditional unlink); the same
+// window exists in removeSymlinks, and only a local writer can use it.
+func removeSpecial(brainDir string, rels []string) (removed, failed []string) {
+	if len(rels) == 0 {
+		return nil, nil
+	}
+	resolved, err := filepath.EvalSymlinks(brainDir)
+	if err != nil {
+		return nil, rels
+	}
+	root, err := os.OpenRoot(resolved)
+	if err != nil {
+		return nil, rels
+	}
+	defer func() { _ = root.Close() }()
+	for _, rel := range rels {
+		fi, err := root.Lstat(rel)
+		if err != nil || fi.IsDir() || fi.Mode().IsRegular() || fi.Mode()&os.ModeSymlink != 0 {
+			failed = append(failed, rel)
+			continue
+		}
+		if err := root.Remove(rel); err != nil {
+			failed = append(failed, rel)
+			continue
+		}
+		removed = append(removed, rel)
+	}
+	return removed, failed
+}
+
 // removeSymlinks unlinks each brain-relative symlink through an os.Root on
 // the brain dir, after re-checking it is still a symlink. Removing a symlink
 // never touches its target. It returns what was removed and what was not.

ingestion/internal/symlinkguard/symlinkguard_test.go

@@ -381,18 +381,19 @@ func TestWatchQueueIsBoundedDuringAnOutage(t *testing.T) {
 		require.Eventually(t, func() bool { _, err := os.Lstat(link); return os.IsNotExist(err) }, 2*time.Second, 2*time.Millisecond)
 	}
 	n.down.Store(false)
-	require.Eventually(t, func() bool { return n.count() >= 1 }, 2*time.Second, 5*time.Millisecond)
+	// Synchronise on the summary being delivered (hyperguild#193: a fixed
-	time.Sleep(100 * time.Millisecond)
+	// sleep flaked under load); once it is, the queue has been flushed.
-	assert.LessOrEqual(t, n.count(), maxPending+1, "queued alerts plus at most one suppression summary")
+	require.Eventually(t, func() bool {
 		n.mu.Lock()
 		defer n.mu.Unlock()
-	found := false
 		for _, m := range n.msgs {
 			if strings.Contains(m, "suppressed") {
-			found = true
+				return true
 			}
 		}
-	assert.True(t, found, "suppressed alerts are counted in a summary")
+		return false
+	}, 10*time.Second, 5*time.Millisecond, "suppressed alerts are counted in a summary")
+	assert.LessOrEqual(t, n.count(), maxPending+1, "queued alerts plus at most one suppression summary")
 }
 
 // Within the bound, every alert queued during an outage is delivered after
@@ -411,11 +412,21 @@ func TestWatchDeliversEveryQueuedAlertAfterAShortOutage(t *testing.T) {
 		require.Eventually(t, func() bool { _, err := os.Lstat(link); return os.IsNotExist(err) }, 2*time.Second, 2*time.Millisecond)
 	}
 	n.down.Store(false)
-	require.Eventually(t, func() bool { return n.count() == 3 }, 2*time.Second, 5*time.Millisecond)
+	require.Eventually(t, func() bool { return n.count() >= 3 }, 10*time.Second, 5*time.Millisecond)
 	n.mu.Lock()
 	defer n.mu.Unlock()
-	for i, name := range []string{"qa", "qb", "qc"} {
+	// Each removal delivered exactly once, in any order: the outage ends
-		assert.Contains(t, n.msgs[i], strconv.Quote(name))
+	// asynchronously, possibly mid-flush, so a later item can send before an
+	// earlier one (hyperguild#193). Order is not what this test is about.
+	assert.Len(t, n.msgs, 3)
+	for _, name := range []string{"qa", "qb", "qc"} {
+		hits := 0
+		for _, m := range n.msgs {
+			if strings.Contains(m, strconv.Quote(name)) {
+				hits++
+			}
+		}
+		assert.Equal(t, 1, hits, "%s delivered exactly once", name)
 	}
 }
 
@@ -457,29 +468,30 @@ func TestWatchAccountsForEveryRemovalDuringAnOutage(t *testing.T) {
 		require.Eventually(t, func() bool { _, err := os.Lstat(link); return os.IsNotExist(err) }, 2*time.Second, 1*time.Millisecond)
 	}
 	n.down.Store(false)
-	require.Eventually(t, func() bool {
+	// Synchronise on the record being complete, not on a fixed sleep after
+	// the first summary (hyperguild#193): sum every "removed N" alert and
+	// every suppression count until they account for all plants.
+	account := func() (delivered, counted int) {
 		n.mu.Lock()
 		defer n.mu.Unlock()
 		for _, m := range n.msgs {
-			if strings.Contains(m, "suppressed") {
+			var k int
-				return true
+			if i := strings.Index(m, "removed "); i >= 0 && strings.Contains(m, "symlink(s)") {
+				if _, err := fmt.Sscanf(m[i+len("removed "):], "%d", &k); err == nil {
+					delivered += k
 				}
 			}
-		return false
-	}, 2*time.Second, 5*time.Millisecond)
-	time.Sleep(50 * time.Millisecond)
-	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") {
-			_, _ = fmt.Sscanf(m[i+3:], "%d", &counted)
+				if _, err := fmt.Sscanf(m[i+3:], "%d", &k); err == nil {
+					counted += k
 				}
 			}
-	assert.Equal(t, plants, delivered+counted, "delivered %d + counted %d must equal %d removals", delivered, counted, plants)
+		}
+		return delivered, counted
+	}
+	require.Eventually(t, func() bool { d, c := account(); return d+c >= plants }, 10*time.Second, 5*time.Millisecond)
+	d, c := account()
+	assert.Equal(t, plants, d+c, "delivered %d + counted %d must equal %d removals", d, c, plants)
 }
 
 // A poison message is still dropped (others send while it fails), and the

ingestion/internal/vectorstore/sync_root_test.go

@@ -42,6 +42,11 @@ func TestSyncRefusesSymlinkedNotesAndSurvivesSwapRaces(t *testing.T) {
 	brain := t.TempDir()
 	writeNote(t, brain, "wiki/w/facts/ok.md", "inside note")
 	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(brain, "wiki", "w", "facts", "leak.md")))
+	// A link to a file elsewhere in the brain: os.Root allows it, only the
+	// regular-file checks refuse it (hyperguild#171). raw/ is not a scan root,
+	// so its sentinel can only arrive through the link.
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(brain, "wiki", "w", "facts", "inlink.md")))
 
 	emb := &recordingEmbedder{}
 	store := &stubStore{}
@@ -51,6 +56,7 @@ func TestSyncRefusesSymlinkedNotesAndSurvivesSwapRaces(t *testing.T) {
 	assert.NotContains(t, emb.all(), brainfstest.Sentinel)
 	for p := range store.upserts {
 		assert.NotContains(t, p, "leak.md")
+		assert.NotContains(t, p, "inlink.md")
 	}
 
 	p := filepath.Join(brain, "knowledge", "r.md")
@@ -61,6 +67,7 @@ func TestSyncRefusesSymlinkedNotesAndSurvivesSwapRaces(t *testing.T) {
 		return e.all()
 	}
 	brainfstest.AssertNoLeak(t, p, "inside", 1500*time.Millisecond, sync)
+	brainfstest.AssertNoLeakFrom(t, p, "inside", inBrain, 1500*time.Millisecond, sync)
 	brainfstest.AssertNoHang(t, p, "inside", 1500*time.Millisecond, 6*time.Second, func() { _ = sync() })
 }
 

ingestion/internal/wiki/index.go

@@ -3,8 +3,6 @@ package wiki
 
 import (
 	"fmt"
-	"os"
-	"path/filepath"
 	"strings"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
@@ -50,8 +48,8 @@ func RebuildIndex(brainDir, date string) error {
 		sb.WriteString("\n")
 	}
 
-	dest := filepath.Join(brainDir, "wiki", "index.md")
+	// Written through the brain root, never through a symlink (#158).
-	return os.WriteFile(dest, []byte(sb.String()), 0o644)
+	return bfs.PutRegular("wiki/index.md", []byte(sb.String()))
 }
 
 // pageFirstSentence reads the page through the brain root, regular files

ingestion/internal/wiki/log.go

@@ -3,8 +3,7 @@ package wiki
 
 import (
 	"fmt"
-	"os"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
-	"path/filepath"
 	"strings"
 )
 
@@ -27,14 +26,14 @@ func AppendLog(brainDir, source string, pages, warnings []string, date string) e
 	}
 	sb.WriteString("\n")
 
-	logPath := filepath.Join(brainDir, "log.md")
+	// Appended through the brain root, never through a symlink (#158).
-	f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
+	bfs, err := brainfs.Open(brainDir)
 	if err != nil {
-		return fmt.Errorf("open log: %w", err)
+		return fmt.Errorf("open brain: %w", err)
 	}
-	if _, err = f.WriteString(sb.String()); err != nil {
+	defer func() { _ = bfs.Close() }()
-		f.Close() //nolint:errcheck
+	if err := bfs.AppendRegular("log.md", []byte(sb.String())); err != nil {
 		return fmt.Errorf("write log: %w", err)
 	}
-	return f.Close()
+	return nil
 }

ingestion/internal/wiki/writers_redirect_test.go

@@ -0,0 +1,35 @@
+package wiki
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// hyperguild#158: RebuildIndex wrote wiki/index.md and AppendLog appended
+// log.md with os.WriteFile / os.OpenFile, so a symlinked file was written
+// through.
+func TestRebuildIndexAndAppendLogDoNotWriteThroughSymlinks(t *testing.T) {
+	b := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "concepts"), 0o755))
+	victim := filepath.Join(b, "raw", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw", "v.md"), filepath.Join(b, "wiki", "index.md")))
+	require.NoError(t, os.Symlink(filepath.Join("raw", "v.md"), filepath.Join(b, "log.md")))
+
+	assert.Error(t, RebuildIndex(b, "2026-10-05"))
+	assert.Error(t, AppendLog(b, "src", []string{"p"}, nil, "2026-10-05"))
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched", string(got))
+
+	require.NoError(t, os.Remove(filepath.Join(b, "wiki", "index.md")))
+	require.NoError(t, os.Remove(filepath.Join(b, "log.md")))
+	require.NoError(t, RebuildIndex(b, "2026-10-05"), "positive control")
+	require.NoError(t, AppendLog(b, "src", []string{"p"}, nil, "2026-10-05"), "positive control")
+	l, _ := os.ReadFile(filepath.Join(b, "log.md"))
+	assert.Contains(t, string(l), "src")
+}