fix(watcher): park through the brain root, keep a note edited mid-resolve, honour only real fences (#205)

From the second independent review of #207:
- parkForReview now skips the delete when the note changed since it was read
  (an LLM call sits in that window; Syncthing can deliver a newer version)
- parked copies are created via brainfs (real dirs only, O_EXCL, no symlink
  following), so a planted raw/needs-review symlink cannot redirect or hide a
  note; this also removes the need for the guard allowlist entry added in
  1e14c56, which is reverted
- a '----' line no longer closes the proposal block
Each has a test that failed first and a mutant that fails it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.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/jwt_validator.go

@@ -0,0 +1,26 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+
+	chassisauth "git.d-ma.be/mathias/mcp-chassis/auth"
+)
+
+// buildJWTValidator builds the JWT validator for issuer (nil when issuer is
+// empty: JWT auth disabled). Since mcp-chassis v0.7 construction no longer
+// fails when OIDC discovery does (mcp-chassis#4): the issuer resolves lazily,
+// and until it does a JWT is answered 503-and-retry, not 401. That replaces
+// #83's boot-time retry loop (hyperguild#155). An issuer still unresolved at
+// boot is logged, so a misconfigured issuer is visible rather than silent.
+func buildJWTValidator(ctx context.Context, logger *slog.Logger, issuer, audience string) (*chassisauth.JWTValidator, error) {
+	v, err := chassisauth.NewJWTValidator(ctx, issuer, audience)
+	if err != nil {
+		return nil, fmt.Errorf("build jwt validator: %w", err)
+	}
+	if ok, rerr := v.Ready(ctx); !ok {
+		logger.Warn("jwt issuer not resolved at boot; JWTs answer 503 until it is", "issuer", issuer, "err", rerr)
+	}
+	return v, nil
+}

ingestion/cmd/server/jwt_validator_test.go

@@ -0,0 +1,111 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/metrics"
+)
+
+// fakeIssuer answers OIDC discovery with 502 for the first fail requests, as
+// ingress does while dex is not yet serving on a cold boot (#83), then with a
+// real discovery document and an empty JWKS.
+func fakeIssuer(t *testing.T, fail int32) (*httptest.Server, *atomic.Int32) {
+	t.Helper()
+	var discoveries atomic.Int32
+	mux := http.NewServeMux()
+	var srv *httptest.Server
+	mux.HandleFunc("/.well-known/openid-configuration", func(w http.ResponseWriter, _ *http.Request) {
+		if discoveries.Add(1) <= fail {
+			w.WriteHeader(http.StatusBadGateway)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"issuer":"`+srv.URL+`","jwks_uri":"`+srv.URL+`/keys"}`)
+	})
+	mux.HandleFunc("/keys", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"keys":[]}`)
+	})
+	srv = httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	return srv, &discoveries
+}
+
+// #83 retried discovery at boot because chassis v0.2.0 failed construction on
+// a 502. Since chassis v0.7 (mcp-chassis#4) the validator is built anyway and
+// resolves the issuer lazily, so boot no longer waits or exits on it
+// (hyperguild#155). An unresolved issuer is logged at boot.
+func TestBuildJWTValidatorReturnsAValidatorWhileDiscovery502s(t *testing.T) {
+	srv, _ := fakeIssuer(t, 1000)
+	var buf bytes.Buffer
+	v, err := buildJWTValidator(context.Background(), slog.New(slog.NewTextHandler(&buf, nil)), srv.URL, "brain")
+	require.NoError(t, err)
+	assert.NotNil(t, v)
+	assert.Contains(t, buf.String(), "jwt issuer not resolved at boot")
+}
+
+func TestBuildJWTValidatorLogsNothingAgainstAHealthyIssuer(t *testing.T) {
+	srv, _ := fakeIssuer(t, 0)
+	var buf bytes.Buffer
+	v, err := buildJWTValidator(context.Background(), slog.New(slog.NewTextHandler(&buf, nil)), srv.URL, "brain")
+	require.NoError(t, err)
+	assert.NotNil(t, v)
+	assert.NotContains(t, buf.String(), "not resolved")
+}
+
+func TestBuildJWTValidatorIsNilWithoutAnIssuer(t *testing.T) {
+	v, err := buildJWTValidator(context.Background(), slog.New(slog.DiscardHandler), "", "brain")
+	require.NoError(t, err)
+	assert.Nil(t, v)
+}
+
+// With the issuer unresolved, a JWT on a REST route answers 503 (retry), not
+// 401: the token may be fine, the server just cannot check it yet.
+func TestBuildMuxAnswers503ToAJWTWhileTheIssuerIsUnresolved(t *testing.T) {
+	srv, _ := fakeIssuer(t, 1000)
+	v, err := buildJWTValidator(context.Background(), slog.New(slog.DiscardHandler), srv.URL, "brain")
+	require.NoError(t, err)
+	mux, err := buildMux(restAuth{token: routesTok, validator: v, realm: "brain"}, testHandler(t),
+		okHandler("mcp"), metrics.New(), nil)
+	require.NoError(t, err)
+	code, _ := do(t, mux, "GET", "/pending", "Bearer aaa.bbb.ccc")
+	assert.Equal(t, http.StatusServiceUnavailable, code)
+}
+
+// PR #183 review: /mcp shares REST's bearer, but only the static token was
+// asserted on it. With the issuer unresolved, a JWT on /mcp answers 503 too,
+// so /mcp's middleware was built with the JWT validator.
+func TestBuildMuxAnswers503ToAJWTOnMCPWhileTheIssuerIsUnresolved(t *testing.T) {
+	srv, _ := fakeIssuer(t, 1000)
+	v, err := buildJWTValidator(context.Background(), slog.New(slog.DiscardHandler), srv.URL, "brain")
+	require.NoError(t, err)
+	mux, err := buildMux(restAuth{token: routesTok, validator: v, realm: "brain"}, testHandler(t),
+		okHandler("mcp"), metrics.New(), nil)
+	require.NoError(t, err)
+	code, _ := do(t, mux, "POST", "/mcp", "Bearer aaa.bbb.ccc")
+	assert.Equal(t, http.StatusServiceUnavailable, code)
+}
+
+// PR #183 review: a 401 on /mcp names the protected-resource metadata in
+// WWW-Authenticate (what the claude.ai OAuth connector discovers from), so
+// /mcp's middleware was built with resourceMetadataURL.
+func TestBuildMuxMCP401CarriesResourceMetadataInWWWAuthenticate(t *testing.T) {
+	const rm = "https://brain.example/.well-known/oauth-protected-resource"
+	mux, err := buildMux(restAuth{token: routesTok, realm: "brain", resourceMetadataURL: rm}, testHandler(t),
+		okHandler("mcp"), metrics.New(), nil)
+	require.NoError(t, err)
+	rec := httptest.NewRecorder()
+	mux.ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/mcp", nil))
+	require.Equal(t, http.StatusUnauthorized, rec.Code)
+	assert.Contains(t, rec.Header().Get("WWW-Authenticate"), `resource_metadata="`+rm+`"`)
+}

ingestion/cmd/server/main.go

@@ -32,11 +32,11 @@ import (
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/reranker"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/search"
-	"github.com/mathiasbq/hyperguild/ingestion/internal/startupretry"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/symlinkguard"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/vectorstore"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/watcher"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/webhook"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/wing"
 	"k8s.io/client-go/kubernetes"
 	"k8s.io/client-go/rest"
 	"k8s.io/client-go/tools/clientcmd"
@@ -145,6 +145,17 @@ func envInt(key string, fallback int) int {
 	return fallback
 }
 
+// envFloat reads a confidence-style value in [0,1]. Anything unparseable or
+// outside the range falls back: a threshold of 0 would auto-place everything.
+func envFloat(key string, fallback float64) float64 {
+	if v := os.Getenv(key); v != "" {
+		if f, err := strconv.ParseFloat(v, 64); err == nil && f >= 0 && f <= 1 {
+			return f
+		}
+	}
+	return fallback
+}
+
 // buildNotifier returns the ntfy notifier, or a nil interface when
 // BRAIN_NTFY_URL is unset. A nil *interface* (not a typed-nil) is required so
 // DegradingSink/Reconcile and the governance observer skip it cleanly.
@@ -180,9 +191,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
 }
@@ -204,7 +218,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()))
@@ -367,29 +381,17 @@ 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"))
 
-	// Built before the watcher, the graph backfill and session ingestion, and
+	// Never fatal on an unreachable issuer (#83): on a cold cluster boot this
-	// retried rather than fatal (#83). Two separate reasons:
+	// pod can beat dex to serving and get a 502 from ingress, and exiting meant
-	//
+	// CrashLoopBackOff redoing the backfill. Since mcp-chassis v0.7 the
-	//   - On a cold cluster boot this pod can beat dex to serving and gets a
+	// validator resolves the issuer lazily and answers JWTs 503-and-retry until
-	//     502 from ingress. Nothing is misconfigured; it simply started first.
+	// it does (hyperguild#155), so no boot retry is needed. A misconfigured
-	//     Exiting there meant CrashLoopBackOff redoing the backfill on every
+	// issuer no longer exits the process: it is logged at boot and every JWT
-	//     attempt, with exponential backoff stretching the brain outage.
+	// gets 503; the static bearer keeps working.
-	//   - Constructing it first means a genuine config error (wrong issuer,
+	jwtValidator, err := buildJWTValidator(ctx, logger,
-	//     bad audience) fails in seconds instead of after all that work.
+		os.Getenv("DEX_ISSUER_URL"), os.Getenv("MCP_AUDIENCE"))
-	//
-	// The budget stays bounded: retrying forever would turn a misconfiguration
-	// into a process that looks alive and never serves.
-	jwtValidator, err := startupretry.Do(ctx,
-		startupretry.Policy{Attempts: 8, Base: time.Second, Max: 30 * time.Second},
-		func(ctx context.Context) (*chassisauth.JWTValidator, error) {
-			v, err := chassisauth.NewJWTValidator(ctx, os.Getenv("DEX_ISSUER_URL"), os.Getenv("MCP_AUDIENCE"))
-			if err != nil {
-				logger.Warn("oidc discovery not ready, retrying", "err", err)
-			}
-			return v, err
-		})
 	if err != nil {
 		logger.Error("build jwt validator", "err", err)
 		os.Exit(1)
@@ -399,10 +401,26 @@ func main() {
 	}
 
 	if watchInterval > 0 {
+		// INGEST_WING_RESOLVE=1 routes raw/ notes into wiki/<wing>/ by
+		// subfolder, frontmatter or classifier+scorer, and parks the rest in
+		// raw/needs-review/ (hyperguild#205). Off = the retired layout. Set
+		// explicitly, a failure to build the resolver is fatal: silently
+		// falling back would write into the layout this flag exists to leave.
+		var wingResolver *wing.Resolver
+		if os.Getenv("INGEST_WING_RESOLVE") == "1" {
+			var rerr error
+			wingResolver, rerr = wing.NewConfiguredResolver(brainDir, llmClient.Complete, envFloat("INGEST_WING_THRESHOLD", 0.9))
+			if rerr != nil {
+				logger.Error("build wing resolver", "err", rerr)
+				os.Exit(1)
+			}
+			logger.Info("wing resolver enabled", "wings", len(wingResolver.Known), "threshold", wingResolver.Threshold)
+		}
 		watcher.Start(ctx, watcher.Config{
 			BrainDir: brainDir,
 			Interval: time.Duration(watchInterval) * time.Second,
 			Pipeline: pipelineCfg,
+			Resolver: wingResolver,
 		})
 	}
 
@@ -529,8 +547,6 @@ func main() {
 		}
 	}
 
-	public["/mcp"] = chassisauth.BearerMiddleware(mcpToken, jwtValidator, "brain", resourceMetadataURL, mcpSrv)
-
 	// POST /capture (#53/#54): the uniform capture REST door. Needs a ticket
 	// tracker to file action items, so it only mounts when Gitea is
 	// configured. It reuses the MCP server's graph-wired brain store (one
@@ -554,14 +570,14 @@ func main() {
 		public["POST /capture"] = captureH
 		// Same use-case behind the MCP `capture` tool (#55 relay) so MCP-native
 		// harnesses (claude.ai, Crush, Pi, LLM Council) reach capture through
-		// the existing /mcp OAuth connector. mcpSrv is already wrapped above;
+		// the existing /mcp OAuth connector. buildMux wraps this same mcpSrv;
 		// WithCapture mutates the same instance, so the tool appears live.
 		mcpSrv.WithCapture(captureSvc, jwtValidator, mcpToken, "local-cli", resolver)
 		// hyperguild#97: a governance-file rewrite gets the same trail a
 		// 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 {
@@ -596,19 +612,18 @@ func main() {
 		os.Exit(1)
 	}
 
-	// /metrics — unauthenticated Prometheus endpoint. kube-prometheus-stack
+	// /metrics — unauthenticated Prometheus endpoint, scraped via the
-	// scrapes it via the ServiceMonitor in k3s/apps/supervisor/. The metrics
+	// ServiceMonitor in k3s/apps/supervisor/. buildMux registers it and wraps
-	// middleware below wraps every other registered handler so it observes
+	// the whole router in the registry's middleware.
-	// real request latency. /metrics itself is excluded from its own
+	//
-	// observation by registering it on the outer mux (post-wrap).
+	// The whole router, /mcp's bearer included, is built in buildMux so its
-	reg := metrics.New()
+	// tests are tests of production wiring (PR #152 review, hyperguild#154).
-	public["GET /metrics"] = http.HandlerFunc(reg.Handler())
+	// The REST API's credential is the same as /mcp's. Untested here: the
-
+	// restAuth fields and the public map this call passes in (e.g. a nil
-	// The whole router, built in one place so the test of buildMux is a test
+	// validator would drop JWT auth on /mcp and REST and the suite stays
-	// of production wiring (PR #152 review). The REST API's credential is the
+	// green), and ListenAndServe serving the result unchanged (hyperguild#182).
-	// same as /mcp's.
+	handler, err := buildMux(restAuth{token: mcpToken, validator: jwtValidator, realm: "brain",
-	mux, err := buildMux(restAuth{token: mcpToken, validator: jwtValidator, realm: "brain",
+		resourceMetadataURL: resourceMetadataURL}, h, mcpSrv, metrics.New(), public)
-		resourceMetadataURL: resourceMetadataURL}, h, public)
 	if err != nil {
 		logger.Error("build router", "err", err)
 		os.Exit(1)
@@ -629,7 +644,7 @@ func main() {
 		"watch_interval", watchIntervalLog,
 		"mcp_enabled", true,
 	)
-	if err := http.ListenAndServe(addr, reg.Middleware(mux)); err != nil {
+	if err := http.ListenAndServe(addr, handler); err != nil {
 		logger.Error("server stopped", "err", err)
 		os.Exit(1)
 	}

ingestion/cmd/server/main_test.go

@@ -76,3 +76,23 @@ func TestAlertingWarnings(t *testing.T) {
 		})
 	}
 }
+
+func TestEnvFloat(t *testing.T) {
+	tests := []struct {
+		name string
+		set  string
+		want float64
+	}{
+		{"unset falls back", "", 0.9},
+		{"valid value", "0.75", 0.75},
+		{"garbage falls back rather than becoming 0", "high", 0.9},
+		{"out of range is rejected, not clamped silently into auto-placing everything", "-1", 0.9},
+		{"above one is rejected", "1.5", 0.9},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Setenv("TEST_ENV_FLOAT", tt.set)
+			assert.InDelta(t, tt.want, envFloat("TEST_ENV_FLOAT", 0.9), 1e-9)
+		})
+	}
+}

ingestion/cmd/server/routes.go

@@ -8,22 +8,22 @@ import (
 	chassisauth "git.d-ma.be/mathias/mcp-chassis/auth"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/metrics"
 )
 
-// publicRoutes is the complete set of patterns allowed on the outer mux,
+// publicRoutes is the complete set of patterns a caller may register on the
-// outside the REST API's auth (hyperguild#149). Each authenticates itself or is
+// outer mux, outside the REST API's auth (hyperguild#149). Each authenticates
-// meant to be open: /mcp (bearer/JWT), /capture (bearer/JWT), the webhook
+// itself or is meant to be open: /capture (bearer/JWT), the webhook (HMAC),
-// (HMAC), /oauth/token (client secret), OAuth metadata and /metrics (open).
+// /oauth/token (client secret) and OAuth metadata (open). /mcp and /metrics
-// A REST pattern added here would beat the authenticated catch-all by
+// are not here: buildMux builds them itself (hyperguild#154). A REST pattern
-// specificity and ship open, which is why buildMux refuses anything else.
+// added here would beat the authenticated catch-all by specificity and ship
+// open, which is why buildMux refuses anything else.
 var publicRoutes = map[string]bool{
-	"/mcp":                      true,
 	"POST /capture":             true,
 	"POST /webhooks/brain-sync": true,
 	"GET /.well-known/oauth-protected-resource":   true,
 	"GET /.well-known/oauth-authorization-server": true,
 	"POST /oauth/token":                           true,
-	"GET /metrics":                                true,
 }
 
 // restAuth is the credential the REST API checks: the same as /mcp's.
@@ -34,16 +34,25 @@ type restAuth struct {
 	resourceMetadataURL string
 }
 
-// buildMux is the server's whole router. The REST API is mounted at "/"
+// buildMux builds the handler main passes to ListenAndServe unchanged. The
-// behind bearer auth that buildMux constructs itself, so a caller cannot pass
+// REST API is mounted at "/" and /mcp is registered, both behind bearer auth
-// a no-op; public handlers are registered as given, and only for patterns on
+// that buildMux constructs itself from auth (one credential), so a caller
-// the publicRoutes allowlist. It returns an http.Handler, not the
+// cannot pass a no-op. GET /metrics serves reg, and the whole router is
-// *ServeMux, so nothing can register a route on the result afterwards and
+// wrapped in reg's middleware. Other public handlers are registered as given,
-// bypass the allowlist.
+// and only for patterns on the publicRoutes allowlist. It returns an
-func buildMux(auth restAuth, h *api.Handler, public map[string]http.Handler) (http.Handler, error) {
+// http.Handler, not the *ServeMux, so nothing can register a route on the
+// result. What stays untested is main's call site: the restAuth fields and
+// the public map main passes in, and ListenAndServe serving this handler
+// unchanged (hyperguild#182). The tests build their own arguments.
+func buildMux(
+	auth restAuth, h *api.Handler, mcpHandler http.Handler, reg *metrics.Registry, public map[string]http.Handler,
+) (http.Handler, error) {
 	if auth.token == "" {
 		return nil, errors.New("buildMux: REST auth needs a token")
 	}
+	if mcpHandler == nil || reg == nil {
+		return nil, errors.New("buildMux: needs the MCP handler and the metrics registry")
+	}
 	mux := http.NewServeMux()
 	for pattern, handler := range public {
 		if !publicRoutes[pattern] {
@@ -51,10 +60,15 @@ func buildMux(auth restAuth, h *api.Handler, public map[string]http.Handler) (ht
 		}
 		mux.Handle(pattern, handler)
 	}
-	mountREST(mux, h, func(next http.Handler) http.Handler {
+	bearer := func(next http.Handler) http.Handler {
 		return chassisauth.BearerMiddleware(auth.token, auth.validator, auth.realm, auth.resourceMetadataURL, next)
-	})
+	}
-	return mux, nil
+	mux.Handle("/mcp", bearer(mcpHandler))
+	// /metrics is registered on the mux and so observed by its own
+	// middleware, like any route.
+	mux.Handle("GET /metrics", reg.Handler())
+	mountREST(mux, h, bearer)
+	return reg.Middleware(mux), nil
 }
 
 // mountREST registers the REST API on its own mux and mounts it at "/" behind
@@ -73,5 +87,23 @@ func mountREST(mux *http.ServeMux, h *api.Handler, auth func(http.Handler) http.
 	rest.HandleFunc("POST /promote", h.Promote)
 	rest.HandleFunc("POST /backfill-embeddings", h.BackfillEmbeddings)
 	rest.HandleFunc("GET /pass-rate", h.PassRate)
-	mux.Handle("/", auth(rest))
+	mux.Handle("/", labelRESTPattern(rest, auth(rest)))
+}
+
+// labelRESTPattern sets the request's Pattern to the REST route it addresses
+// before auth runs, so the metrics middleware (which reads Pattern from the
+// same *http.Request) labels a refused request by its route rather than by
+// the "/" mount (hyperguild#155). A refused request to a path no route
+// matches keeps "/", so for refused requests the label set stays bounded by
+// the registered routes. That bound does not hold for authenticated
+// requests: an unregistered path reaches the REST mux, which 404s with an
+// empty Pattern, and the metrics middleware falls back to the raw URL path
+// (hyperguild#185).
+func labelRESTPattern(rest *http.ServeMux, next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if _, pattern := rest.Handler(r); pattern != "" {
+			r.Pattern = pattern
+		}
+		next.ServeHTTP(w, r)
+	})
 }

ingestion/cmd/server/routes_observability_test.go

@@ -0,0 +1,88 @@
+package main
+
+import (
+	"bytes"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// wrongTokSentinel is a presented credential distinctive enough that any
+// occurrence in a log line is the raw token, not a coincidence.
+const wrongTokSentinel = "wrong-tok-sentinel-q7zx"
+
+// hyperguild#155: since #149 every REST route sits behind BearerMiddleware,
+// and chassis v0.2.0 refused without logging, so an unknown caller got
+// silent 401s. The chassis now writes an `mcp auth rejected` line, and the
+// presented token appears nowhere in the log as a bare value (PR #181
+// review: asserting on the "Bearer " header form could never fail, since
+// the chassis logs fields, not headers).
+func TestBuildMuxRejectionLogLineOmitsTheBarePresentedToken(t *testing.T) {
+	var buf bytes.Buffer
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(&buf, nil)))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+
+	code, _ := do(t, testMux(t), "POST", "/query", "Bearer "+wrongTokSentinel)
+	require.Equal(t, http.StatusUnauthorized, code)
+	assert.Contains(t, buf.String(), "mcp auth rejected")
+	assert.Contains(t, buf.String(), "path=/query")
+	assert.NotContains(t, buf.String(), wrongTokSentinel, "the rejected token is logged as a bare value")
+	assert.NotContains(t, buf.String(), routesTok, "the valid static token is logged")
+}
+
+// The `mcp auth accepted` line leaves out the valid static token.
+func TestBuildMuxAcceptedLogLineOmitsTheBareStaticToken(t *testing.T) {
+	var buf bytes.Buffer
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(&buf, nil)))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+
+	code, _ := do(t, testMux(t), "GET", "/pending", "Bearer "+routesTok)
+	require.Equal(t, http.StatusOK, code)
+	assert.Contains(t, buf.String(), "mcp auth accepted")
+	assert.NotContains(t, buf.String(), routesTok, "the accepted static token is logged as a bare value")
+}
+
+// An authenticated REST request is labelled with the REST mux's pattern:
+// the inner mux sets it on the same *http.Request the outer middleware reads.
+func TestMetricsLabelAnAuthenticatedRESTRequestWithItsRoutePattern(t *testing.T) {
+	mux, reg := testMuxAndRegistry(t)
+	code, _ := do(t, mux, "GET", "/pending", "Bearer "+routesTok)
+	require.Equal(t, http.StatusOK, code)
+
+	rec := httptest.NewRecorder()
+	reg.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/metrics", nil))
+	assert.Contains(t, rec.Body.String(), `path="GET /pending"`)
+	assert.NotContains(t, rec.Body.String(), `path="/"`)
+}
+
+// hyperguild#155: a request refused by REST auth never reaches the REST mux,
+// so it was labelled path="/" and a 4xx on /query could not be told from one
+// on /write. It is now labelled with the REST pattern it was addressed to.
+func TestMetricsLabelARejectedRESTRequestWithItsRoutePattern(t *testing.T) {
+	mux, reg := testMuxAndRegistry(t)
+	code, _ := do(t, mux, "POST", "/query", "")
+	require.Equal(t, http.StatusUnauthorized, code)
+
+	rec := httptest.NewRecorder()
+	reg.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/metrics", nil))
+	assert.Contains(t, rec.Body.String(), `path="POST /query",status="4xx"`)
+}
+
+// A path no REST route matches keeps the catch-all label, so an attacker
+// probing random URLs cannot grow the series set.
+func TestMetricsLabelARejectedUnknownPathWithTheCatchAll(t *testing.T) {
+	mux, reg := testMuxAndRegistry(t)
+	code, _ := do(t, mux, "POST", "/no-such-route-zq", "")
+	require.Equal(t, http.StatusUnauthorized, code)
+
+	rec := httptest.NewRecorder()
+	reg.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/metrics", nil))
+	assert.Contains(t, rec.Body.String(), `path="/",status="4xx"`)
+	assert.NotContains(t, rec.Body.String(), "no-such-route-zq")
+}

ingestion/cmd/server/routes_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/metrics"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 )
 
@@ -21,20 +22,34 @@ func okHandler(body string) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { _, _ = w.Write([]byte(body)) })
 }
 
-// testMux builds the router exactly as main does: buildMux with the full
+// testMux builds the router through buildMux, the function main calls, with
-// public set main registers (stub handlers) and real bearer config.
+// every allowlisted public pattern (stub handlers), a stub MCP server and a
-// hyperguild#149: the REST API is authenticated as a whole; the PR #152
+// static token only: no JWT validator and no resourceMetadataURL (the tests
-// review showed a test of a COPY of the router let main.go regress unseen.
+// in jwt_validator_test.go pass those). It does not use main's own restAuth
+// or public map (hyperguild#182). hyperguild#149: the REST API is
+// authenticated as a whole; the PR #152 review showed a test of a COPY of
+// the router let main.go regress unseen.
 func testMux(t *testing.T) http.Handler {
 	t.Helper()
-	h := api.NewHandler(t.TempDir(), slog.New(slog.NewTextHandler(os.Stderr, nil)), pipeline.Config{})
+	mux, _ := testMuxAndRegistry(t)
+	return mux
+}
+
+func testMuxAndRegistry(t *testing.T) (http.Handler, *metrics.Registry) {
+	t.Helper()
 	public := map[string]http.Handler{}
 	for p := range publicRoutes {
 		public[p] = okHandler("public " + p)
 	}
-	mux, err := buildMux(restAuth{token: routesTok, realm: "brain"}, h, public)
+	reg := metrics.New()
+	mux, err := buildMux(restAuth{token: routesTok, realm: "brain"}, testHandler(t), okHandler("mcp"), reg, public)
 	require.NoError(t, err)
-	return mux
+	return mux, reg
+}
+
+func testHandler(t *testing.T) *api.Handler {
+	t.Helper()
+	return api.NewHandler(t.TempDir(), slog.New(slog.NewTextHandler(os.Stderr, nil)), pipeline.Config{})
 }
 
 func do(t *testing.T, h http.Handler, method, path, authz string) (int, string) {
@@ -74,8 +89,9 @@ func TestBuildMuxAuthenticatesAnUnregisteredPath(t *testing.T) {
 }
 
 // buildMux registers public handlers as given, without adding auth: each
-// public route owns its own (bearer on /mcp, HMAC on the webhook, client
+// public route owns its own (bearer/JWT on /capture, HMAC on the webhook,
-// secret on /oauth/token) or is meant to be open (/metrics, OAuth metadata).
+// client secret on /oauth/token) or is meant to be open (OAuth metadata).
+// /mcp and /metrics are not public routes: buildMux builds them itself.
 func TestBuildMuxDoesNotWrapPublicRoutes(t *testing.T) {
 	r := testMux(t)
 	for p := range publicRoutes {
@@ -93,14 +109,66 @@ func TestBuildMuxDoesNotWrapPublicRoutes(t *testing.T) {
 // over the authenticated catch-all (more specific pattern), so it is refused.
 func TestBuildMuxRefusesAPublicPatternOffTheAllowlist(t *testing.T) {
 	h := api.NewHandler(t.TempDir(), slog.New(slog.NewTextHandler(os.Stderr, nil)), pipeline.Config{})
-	for _, p := range []string{"POST /query", "GET /pending", "/", "POST /metrics"} {
+	// "/mcp" and "GET /metrics" are built by buildMux itself (hyperguild#154):
-		_, err := buildMux(restAuth{token: routesTok, realm: "brain"}, h, map[string]http.Handler{p: okHandler("x")})
+	// passing either as public would register them unauthenticated or twice.
+	for _, p := range []string{"POST /query", "GET /pending", "/", "POST /metrics", "/mcp", "GET /metrics"} {
+		_, err := buildMux(restAuth{token: routesTok, realm: "brain"}, h, okHandler("mcp"), metrics.New(),
+			map[string]http.Handler{p: okHandler("x")})
 		assert.Error(t, err, "public pattern %q must be refused", p)
 	}
 }
 
 func TestBuildMuxRefusesAnEmptyToken(t *testing.T) {
 	h := api.NewHandler(t.TempDir(), slog.New(slog.NewTextHandler(os.Stderr, nil)), pipeline.Config{})
-	_, err := buildMux(restAuth{token: "", realm: "brain"}, h, nil)
+	_, err := buildMux(restAuth{token: "", realm: "brain"}, h, okHandler("mcp"), metrics.New(), nil)
 	assert.Error(t, err)
 }
+
+// hyperguild#154: /mcp's bearer was built in main.go, untested; the buildMux
+// tests used stubs. buildMux now wraps the MCP handler itself, with the same
+// credential as the REST API.
+func TestBuildMuxRefusesMCPWithoutAValidToken(t *testing.T) {
+	r := testMux(t)
+	for _, authz := range []string{"", "Bearer wrong"} {
+		code, body := do(t, r, "POST", "/mcp", authz)
+		assert.Equal(t, http.StatusUnauthorized, code, "authz %q", authz)
+		assert.NotEqual(t, "mcp", body)
+	}
+	code, body := do(t, r, "POST", "/mcp", "Bearer "+routesTok)
+	assert.Equal(t, http.StatusOK, code)
+	assert.Equal(t, "mcp", body)
+}
+
+func TestBuildMuxRefusesANilMCPHandlerOrRegistry(t *testing.T) {
+	auth := restAuth{token: routesTok, realm: "brain"}
+	_, err := buildMux(auth, testHandler(t), nil, metrics.New(), nil)
+	assert.Error(t, err)
+	_, err = buildMux(auth, testHandler(t), okHandler("mcp"), nil, nil)
+	assert.Error(t, err)
+}
+
+// hyperguild#154: main wrapped buildMux's result in the metrics middleware
+// before ListenAndServe, untested. buildMux now returns the handler main
+// serves as-is, metrics included: a request through it is observed and
+// exposed on its own GET /metrics.
+func TestBuildMuxObservesRequestsAndServesMetrics(t *testing.T) {
+	r := testMux(t)
+	code, _ := do(t, r, "GET", "/pending", "Bearer "+routesTok)
+	require.Equal(t, http.StatusOK, code)
+	code, body := do(t, r, "GET", "/metrics", "")
+	require.Equal(t, http.StatusOK, code)
+	assert.Contains(t, body, `path="GET /pending"`)
+}
+
+// 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/cmd/wingbacktest/main.go

@@ -0,0 +1,147 @@
+// Command wingbacktest measures how well the wing resolver would have placed
+// pages whose wing a human already decided (hyperguild#205).
+//
+// It reads pages from the wings given in -wings, hides the wing, asks the
+// local classifier and the BM25 scorer, and reports coverage/precision per
+// confidence threshold. Page text is sent to -llm-url, which MUST be a local
+// model (it is not checked here); sample only wings you would allow.
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io/fs"
+	"log/slog"
+	"math/rand"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/llm"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/wing"
+)
+
+func main() {
+	brain := flag.String("brain", "/var/lib/supervisor/brain", "brain directory (read only)")
+	wingsFlag := flag.String("wings", "", "comma-separated wings to sample pages FROM (must be wings you would allow)")
+	perWing := flag.Int("per-wing", 8, "pages sampled per wing")
+	llmURL := flag.String("llm-url", "http://10.0.1.20:31234/v1", "OpenAI-compatible LOCAL endpoint")
+	model := flag.String("model", "qwen35-9b-fast", "model name")
+	seed := flag.Int64("seed", 1, "sampling seed")
+	flag.Parse()
+
+	if err := run(*brain, strings.Split(*wingsFlag, ","), *perWing, *llmURL, *model, *seed); err != nil {
+		slog.Error("wingbacktest", "err", err)
+		os.Exit(1)
+	}
+}
+
+func run(brain string, sampleWings []string, perWing int, llmURL, model string, seed int64) error {
+	known, err := wing.KnownWings(brain)
+	if err != nil {
+		return err
+	}
+	client := llm.New(llmURL, "", model, 3*time.Minute)
+	classifier := wing.NewLLMClassifier(client.Complete)
+	rng := rand.New(rand.NewSource(seed))
+
+	var samples []wing.Sample
+	perWingSamples := map[string][]wing.Sample{}
+	for _, w := range sampleWings {
+		w = strings.TrimSpace(w)
+		if w == "" {
+			continue
+		}
+		pages, err := listPages(brain, w)
+		if err != nil {
+			return err
+		}
+		rng.Shuffle(len(pages), func(i, j int) { pages[i], pages[j] = pages[j], pages[i] })
+		if len(pages) > perWing {
+			pages = pages[:perWing]
+		}
+		for _, rel := range pages {
+			text, err := readBody(brain, rel)
+			if err != nil || len(text) < 200 {
+				continue
+			}
+			sugg, cerr := classifier.Classify(context.Background(), text, known)
+			if cerr != nil {
+				slog.Warn("classify failed", "page", rel, "err", cerr)
+			}
+			top, _ := wing.TopWing(wing.NewBM25Scorer(brain, known, rel).Score(text))
+			s := wing.Sample{Truth: w, Suggested: strings.ToLower(sugg.Wing), Confidence: sugg.Confidence, ScorerTop: top}
+			slog.Info("sample", "page", rel, "truth", w, "classifier", s.Suggested, "conf", s.Confidence, "scorer", top, "reason", sugg.Reason)
+			samples = append(samples, s)
+			perWingSamples[w] = append(perWingSamples[w], s)
+		}
+	}
+	report(samples, perWingSamples)
+	return nil
+}
+
+func report(samples []wing.Sample, per map[string][]wing.Sample) {
+	fmt.Printf("# wing backtest\n\nn=%d pages. Classifier+scorer must agree; threshold applies to classifier confidence.\n\n", len(samples))
+	fmt.Println("| threshold | auto | coverage | precision |")
+	fmt.Println("|---|---|---|---|")
+	for _, t := range []float64{0.5, 0.6, 0.7, 0.8, 0.9, 0.95} {
+		r := wing.Evaluate(samples, t)
+		fmt.Printf("| %.2f | %d/%d | %.0f%% | %.0f%% |\n", t, r.Auto, r.N, 100*r.Coverage, 100*r.Precision)
+	}
+	fmt.Println("\n## per wing (threshold 0.80)\n\n| wing | n | auto | precision |\n|---|---|---|---|")
+	names := make([]string, 0, len(per))
+	for w := range per {
+		names = append(names, w)
+	}
+	sort.Strings(names)
+	for _, w := range names {
+		r := wing.Evaluate(per[w], 0.8)
+		fmt.Printf("| %s | %d | %d | %.0f%% |\n", w, r.N, r.Auto, 100*r.Precision)
+	}
+	fmt.Println("\n## wrong auto-placements at 0.80")
+	fmt.Println()
+	for _, s := range samples {
+		if s.Suggested != "" && s.Confidence >= 0.8 && s.ScorerTop == s.Suggested && s.Suggested != s.Truth {
+			fmt.Printf("- truth=%s -> both said %s (conf %.2f)\n", s.Truth, s.Suggested, s.Confidence)
+		}
+	}
+}
+
+func listPages(brain, w string) ([]string, error) {
+	var out []string
+	root := filepath.Join(brain, "wiki", w)
+	err := filepath.WalkDir(root, func(p string, d fs.DirEntry, err error) error {
+		if err != nil || d.IsDir() || !d.Type().IsRegular() || !strings.HasSuffix(p, ".md") || d.Name() == "_index.md" {
+			return err
+		}
+		rel, rerr := filepath.Rel(brain, p)
+		if rerr != nil {
+			return rerr
+		}
+		out = append(out, filepath.ToSlash(rel))
+		return nil
+	})
+	if err != nil {
+		return nil, fmt.Errorf("walk %s: %w", w, err)
+	}
+	return out, nil
+}
+
+// readBody returns the page text without YAML frontmatter, so the wing label
+// (and anything else in frontmatter) cannot leak into the classification.
+func readBody(brain, rel string) (string, error) {
+	b, err := os.ReadFile(filepath.Join(brain, filepath.FromSlash(rel)))
+	if err != nil {
+		return "", fmt.Errorf("read %s: %w", rel, err)
+	}
+	s := string(b)
+	if strings.HasPrefix(s, "---\n") {
+		if end := strings.Index(s[4:], "\n---"); end >= 0 {
+			s = s[4+end+4:]
+		}
+	}
+	return strings.TrimSpace(s), nil
+}

ingestion/cmd/wingmigrate/main.go

@@ -0,0 +1,92 @@
+// Command wingmigrate moves pages out of the retired wiki/{sources,concepts,
+// entities}/ layout into wiki/<wing>/ (hyperguild#205 S5).
+//
+// Default is a dry run that prints the plan. -apply performs the Auto items.
+// Page text goes to -llm-url, which MUST be a local model.
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"log/slog"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/llm"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/migrate"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/wing"
+)
+
+func main() {
+	brain := flag.String("brain", "/var/lib/supervisor/brain", "brain directory")
+	llmURL := flag.String("llm-url", "http://10.0.1.20:31234/v1", "OpenAI-compatible LOCAL endpoint")
+	model := flag.String("model", "qwen35-9b-fast", "model name")
+	threshold := flag.Float64("threshold", 0.9, "classifier confidence threshold")
+	apply := flag.Bool("apply", false, "perform the Auto moves (default: dry run)")
+	what := flag.String("what-if-eligible", "", "dry run only: comma-separated wings to treat as eligible, to see what tagging them would allow")
+	flag.Parse()
+
+	if *apply && *what != "" {
+		slog.Error("-what-if-eligible is a dry-run aid and cannot be combined with -apply: eligibility is a sovereignty decision made in classification.yaml")
+		os.Exit(2)
+	}
+	if err := run(*brain, *llmURL, *model, *threshold, *apply, *what); err != nil {
+		slog.Error("wingmigrate", "err", err)
+		os.Exit(1)
+	}
+}
+
+func run(brain, llmURL, model string, threshold float64, apply bool, whatIf string) error {
+	client := llm.New(llmURL, "", model, 3*time.Minute)
+	base, err := wing.NewConfiguredResolver(brain, client.Complete, threshold)
+	if err != nil {
+		return err
+	}
+	if whatIf != "" {
+		allowed := map[string]bool{}
+		for _, w := range strings.Split(whatIf, ",") {
+			allowed[strings.TrimSpace(w)] = true
+		}
+		base.Eligible = func(w string) bool { return allowed[w] }
+	}
+	rf := func(exclude string) *wing.Resolver {
+		r := *base
+		r.Scorer = wing.NewBM25Scorer(brain, base.Known, exclude)
+		return &r
+	}
+	items, err := migrate.BuildPlan(context.Background(), brain, rf)
+	if err != nil {
+		return err
+	}
+	report(items)
+	if !apply {
+		fmt.Println("\n_dry run: nothing was changed_")
+		return nil
+	}
+	n, err := migrate.Apply(brain, items)
+	fmt.Printf("\napplied %d moves\n", n)
+	return err
+}
+
+func report(items []migrate.Item) {
+	auto, exc := 0, 0
+	for _, it := range items {
+		if it.Status == migrate.Auto {
+			auto++
+		} else {
+			exc++
+		}
+	}
+	fmt.Printf("# wing migration plan\n\n%d pages: %d auto, %d exceptions\n\n", len(items), auto, exc)
+	fmt.Println("| status | kind | from | to / proposal | how | why |")
+	fmt.Println("|---|---|---|---|---|---|")
+	for _, it := range items {
+		dest := it.To
+		if dest == "" {
+			dest = it.Wing
+		}
+		fmt.Printf("| %s | %s | %s | %s | %s | %s |\n", it.Status, it.Kind, it.From, dest, it.Method, strings.ReplaceAll(it.Reason, "|", "/"))
+	}
+}

ingestion/go.mod

@@ -34,9 +34,9 @@ require (
 	github.com/rogpeppe/go-internal v1.15.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
-	golang.org/x/net v0.26.0 // indirect
+	golang.org/x/net v0.55.0 // indirect
 	golang.org/x/oauth2 v0.21.0 // indirect
-	golang.org/x/term v0.28.0 // indirect
+	golang.org/x/term v0.43.0 // indirect
 	golang.org/x/time v0.3.0 // indirect
 	google.golang.org/protobuf v1.34.2 // indirect
 	gopkg.in/evanphx/json-patch.v4 v4.12.0 // indirect
@@ -51,7 +51,7 @@ require (
 )
 
 require (
-	git.d-ma.be/mathias/mcp-chassis v0.2.0
+	git.d-ma.be/mathias/mcp-chassis v0.7.1
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0 // indirect
 	github.com/goccy/go-json v0.10.3 // indirect
@@ -66,9 +66,9 @@ require (
 	github.com/lestrrat-go/option v1.0.1 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/segmentio/asm v1.2.0 // indirect
-	golang.org/x/crypto v0.32.0 // indirect
+	golang.org/x/crypto v0.51.0 // indirect
-	golang.org/x/sync v0.17.0 // indirect
+	golang.org/x/sync v0.21.0 // indirect
-	golang.org/x/sys v0.31.0 // indirect
+	golang.org/x/sys v0.45.0
-	golang.org/x/text v0.29.0 // indirect
+	golang.org/x/text v0.39.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1
 )

ingestion/go.sum

@@ -1,5 +1,5 @@
-git.d-ma.be/mathias/mcp-chassis v0.2.0 h1:6fLmb7xqRa2nNVWsHaUbbfbArgDXJw/gDhb09clBIjo=
+git.d-ma.be/mathias/mcp-chassis v0.7.1 h1:4h8TOBHTA0L/no4IPcr4tLcQtmKUlhE2/cXyPdNFGmM=
-git.d-ma.be/mathias/mcp-chassis v0.2.0/go.mod h1:Ks7EK2UnGAN0H3rJjKUxUagX8/ZBdtLrOlcUbv0RwH8=
+git.d-ma.be/mathias/mcp-chassis v0.7.1/go.mod h1:Ks7EK2UnGAN0H3rJjKUxUagX8/ZBdtLrOlcUbv0RwH8=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -117,42 +117,42 @@ github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9dec
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
-golang.org/x/crypto v0.32.0 h1:euUpcYgM8WcP71gNpTqQCn6rC2t6ULUPiOzfWaXVVfc=
+golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
-golang.org/x/crypto v0.32.0/go.mod h1:ZnnJkOaASj8g0AjIduWNlq2NRxL0PlBrbKVyZ6V/Ugc=
+golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
 golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
-golang.org/x/net v0.26.0 h1:soB7SVo0PWrY4vPW/+ay0jKDNScG2X9wFeYlXIvJsOQ=
+golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
-golang.org/x/net v0.26.0/go.mod h1:5YKkiSynbBIh3p6iOc/vibscux0x38BZDkn8sCUPxHE=
+golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
 golang.org/x/oauth2 v0.21.0 h1:tsimM75w1tF/uws5rbeHzIWxEqElMehnc+iW793zsZs=
 golang.org/x/oauth2 v0.21.0/go.mod h1:XYTD2NtWslqkgxebSiOHnXEap4TF09sJSc7H1sXbhtI=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
+golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
-golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
+golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
-golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/term v0.28.0 h1:/Ts8HFuMR2E6IP/jlo7QVLZHggjKQbhu/7H0LJFr3Gg=
+golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
-golang.org/x/term v0.28.0/go.mod h1:Sw/lC2IAUZ92udQNf3WodGtn4k/XoLyZoh8v/8uiwek=
+golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
-golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
+golang.org/x/text v0.39.0 h1:UbZz4pLOvn600D6Oh6GGEI6VAmndrEBLv8/6BEXzyus=
-golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
+golang.org/x/text v0.39.0/go.mod h1:3UwRclnC2g0TU9x8PZiyfOajCd1zaUNHF9cvqcQZ+ZM=
 golang.org/x/time v0.3.0 h1:rg5rLMjNzMS1RkNLzCG38eapWhnYLFYXDXj2gOlr8j4=
 golang.org/x/time v0.3.0/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
 golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
-golang.org/x/tools v0.36.0 h1:kWS0uv/zsvHEle1LbV5LE8QujrxB3wfQyxHfhOk0Qkg=
+golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
-golang.org/x/tools v0.36.0/go.mod h1:WBDiHKJK8YgLHlcQPYQzNCkUxUypCaa5ZegCVutKm+s=
+golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=

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/pending_review_test.go

@@ -0,0 +1,51 @@
+package api
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func writeParked(t *testing.T, brainDir, name, content string) {
+	t.Helper()
+	dir := filepath.Join(brainDir, "raw", "needs-review")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644))
+}
+
+func TestListPending_ShowsParkedNotesWithTheirProposal(t *testing.T) {
+	dir := t.TempDir()
+	writeRaw(t, dir, "fresh.md", "---\ncreated_at: 2026-10-20T08:00:00Z\n---\nA note not yet processed.\n")
+	writeParked(t, dir, "unsure.md", "---\nproposed_wing: radar\nproposal_confidence: 0.55\nproposal_reason: \"below threshold\"\ncreated_at: 2026-10-19T08:00:00Z\n---\nBody of the unsure note.\n")
+
+	got, err := ListPending(dir)
+	require.NoError(t, err)
+	require.Len(t, got, 2)
+
+	assert.Equal(t, "unsure.md", got[0].Filename, "oldest first across both queues")
+	assert.Equal(t, "needs-review", got[0].Queue)
+	assert.Equal(t, "radar", got[0].ProposedWing)
+	assert.Equal(t, "below threshold", got[0].ProposalReason)
+	assert.InDelta(t, 0.55, got[0].ProposalConfidence, 1e-9)
+	assert.Contains(t, got[0].Excerpt, "Body of the unsure note")
+	assert.NotContains(t, got[0].Excerpt, "proposed_wing", "excerpt is body, not frontmatter")
+
+	assert.Equal(t, "fresh.md", got[1].Filename)
+	assert.Empty(t, got[1].Queue, "a top-level note has no queue label")
+	assert.Empty(t, got[1].ProposedWing)
+}
+
+func TestListPending_ParkedSymlinkIsNotListed(t *testing.T) {
+	dir := t.TempDir()
+	outside := filepath.Join(t.TempDir(), "secret.md")
+	require.NoError(t, os.WriteFile(outside, []byte("outside"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw", "needs-review"), 0o755))
+	require.NoError(t, os.Symlink(outside, filepath.Join(dir, "raw", "needs-review", "link.md")))
+
+	got, err := ListPending(dir)
+	require.NoError(t, err)
+	assert.Empty(t, got, "same symlink rule as the top level (#153)")
+}

ingestion/internal/api/promote.go

@@ -8,6 +8,7 @@ import (
 	"path/filepath"
 	"regexp"
 	"sort"
+	"strconv"
 	"strings"
 	"time"
 
@@ -20,6 +21,15 @@ type PendingNote struct {
 	CreatedAt string `json:"created_at"`
 	SizeBytes int64  `json:"size_bytes"`
 	Excerpt   string `json:"excerpt"`
+
+	// Set only for a note parked in raw/needs-review/ by the wing resolver
+	// (hyperguild#205): it was not placed automatically, and the proposal says
+	// what the resolver would have done and why it did not. Approve by moving
+	// the note into raw/<wing>/ and the watcher ingests it there.
+	Queue              string  `json:"queue,omitempty"`
+	ProposedWing       string  `json:"proposed_wing,omitempty"`
+	ProposalReason     string  `json:"proposal_reason,omitempty"`
+	ProposalConfidence float64 `json:"proposal_confidence,omitempty"`
 }
 
 // datePrefix matches a leading YYYY-MM-DD- on a raw filename, stripped when
@@ -38,11 +48,32 @@ func ListPending(brainDir string) ([]PendingNote, error) {
 		return nil, fmt.Errorf("read raw dir: %w", err)
 	}
 	defer func() { _ = root.Close() }()
+
+	out, err := listNotes(root, "")
+	if err != nil {
+		return nil, err
+	}
+	// raw/needs-review/ is read through its own root, so a symlinked directory
+	// or note there is refused exactly like at the top level (#153).
+	if sub, serr := root.OpenRoot("needs-review"); serr == nil {
+		defer func() { _ = sub.Close() }()
+		parked, perr := listNotes(sub, "needs-review")
+		if perr != nil {
+			return nil, perr
+		}
+		out = append(out, parked...)
+	}
+	sort.SliceStable(out, func(i, j int) bool { return out[i].CreatedAt < out[j].CreatedAt })
+	return out, nil
+}
+
+// listNotes lists the regular .md notes directly under root. queue labels the
+// notes ("" for the top of raw/) and enables reading a wing proposal.
+func listNotes(root *os.Root, queue string) ([]PendingNote, error) {
 	entries, err := fs.ReadDir(root.FS(), ".")
 	if err != nil {
 		return nil, fmt.Errorf("read raw dir: %w", err)
 	}
-
 	out := make([]PendingNote, 0, len(entries))
 	for _, e := range entries {
 		if !e.Type().IsRegular() || !strings.HasSuffix(e.Name(), ".md") || strings.HasPrefix(e.Name(), "tunnel-candidates-") {
@@ -57,14 +88,20 @@ func ListPending(brainDir string) ([]PendingNote, error) {
 		if created == "" {
 			created = info.ModTime().UTC().Format(time.RFC3339)
 		}
-		out = append(out, PendingNote{
+		n := PendingNote{
 			Filename:  e.Name(),
 			CreatedAt: created,
 			SizeBytes: info.Size(),
 			Excerpt:   excerpt(body, 200),
-		})
+			Queue:     queue,
+		}
+		if queue != "" {
+			n.ProposedWing = fm.get("proposed_wing")
+			n.ProposalReason = unquoteScalar(fm.get("proposal_reason"))
+			n.ProposalConfidence, _ = strconv.ParseFloat(fm.get("proposal_confidence"), 64)
+		}
+		out = append(out, n)
 	}
-	sort.SliceStable(out, func(i, j int) bool { return out[i].CreatedAt < out[j].CreatedAt })
 	return out, nil
 }
 
@@ -127,18 +164,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 +233,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)
 	}
 
@@ -241,3 +276,13 @@ func readRawSource(brainDir, base string) ([]byte, error) {
 	}
 	return raw, nil
 }
+
+// unquoteScalar undoes the Go-style double quoting the watcher writes around a
+// free-text value (strconv.Quote keeps it on one line); a bare value is
+// returned as is.
+func unquoteScalar(v string) string {
+	if u, err := strconv.Unquote(v); err == nil {
+		return u
+	}
+	return v
+}

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.go

@@ -3,15 +3,18 @@ package api
 import (
 	"crypto/sha256"
 	"encoding/hex"
+	"errors"
 	"fmt"
-	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
 	"time"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/claim"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/notes"
 )
 
 // ContentHash returns the lowercase hex sha256 of b. It is the note's
@@ -91,14 +94,23 @@ func UpdateNote(brainDir string, opts UpdateNoteOptions) (relPath, contentHash,
 		rel = filepath.ToSlash(rel)
 	}
 
-	rel, abs, err := resolveWithin(brainDir, rel)
+	// The path is caller-supplied (brain_update): resolve it as brain_edit
+	// does, knowledge/ and wiki/ notes only, and read and rewrite it through
+	// the brain root, never through a symlink (hyperguild#169).
+	t, err := notes.Resolve(brainDir, rel, notes.ScopeNotes)
 	if err != nil {
 		return "", "", "", err
 	}
-
+	rel = t.Rel
-	prior, err := os.ReadFile(abs)
+	bfs, err := brainfs.Open(brainDir)
 	if err != nil {
-		if os.IsNotExist(err) {
+		return "", "", "", fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+
+	prior, err := bfs.ReadRegular(rel)
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
 			return "", "", "", fmt.Errorf("note %q does not exist: use brain_write to create", rel)
 		}
 		return "", "", "", fmt.Errorf("read target: %w", err)
@@ -164,7 +176,7 @@ func UpdateNote(brainDir string, opts UpdateNoteOptions) (relPath, contentHash,
 		return "", "", "", err
 	}
 	out := []byte(stamped)
-	if err := os.WriteFile(abs, out, 0o644); err != nil {
+	if err := bfs.WriteRegular(rel, out); err != nil {
 		return "", "", "", fmt.Errorf("write: %w", err)
 	}
 	return rel, ContentHash(out), priorHash, nil

ingestion/internal/api/update_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/update_scope_test.go

@@ -0,0 +1,112 @@
+package api_test
+
+import (
+	"os"
+	"path/filepath"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
+)
+
+// brain_update passed the caller's path through resolveWithin, a lexical
+// containment check only: any file in the brain could be superseded
+// (classification.yaml, raw/, sessions/), and a final symlink was written
+// through. It now resolves like brain_edit: knowledge/ and wiki/ notes only,
+// read and rewritten through the brain root.
+func TestUpdateNoteRefusesPathsOutsideKnowledgeAndWikiNotes(t *testing.T) {
+	brain := t.TempDir()
+	files := map[string]string{
+		"classification.yaml": "levels: {}\n",
+		"raw/r.md":            "raw\n",
+		"sessions/s.jsonl":    "{}\n",
+		"wiki/w/facts/ok.md":  "---\ntitle: ok\n---\nold\n",
+		"knowledge/k.md":      "---\ntitle: k\n---\nold\n",
+		"wiki/w/facts/x.txt":  "txt\n",
+	}
+	for rel, body := range files {
+		p := filepath.Join(brain, filepath.FromSlash(rel))
+		require.NoError(t, os.MkdirAll(filepath.Dir(p), 0o755))
+		require.NoError(t, os.WriteFile(p, []byte(body), 0o644))
+	}
+	for _, rel := range []string{"classification.yaml", "raw/r.md", "sessions/s.jsonl", "wiki/w/facts/x.txt", "wiki/w/../../raw/r.md"} {
+		_, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: rel, Content: "replaced"})
+		assert.Error(t, err, rel)
+	}
+	for rel, body := range files {
+		if rel == "wiki/w/facts/ok.md" || rel == "knowledge/k.md" {
+			continue
+		}
+		got, err := os.ReadFile(filepath.Join(brain, filepath.FromSlash(rel)))
+		require.NoError(t, err)
+		assert.Equal(t, body, string(got), rel)
+	}
+	for _, rel := range []string{"wiki/w/facts/ok.md", "knowledge/k.md"} {
+		_, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: rel, Content: "new body"})
+		require.NoError(t, err, "positive control: %s", rel)
+		got, _ := os.ReadFile(filepath.Join(brain, filepath.FromSlash(rel)))
+		assert.Contains(t, string(got), "new body")
+	}
+}
+
+func TestUpdateNoteDoesNotWriteThroughASymlinkedNote(t *testing.T) {
+	brain := t.TempDir()
+	facts := filepath.Join(brain, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	victim := filepath.Join(brain, "raw", "victim.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "victim.md"), filepath.Join(facts, "l.md")))
+	_, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: "wiki/w/facts/l.md", Content: "replaced"})
+	assert.Error(t, err)
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched\n", string(got))
+}
+
+// The note is swapped between a regular file and an in-brain symlink to a
+// raw/ file while UpdateNote runs: the read and the write each refuse a
+// symlink, so the raw/ file is never rewritten.
+func TestUpdateNoteNeverRewritesASymlinkSwappedInForTheNote(t *testing.T) {
+	brain := t.TempDir()
+	facts := filepath.Join(brain, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	victim := filepath.Join(brain, "raw", "victim.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	note := filepath.Join(facts, "n.md")
+	body := "---\ntitle: n\n---\nold\n"
+	require.NoError(t, os.WriteFile(note, []byte(body), 0o644))
+
+	var stop atomic.Bool
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		tmp := note + ".swap"
+		for i := 0; !stop.Load(); i++ {
+			_ = os.Remove(tmp)
+			if i%2 == 0 {
+				_ = os.WriteFile(tmp, []byte(body), 0o644)
+			} else {
+				_ = os.Symlink(filepath.Join("..", "..", "..", "raw", "victim.md"), tmp)
+			}
+			_ = os.Rename(tmp, note)
+		}
+	}()
+	ok := 0
+	for deadline := time.Now().Add(1500 * time.Millisecond); time.Now().Before(deadline); {
+		if _, _, _, err := api.UpdateNote(brain, api.UpdateNoteOptions{Path: "wiki/w/facts/n.md", Content: "new"}); err == nil {
+			ok++
+		}
+	}
+	stop.Store(true)
+	wg.Wait()
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched\n", string(got))
+	assert.Positive(t, ok, "positive control: some updates reach the regular note")
+}

ingestion/internal/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/detect_root_test.go

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

ingestion/internal/brain/index.go

@@ -2,12 +2,16 @@ package brain
 
 import (
 	"bufio"
+	"bytes"
+	"errors"
 	"fmt"
-	"os"
+	"io"
-	"path/filepath"
+	"io/fs"
 	"sort"
 	"strings"
 	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 )
 
 // noteEntry is one row in a Wing _index.md.
@@ -26,14 +30,18 @@ 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
-	if _, err := os.Stat(wingDir); os.IsNotExist(err) {
+	// hall that is a symlink is not followed, and notes are regular files.
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	if _, err := bfs.Lstat("wiki/" + w); errors.Is(err, fs.ErrNotExist) {
 		return nil
-	} else if err != nil {
-		return fmt.Errorf("stat wing: %w", err)
 	}
 
-	entries, err := collectWingEntries(wingDir)
+	entries, err := collectWingEntries(bfs, "wiki/"+w)
 	if err != nil {
 		return err
 	}
@@ -52,74 +60,85 @@ 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/.
 func BuildAllWingIndexes(brainDir string) error {
-	wikiDir := filepath.Join(brainDir, "wiki")
+	bfs, err := brainfs.Open(brainDir)
-	ents, err := os.ReadDir(wikiDir)
+	if err != nil {
-	if os.IsNotExist(err) {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	wings, err := bfs.ReadDirDirs("wiki")
+	_ = bfs.Close()
+	if errors.Is(err, fs.ErrNotExist) {
 		return nil
 	}
 	if err != nil {
 		return fmt.Errorf("read wiki: %w", err)
 	}
-	for _, e := range ents {
+	for _, w := range wings {
-		if !e.IsDir() {
+		if err := BuildWingIndex(brainDir, w); err != nil {
-			continue
+			return fmt.Errorf("index %s: %w", w, err)
-		}
-		if err := BuildWingIndex(brainDir, e.Name()); err != nil {
-			return fmt.Errorf("index %s: %w", e.Name(), err)
 		}
 	}
 	return nil
 }
 
-func collectWingEntries(wingDir string) ([]noteEntry, error) {
+func collectWingEntries(bfs *brainfs.Brain, wingRel string) ([]noteEntry, error) {
 	var out []noteEntry
-	ents, err := os.ReadDir(wingDir)
+	halls, err := bfs.ReadDirDirs(wingRel)
 	if err != nil {
 		return nil, fmt.Errorf("read wing: %w", err)
 	}
-	for _, hallEnt := range ents {
+	for _, hall := range halls {
-		if !hallEnt.IsDir() {
-			continue
-		}
-		hall := hallEnt.Name()
 		if !IsValidHall(hall) {
 			continue
 		}
-		hallDir := filepath.Join(wingDir, hall)
+		hallRel := wingRel + "/" + hall
-		notes, err := os.ReadDir(hallDir)
+		names, err := bfs.ReadDirRegular(hallRel)
 		if err != nil {
 			return nil, fmt.Errorf("read hall %s: %w", hall, err)
 		}
-		for _, n := range notes {
+		for _, name := range names {
-			if n.IsDir() || !strings.HasSuffix(n.Name(), ".md") || n.Name() == "_index.md" {
+			if !strings.HasSuffix(name, ".md") || name == "_index.md" {
 				continue
 			}
-			slug := strings.TrimSuffix(n.Name(), ".md")
+			slug := strings.TrimSuffix(name, ".md")
-			full := filepath.Join(hallDir, n.Name())
+			title, created := readTitleAndCreatedIn(bfs, hallRel+"/"+name, slug)
-			title, created := readTitleAndCreated(full, slug)
 			out = append(out, noteEntry{Hall: hall, Slug: slug, Title: title, Created: created})
 		}
 	}
 	return out, nil
 }
 
-// readTitleAndCreated reads YAML frontmatter for title + created_at; falls
+// readTitleAndCreatedIn is readTitleAndCreated through the brain root,
-// back to slug and file mtime when absent.
+// regular files only (hyperguild#157).
-func readTitleAndCreated(path, slug string) (string, string) {
+func readTitleAndCreatedIn(bfs *brainfs.Brain, rel, slug string) (string, string) {
-	f, err := os.Open(path)
+	content, err := bfs.ReadRegular(rel)
 	if err != nil {
 		return slug, ""
 	}
-	defer func() { _ = f.Close() }()
+	title, created := parseTitleAndCreated(bytes.NewReader(content))
+	if created == "" {
+		if info, err := bfs.Lstat(rel); err == nil {
+			created = info.ModTime().UTC().Format("2006-01-02")
+		}
+	}
+	return titleOrSlug(title, slug), created
+}
 
-	title, created := "", ""
+func titleOrSlug(title, slug string) string {
-	scanner := bufio.NewScanner(f)
+	if title == "" {
+		return strings.ReplaceAll(slug, "-", " ")
+	}
+	return title
+}
+
+func parseTitleAndCreated(r io.Reader) (title, created string) {
+	scanner := bufio.NewScanner(r)
 	inFrontmatter := false
 	for scanner.Scan() {
 		line := scanner.Text()
@@ -149,13 +168,5 @@ func readTitleAndCreated(path, slug string) (string, string) {
 			}
 		}
 	}
-	if title == "" {
-		title = strings.ReplaceAll(slug, "-", " ")
-	}
-	if created == "" {
-		if info, err := os.Stat(path); err == nil {
-			created = info.ModTime().UTC().Format("2006-01-02")
-		}
-	}
 	return title, created
 }

ingestion/internal/brain/index_root_test.go

@@ -0,0 +1,132 @@
+package brain_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest"
+)
+
+func readIndex(t *testing.T, brainDir, wing string) string {
+	t.Helper()
+	b, _ := os.ReadFile(filepath.Join(brainDir, "wiki", wing, "_index.md"))
+	return string(b)
+}
+
+// hyperguild#157 slice 5: BuildWingIndex listed wiki/<wing>/<hall>/ with
+// os.ReadDir and opened each note by path, so a symlinked note put the
+// target's title into _index.md, and a FIFO hung the index build.
+func TestBuildWingIndexRefusesSymlinkedNotesAndSurvivesSwapRaces(t *testing.T) {
+	b := t.TempDir()
+	facts := filepath.Join(b, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(facts, "ok.md"), []byte("---\ntitle: zqinside\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(facts, "leak.md")))
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(b, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md")))
+
+	require.NoError(t, brain.BuildWingIndex(b, "w"))
+	idx := readIndex(t, b, "w")
+	assert.Contains(t, idx, "zqinside", "positive control")
+	assert.NotContains(t, idx, brainfstest.Sentinel)
+	assert.NotContains(t, idx, "leak")
+	assert.NotContains(t, idx, "inlink")
+
+	p := filepath.Join(facts, "r.md")
+	read := func() string {
+		_ = brain.BuildWingIndex(b, "w")
+		return readIndex(t, b, "w")
+	}
+	brainfstest.AssertNoLeak(t, p, "---\ntitle: zqinside\n---\n", 1500*time.Millisecond, read)
+	brainfstest.AssertNoLeakFrom(t, p, "---\ntitle: zqinside\n---\n", inBrain, 1500*time.Millisecond, read)
+	brainfstest.AssertNoHang(t, p, "---\ntitle: zqinside\n---\n", 1500*time.Millisecond, 6*time.Second, func() { _ = read() })
+}
+
+// A symlinked hall is skipped while a real hall next to it is indexed; a
+// symlinked wing is refused and nothing is written into its target.
+func TestBuildWingIndexSkipsASymlinkedHallAndRefusesASymlinkedWing(t *testing.T) {
+	b := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "raw", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(b, "raw", "facts", "r.md"), []byte("---\ntitle: zqrawonly\n---\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "w", "decisions"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(b, "wiki", "w", "decisions", "d.md"), []byte("---\ntitle: zqrealhall\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "facts"), filepath.Join(b, "wiki", "w", "facts")))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(b, "wiki", "alias")))
+
+	require.NoError(t, brain.BuildWingIndex(b, "w"))
+	idx, err := os.ReadFile(filepath.Join(b, "wiki", "w", "_index.md"))
+	require.NoError(t, err, "the wing index is written")
+	assert.Contains(t, string(idx), "zqrealhall", "the real hall is indexed")
+	assert.NotContains(t, string(idx), "zqrawonly", "the symlinked hall is not")
+
+	assert.Error(t, brain.BuildWingIndex(b, "alias"))
+	_, err = os.Stat(filepath.Join(b, "raw", "_index.md"))
+	assert.True(t, os.IsNotExist(err), "an index was written into the symlinked wing's target")
+}
+
+// BuildAllWingIndexes indexes the real wings and skips a symlinked one.
+func TestBuildAllWingIndexesSkipsASymlinkedWing(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: zqrealwing\n---\n"), 0o644))
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "raw", "facts"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(b, "wiki", "alias")))
+
+	require.NoError(t, brain.BuildAllWingIndexes(b))
+	idx, err := os.ReadFile(filepath.Join(b, "wiki", "w", "_index.md"))
+	require.NoError(t, err)
+	assert.Contains(t, string(idx), "zqrealwing")
+	_, err = os.Stat(filepath.Join(b, "raw", "_index.md"))
+	assert.True(t, os.IsNotExist(err))
+}
+
+// A link to a symlinked note does not resolve: only regular files count as
+// entries, so StripUnresolvedLinks unwraps it.
+func TestStripUnresolvedLinksDoesNotCountASymlinkedNoteAsAnEntry(t *testing.T) {
+	b := t.TempDir()
+	facts := filepath.Join(b, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(facts, "real.md"), []byte("x"), 0o644))
+	brainfstest.WriteSentinelAt(t, filepath.Join(b, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "ghost.md")))
+	out, unlinked, err := brain.StripUnresolvedLinks(b, "see [[real]] and [[ghost]]")
+	require.NoError(t, err)
+	assert.Contains(t, out, "[[real]]", "positive control")
+	assert.NotContains(t, out, "[[ghost]]")
+	assert.Contains(t, unlinked, "ghost")
+}
+
+// A linked tree (knowledge/ or wiki/) that is not a real directory is
+// skipped, not an error: StripUnresolvedLinks runs before every brain_write,
+// and an error there loses the learning.
+func TestStripUnresolvedLinksSkipsALinkedTreeThatIsNotARealDirectory(t *testing.T) {
+	for name, mk := range map[string]func(t *testing.T, b string){
+		"symlink to an in-brain dir": func(t *testing.T, b string) {
+			require.NoError(t, os.MkdirAll(filepath.Join(b, "raw", "k"), 0o755))
+			require.NoError(t, os.Symlink(filepath.Join("raw", "k"), filepath.Join(b, "knowledge")))
+		},
+		"dangling symlink": func(t *testing.T, b string) {
+			require.NoError(t, os.Symlink("nowhere", filepath.Join(b, "knowledge")))
+		},
+		"regular file": func(t *testing.T, b string) {
+			require.NoError(t, os.WriteFile(filepath.Join(b, "knowledge"), []byte("x"), 0o644))
+		},
+	} {
+		t.Run(name, func(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", "real.md"), []byte("x"), 0o644))
+			mk(t, b)
+			out, _, err := brain.StripUnresolvedLinks(b, "learning [[real]] and [[gone]]")
+			require.NoError(t, err)
+			assert.Contains(t, out, "[[real]]", "links into wiki/ still resolve")
+			assert.NotContains(t, out, "[[gone]]")
+		})
+	}
+}

ingestion/internal/brain/linkcheck.go

@@ -1,12 +1,16 @@
 package brain
 
 import (
+	"errors"
 	"fmt"
-	"os"
+	"io/fs"
-	"path/filepath"
+	"log/slog"
+	"path"
 	"regexp"
 	"sort"
 	"strings"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 )
 
 // wikilinkRE matches [[target]] and [[target|Display Text]].
@@ -43,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
@@ -98,29 +107,40 @@ var linkedTrees = []string{"knowledge", "wiki"}
 // one the audit will also resolve.
 func entryIndex(brainDir string) (map[string]struct{}, error) {
 	index := map[string]struct{}{}
+	// Walked through the brain root (hyperguild#157): only regular files
+	// count as entries, so a symlinked .md name cannot make a link resolve.
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return nil, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
 	for _, dir := range linkedTrees {
-		root := filepath.Join(brainDir, dir)
+		if _, err := bfs.Lstat(dir); errors.Is(err, fs.ErrNotExist) {
-		if _, err := os.Stat(root); os.IsNotExist(err) {
 			continue
-		} else if err != nil {
-			return nil, fmt.Errorf("stat %s: %w", dir, err)
 		}
-		err := filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
+		var walkErr error
-			if err != nil {
+		err := bfs.WalkRegular(dir, func(rel string) error {
-				return err
+			if !strings.HasSuffix(rel, ".md") {
-			}
-			if d.IsDir() || !strings.HasSuffix(path, ".md") {
 				return nil
 			}
-			rel, err := filepath.Rel(brainDir, path)
+			index[strings.TrimSuffix(path.Base(rel), ".md")] = struct{}{}
-			if err != nil {
-				return err
-			}
-			rel = filepath.ToSlash(rel)
-			index[strings.TrimSuffix(filepath.Base(rel), ".md")] = struct{}{}
 			index[strings.TrimPrefix(strings.TrimSuffix(rel, ".md"), "wiki/")] = struct{}{}
 			return nil
+		}, func(rel string, err error) {
+			// A linked tree that is not a real directory (a symlink, a
+			// file) is skipped, as filepath.WalkDir did: this runs before
+			// every brain_write, and an error here loses the learning.
+			if rel == dir && errors.Is(err, brainfs.ErrNotRegular) {
+				slog.Warn("link check: skipping a linked tree that is not a real directory", "dir", dir)
+				return
+			}
+			if walkErr == nil {
+				walkErr = fmt.Errorf("%s: %w", rel, err)
+			}
 		})
+		if err == nil {
+			err = walkErr
+		}
 		if err != nil {
 			return nil, fmt.Errorf("walk %s: %w", dir, err)
 		}

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

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

ingestion/internal/brain/tunnel_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/tunnel_root_test.go

@@ -0,0 +1,141 @@
+package brain_test
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+)
+
+// brain_tunnel passes caller-supplied source and target paths to WriteTunnel,
+// which checked only "wiki/<wing>/..." and then joined them onto the brain
+// dir: ".." segments resolved outside the brain and appendSeeAlso rewrote the
+// file there.
+func TestWriteTunnelRefusesATargetThatTraversesOutOfTheBrain(t *testing.T) {
+	brain0 := t.TempDir()
+	src := filepath.Join(brain0, "wiki", "a", "facts", "s.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(src), 0o755))
+	require.NoError(t, os.WriteFile(src, []byte("---\ntitle: S\n---\nbody\n"), 0o644))
+	victim := filepath.Join(t.TempDir(), "victim.md")
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+
+	up := strings.Repeat("../", strings.Count(filepath.Clean(brain0), "/")+3)
+	target := "wiki/b/x/" + up + strings.TrimPrefix(victim, "/")
+	err := brain.WriteTunnel(brain0, "wiki/a/facts/s.md", target)
+	assert.Error(t, err)
+	got, rerr := os.ReadFile(victim)
+	require.NoError(t, rerr)
+	assert.Equal(t, "untouched\n", string(got), "a file outside the brain was modified")
+}
+
+func TestWriteTunnelRefusesUncleanOrNonWikiPaths(t *testing.T) {
+	brain0 := t.TempDir()
+	for _, p := range []string{"wiki/a/facts/s.md", "wiki/b/facts/t.md", "wiki/b/facts/t.txt", "raw/r.md"} {
+		require.NoError(t, os.MkdirAll(filepath.Dir(filepath.Join(brain0, p)), 0o755))
+		require.NoError(t, os.WriteFile(filepath.Join(brain0, p), []byte("x\n"), 0o644))
+	}
+	for _, target := range []string{
+		"wiki/b/facts/../../../raw/r.md",
+		"wiki/b/./facts/t.md",
+		"wiki/b//facts/t.md",
+		"/wiki/b/facts/t.md",
+		"wiki/b/facts/t.txt",
+		"wiki/b/facts/",
+	} {
+		assert.Error(t, brain.WriteTunnel(brain0, "wiki/a/facts/s.md", target), target)
+	}
+	for _, p := range []string{"raw/r.md", "wiki/b/facts/t.txt"} {
+		got, err := os.ReadFile(filepath.Join(brain0, p))
+		require.NoError(t, err)
+		assert.Equal(t, "x\n", string(got), p)
+	}
+	require.NoError(t, brain.WriteTunnel(brain0, "wiki/a/facts/s.md", "wiki/b/facts/t.md"), "positive control")
+	got, err := os.ReadFile(filepath.Join(brain0, "wiki", "b", "facts", "t.md"))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "[[a/facts/s]]")
+}
+
+func TestWriteTunnelDoesNotWriteThroughASymlinkedNote(t *testing.T) {
+	brain0 := t.TempDir()
+	src := filepath.Join(brain0, "wiki", "a", "facts", "s.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(src), 0o755))
+	require.NoError(t, os.WriteFile(src, []byte("x\n"), 0o644))
+	tdir := filepath.Join(brain0, "wiki", "b", "facts")
+	require.NoError(t, os.MkdirAll(tdir, 0o755))
+	victim := filepath.Join(t.TempDir(), "victim.md")
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	require.NoError(t, os.Symlink(victim, filepath.Join(tdir, "t.md")))
+	assert.Error(t, brain.WriteTunnel(brain0, "wiki/a/facts/s.md", "wiki/b/facts/t.md"))
+	got, err := os.ReadFile(victim)
+	require.NoError(t, err)
+	assert.Equal(t, "untouched\n", string(got))
+
+	// The same with a link to a file elsewhere in the brain, which os.Root
+	// would follow.
+	inVictim := filepath.Join(brain0, "raw", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(inVictim), 0o755))
+	require.NoError(t, os.WriteFile(inVictim, []byte("untouched\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "v.md"), filepath.Join(tdir, "u.md")))
+	assert.Error(t, brain.WriteTunnel(brain0, "wiki/a/facts/s.md", "wiki/b/facts/u.md"))
+	got, err = os.ReadFile(inVictim)
+	require.NoError(t, err)
+	assert.Equal(t, "untouched\n", string(got))
+	got, err = os.ReadFile(src)
+	require.NoError(t, err)
+	assert.Equal(t, "x\n", string(got), "the source is not touched when the target is refused")
+}
+
+// The target is swapped between a regular note and a symlink to an in-brain
+// file outside wiki/ while WriteTunnel runs: the read and the write each
+// refuse a symlink, so the other file is never rewritten.
+func TestWriteTunnelNeverRewritesASymlinkSwappedInForTheTarget(t *testing.T) {
+	brain0 := t.TempDir()
+	src := filepath.Join(brain0, "wiki", "a", "facts", "s.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(src), 0o755))
+	require.NoError(t, os.WriteFile(src, []byte("x\n"), 0o644))
+	tdir := filepath.Join(brain0, "wiki", "b", "facts")
+	require.NoError(t, os.MkdirAll(tdir, 0o755))
+	victim := filepath.Join(brain0, "raw", "victim.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	tgt := filepath.Join(tdir, "t.md")
+	require.NoError(t, os.WriteFile(tgt, []byte("t\n"), 0o644))
+
+	var stop atomic.Bool
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		tmp := tgt + ".swap"
+		for i := 0; !stop.Load(); i++ {
+			_ = os.Remove(tmp)
+			if i%2 == 0 {
+				_ = os.WriteFile(tmp, []byte("t\n"), 0o644)
+			} else {
+				_ = os.Symlink(filepath.Join("..", "..", "..", "raw", "victim.md"), tmp)
+			}
+			_ = os.Rename(tmp, tgt)
+		}
+	}()
+	ok := 0
+	for deadline := time.Now().Add(1500 * time.Millisecond); time.Now().Before(deadline); {
+		if brain.WriteTunnel(brain0, "wiki/a/facts/s.md", "wiki/b/facts/t.md") == nil {
+			ok++
+		}
+		_ = os.WriteFile(src, []byte("x\n"), 0o644)
+	}
+	stop.Store(true)
+	wg.Wait()
+	got, err := os.ReadFile(victim)
+	require.NoError(t, err)
+	assert.Equal(t, "untouched\n", string(got), "the swapped-in symlink's target was rewritten")
+	assert.Positive(t, ok, "positive control: some tunnels were written to the regular target")
+}

ingestion/internal/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

@@ -82,9 +82,203 @@ func (b *Brain) realDir(rel string) error {
 	return nil
 }
 
+// ReadDirRegular lists the regular files directly in a brain-relative
+// directory, by name. Every component of relDir must be a real directory
+// (ErrNotRegular otherwise); symlinks, FIFOs, devices and subdirectories in
+// it are left out.
+func (b *Brain) ReadDirRegular(relDir string) ([]string, error) {
+	relDir = filepath.ToSlash(relDir)
+	if err := b.realDir(relDir); err != nil {
+		return nil, err
+	}
+	ents, err := fs.ReadDir(b.root.FS(), relDir)
+	if err != nil {
+		return nil, err
+	}
+	var names []string
+	for _, e := range ents {
+		if e.Type().IsRegular() {
+			names = append(names, e.Name())
+		}
+	}
+	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.
+func (b *Brain) ReadDirDirs(relDir string) ([]string, error) {
+	relDir = filepath.ToSlash(relDir)
+	if err := b.realDir(relDir); err != nil {
+		return nil, err
+	}
+	ents, err := fs.ReadDir(b.root.FS(), relDir)
+	if err != nil {
+		return nil, err
+	}
+	var names []string
+	for _, e := range ents {
+		if e.Type().IsDir() {
+			names = append(names, e.Name())
+		}
+	}
+	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
@@ -92,7 +286,7 @@ func (b *Brain) ReadRegular(rel string) ([]byte, error) {
 	if !fi.Mode().IsRegular() {
 		return nil, fmt.Errorf("%s: %w", rel, ErrNotRegular)
 	}
-	return b.readOpened(rel)
+	return b.readOpenedMax(rel, -1, fi)
 }
 
 // readOpened opens rel non-blocking and reads it only if the OPENED handle is
@@ -106,11 +300,17 @@ func (b *Brain) ReadRegular(rel string) ([]byte, error) {
 // cannot create one; fs.protected_hardlinks=1 and the pod's secrets are on a
 // different filesystem from the brain volume, so a local caller cannot link
 // them in. Refusing Nlink > 1 is the next step if either changes.
-func (b *Brain) readOpened(rel string) ([]byte, error) { return b.readOpenedMax(rel, -1) }
+func (b *Brain) readOpened(rel string) ([]byte, error) { return b.readOpenedMax(rel, -1, nil) }
 
 // 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
@@ -118,10 +318,14 @@ func (b *Brain) ReadRegularMax(rel string, max int64) ([]byte, error) {
 	if !fi.Mode().IsRegular() {
 		return nil, fmt.Errorf("%s: %w", rel, ErrNotRegular)
 	}
-	return b.readOpenedMax(rel, max)
+	return b.readOpenedMax(rel, max, fi)
 }
 
-func (b *Brain) readOpenedMax(rel string, max int64) ([]byte, error) {
+// readOpenedMax opens rel and reads it if the opened handle is a regular file
+// and, when lfi is set, the same file the caller Lstat-ed: os.Root follows an
+// in-root final symlink even with O_NOFOLLOW, so a symlink to another brain
+// file swapped in between the Lstat and the open is refused only here.
+func (b *Brain) readOpenedMax(rel string, max int64, lfi fs.FileInfo) ([]byte, error) {
 	f, err := b.root.OpenFile(rel, os.O_RDONLY|syscall.O_NONBLOCK, 0)
 	if err != nil {
 		return nil, err
@@ -134,6 +338,9 @@ func (b *Brain) readOpenedMax(rel string, max int64) ([]byte, error) {
 	if !hfi.Mode().IsRegular() {
 		return nil, fmt.Errorf("%s: %w", rel, ErrNotRegular)
 	}
+	if lfi != nil && !os.SameFile(lfi, hfi) {
+		return nil, fmt.Errorf("%s: changed while opening: %w", rel, ErrNotRegular)
+	}
 	if max >= 0 && hfi.Size() > max {
 		return nil, fmt.Errorf("%s is %d bytes (limit %d): %w", rel, hfi.Size(), max, ErrTooLarge)
 	}
@@ -199,3 +406,51 @@ func (b *Brain) WalkRegular(relDir string, fn func(rel string) error, onErr func
 		return fn(p)
 	})
 }
+
+// WriteRegular replaces the contents of an existing regular file at a
+// brain-relative path. It never creates a file and never writes through a
+// final symlink: os.Root.OpenFile follows an in-root final symlink even with
+// O_NOFOLLOW (verified on go1.27), so the path is Lstat-ed through the root
+// first and the opened handle must be that same file (os.SameFile), which
+// also catches a swap between the two. O_NONBLOCK keeps a FIFO from blocking
+// the open. Every directory above the file must be a real directory
+// (hyperguild#173); a directory swapped in after that check is the #167
+// residual.
+func (b *Brain) WriteRegular(rel string, data []byte) error {
+	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
+	}
+	if !lfi.Mode().IsRegular() {
+		return fmt.Errorf("%s: %w", rel, ErrNotRegular)
+	}
+	f, err := b.root.OpenFile(rel, os.O_WRONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = f.Close() }()
+	fi, err := f.Stat()
+	if err != nil {
+		return err
+	}
+	if !fi.Mode().IsRegular() || !os.SameFile(lfi, fi) {
+		return fmt.Errorf("%s: changed while opening: %w", rel, ErrNotRegular)
+	}
+	if err := f.Truncate(0); err != nil {
+		return err
+	}
+	if _, err := f.Write(data); err != nil {
+		return err
+	}
+	return f.Close()
+}

ingestion/internal/brainfs/brainfs_test.go

@@ -6,6 +6,8 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"sync"
+	"sync/atomic"
 	"syscall"
 	"testing"
 	"time"
@@ -189,3 +191,341 @@ func TestWalkRegularReportsASymlinkedIntermediateComponentOfTheWalkRoot(t *testi
 	require.Len(t, errs, 1)
 	assert.ErrorIs(t, errs[0], ErrNotRegular)
 }
+
+func TestReadDirRegularListsOnlyRegularFilesAndRefusesSymlinkedComponents(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "a", "b", "sub"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "a", "b", "n.md"), []byte("n"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "other.md"), []byte("o"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "other.md"), filepath.Join(dir, "a", "b", "l.md")))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(dir, "a", "b", "f.md"), 0o644))
+	require.NoError(t, os.Symlink("a", filepath.Join(dir, "alias")))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "x"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "a"), filepath.Join(dir, "x", "mid")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	names, err := b.ReadDirRegular("a/b")
+	require.NoError(t, err)
+	assert.Equal(t, []string{"n.md"}, names)
+	for _, rel := range []string{"alias/b", "x/mid/b"} {
+		_, err := b.ReadDirRegular(rel)
+		assert.ErrorIs(t, err, ErrNotRegular, rel)
+	}
+}
+
+// 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 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")
+	require.NoError(t, os.WriteFile(p, []byte("inside"), 0o644))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	var stop atomic.Bool
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		tmp := p + ".swap"
+		for i := 0; !stop.Load(); i++ {
+			_ = os.Remove(tmp)
+			if i%2 == 0 {
+				_ = os.WriteFile(tmp, []byte("inside"), 0o644)
+			} else {
+				_ = os.Symlink("s.md", tmp)
+			}
+			_ = os.Rename(tmp, p)
+		}
+	}()
+	leaks, ok := 0, 0
+	for deadline := time.Now().Add(1500 * time.Millisecond); time.Now().Before(deadline); {
+		got, err := b.ReadRegular("r.md")
+		if err == nil {
+			ok++
+		}
+		if string(got) == "zqsamefilesentinel" {
+			leaks++
+		}
+		got, _ = b.ReadRegularMax("r.md", 1<<20)
+		if string(got) == "zqsamefilesentinel" {
+			leaks++
+		}
+	}
+	stop.Store(true)
+	wg.Wait()
+	assert.Zero(t, leaks)
+	assert.Positive(t, ok, "positive control: the regular file is read")
+}
+
+func TestWriteRegularRefusesFinalSymlinksFIFOsEscapesAndMissingFilesAndRewritesRegularFiles(t *testing.T) {
+	dir := t.TempDir()
+	outside := filepath.Join(t.TempDir(), "o.md")
+	require.NoError(t, os.WriteFile(outside, []byte("untouched"), 0o644))
+	require.NoError(t, os.Symlink(outside, filepath.Join(dir, "l.md")))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(dir, "f.md"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "n.md"), []byte("old content"), 0o644))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	assert.Error(t, b.WriteRegular("l.md", []byte("x")))
+	got, _ := os.ReadFile(outside)
+	assert.Equal(t, "untouched", string(got))
+
+	// A symlink to another file inside the brain: os.Root would allow it,
+	// only O_NOFOLLOW refuses it.
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "in.md"), []byte("inside"), 0o644))
+	require.NoError(t, os.Symlink("in.md", filepath.Join(dir, "il.md")))
+	assert.Error(t, b.WriteRegular("il.md", []byte("x")))
+	got, _ = os.ReadFile(filepath.Join(dir, "in.md"))
+	assert.Equal(t, "inside", string(got))
+
+	// A reader held open, so a non-blocking write open would succeed. The
+	// Lstat type check refuses the FIFO first; the handle check and
+	// O_NONBLOCK matter only if it is swapped in after the Lstat.
+	r, err := os.OpenFile(filepath.Join(dir, "f.md"), os.O_RDONLY|syscall.O_NONBLOCK, 0)
+	require.NoError(t, err)
+	defer func() { _ = r.Close() }()
+	done := make(chan error, 1)
+	go func() { done <- b.WriteRegular("f.md", []byte("x")) }()
+	select {
+	case err := <-done:
+		assert.Error(t, err)
+	case <-time.After(3 * time.Second):
+		t.Fatal("WriteRegular hung on a FIFO")
+	}
+
+	assert.Error(t, b.WriteRegular("../"+filepath.Base(filepath.Dir(outside))+"/o.md", []byte("x")))
+	assert.Error(t, b.WriteRegular("missing.md", []byte("x")), "does not create files")
+
+	require.NoError(t, b.WriteRegular("n.md", []byte("new")))
+	got, _ = os.ReadFile(filepath.Join(dir, "n.md"))
+	assert.Equal(t, "new", string(got), "truncated and rewritten")
+}
+
+func TestReadDirDirsListsOnlyRealSubdirsAndRefusesSymlinkedComponents(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "a", "real"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "other"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "other"), filepath.Join(dir, "a", "linked")))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "a", "f.md"), []byte("f"), 0o644))
+	require.NoError(t, os.Symlink("a", filepath.Join(dir, "alias")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	names, err := b.ReadDirDirs("a")
+	require.NoError(t, err)
+	assert.Equal(t, []string{"real"}, names)
+	_, 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,12 +1,15 @@
 // 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
 
 import (
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
@@ -17,32 +20,50 @@ 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
+// frontmatter title and aliases, a heading, a wikilink and the body.
+const outsideContent = "---\ntitle: " + Sentinel + "\naliases:\n  - " + Sentinel + "\n---\n# " + Sentinel +
+	"\n\n" + Sentinel + " [[" + Sentinel + "]]\n"
+
 // Outside writes a file outside any brain dir containing Sentinel.
-func Outside(t *testing.T) string {
+func Outside(t testing.TB) string {
 	t.Helper()
 	p := filepath.Join(t.TempDir(), "secret.md")
-	if err := os.WriteFile(p, []byte("# secret\n\n"+Sentinel), 0o644); err != nil {
+	if err := os.WriteFile(p, []byte(outsideContent), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	return p
 }
 
+var swapSeq atomic.Int64
+
 // StartSwap renames, in a loop, a regular note (content inside) and either
 // a symlink to outside or a FIFO into path, until the test ends. FIFOs get a
 // writer held open until the swapper exits, so a reader that skips the
 // handle check parks forever instead of reading EOF. The swapper is stopped
-// and awaited before t.TempDir cleanup.
+// and awaited before t.TempDir cleanup. It returns the number of symlinks
-func StartSwap(t *testing.T, path, inside, outside string, fifo bool) {
+// or FIFOs actually renamed into path so far, so a caller can tell a race
+// that ran from one whose every swap failed (hyperguild#177).
+func StartSwap(t testing.TB, path, inside, outside string, fifo bool) *atomic.Int64 {
 	t.Helper()
+	var swaps atomic.Int64
 	var stop atomic.Bool
 	var wg sync.WaitGroup
 	wg.Add(1)
 	go func() {
 		defer wg.Done()
-		tmp := path + ".swap"
+		// A name of its own: swappers on one path share a test, and one
+		// opening another's FIFO for write would block forever.
+		tmp := fmt.Sprintf("%s.swap%d", path, swapSeq.Add(1))
+		// A relative link: os.Root refuses every absolute link on its own, so
+		// an absolute in-brain target would test nothing.
+		link := outside
+		if rel, err := filepath.Rel(filepath.Dir(path), outside); err == nil {
+			link = rel
+		}
 		var writers []*os.File
 		defer func() {
 			for _, w := range writers {
@@ -51,35 +72,84 @@ func StartSwap(t *testing.T, path, inside, outside string, fifo bool) {
 		}()
 		for i := 0; !stop.Load(); i++ {
 			_ = os.Remove(tmp)
+			var made error
 			switch {
 			case i%2 == 0:
 				_ = os.WriteFile(tmp, []byte(inside), 0o644)
 			case fifo:
-				if err := syscall.Mkfifo(tmp, 0o644); err == nil {
+				if made = syscall.Mkfifo(tmp, 0o644); made == nil {
 					if w, err := os.OpenFile(tmp, os.O_RDWR, 0); err == nil {
 						writers = append(writers, w)
 					}
 				}
 			default:
-				_ = os.Symlink(outside, tmp)
+				made = os.Symlink(link, tmp)
+			}
+			if err := os.Rename(tmp, path); err == nil && made == nil && i%2 == 1 {
+				swaps.Add(1)
 			}
-			_ = os.Rename(tmp, path)
 		}
 	}()
 	t.Cleanup(func() { stop.Store(true); wg.Wait() })
+	return &swaps
+}
+
+// WriteSentinelAt writes a file carrying Sentinel at p (creating its
+// directory), for an in-brain symlink target.
+func WriteSentinelAt(t *testing.T, p string) string {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(p, []byte(outsideContent), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return p
 }
 
 // AssertNoLeak loops read for d while a symlink swapper runs on path, and
-// fails if any output contains Sentinel.
+// fails if any output contains Sentinel. The symlink points outside the
+// brain; os.Root refuses that on its own, so pair it with AssertNoLeakFrom
+// and an in-brain target.
 func AssertNoLeak(t *testing.T, path, inside string, d time.Duration, read func() string) {
 	t.Helper()
-	StartSwap(t, path, inside, Outside(t), false)
+	AssertNoLeakFrom(t, path, inside, Outside(t), d, read)
-	leaks, iters := 0, 0
+}
+
+// InsideMarker must appear in the inside note's content and in read's
+// output whenever read saw that note: the floor below counts such reads.
+const InsideMarker = "inside"
+
+// AssertNoLeakFrom is AssertNoLeak with the symlink pointing at target, e.g.
+// a file elsewhere in the brain written with WriteSentinelAt.
+//
+// Beyond "no Sentinel in any output" it sets two floors, because without
+// them the assertion passes when nothing was tested (hyperguild#177): at
+// least one symlink must have been swapped into path, and at least one read
+// must have returned InsideMarker (a reader that always errors returns
+// nothing, and so never leaks).
+func AssertNoLeakFrom(t testing.TB, path, inside, target string, d time.Duration, read func() string) {
+	t.Helper()
+	if !strings.Contains(inside, InsideMarker) {
+		t.Fatalf("inside content must contain %q", InsideMarker)
+	}
+	swaps := StartSwap(t, path, inside, target, false)
+	leaks, iters, insideReads := 0, 0, 0
 	for deadline := time.Now().Add(d); time.Now().Before(deadline); iters++ {
-		leaks += strings.Count(read(), Sentinel)
+		out := read()
+		leaks += strings.Count(out, Sentinel)
+		if strings.Contains(out, InsideMarker) {
+			insideReads++
+		}
 	}
 	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)
+	}
+	if insideReads == 0 {
+		t.Fatalf("no read in %d iterations returned the inside note (%q): the reader read nothing", iters, InsideMarker)
 	}
 }
 

ingestion/internal/brainfs/brainfstest/brainfstest_test.go

@@ -0,0 +1,79 @@
+package brainfstest
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"syscall"
+	"testing"
+	"time"
+)
+
+// recordingTB stands in for the test under AssertNoLeakFrom so a fatal
+// there can be observed instead of failing this test. Fatalf ends the
+// calling goroutine the way testing.T does.
+type recordingTB struct {
+	testing.TB
+	failed bool
+	msg    string
+}
+
+func (r *recordingTB) Fatalf(format string, args ...any) {
+	r.failed, r.msg = true, fmt.Sprintf(format, args...)
+	runtime.Goexit()
+}
+
+func runAssert(t *testing.T, path, target string, read func() string) *recordingTB {
+	t.Helper()
+	r := &recordingTB{TB: t}
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		AssertNoLeakFrom(r, path, "inside", target, 200*time.Millisecond, read)
+	}()
+	<-done
+	return r
+}
+
+// hyperguild#177: with every swap failing, no leak can occur, so the leak
+// assertion passed without testing anything.
+func TestAssertNoLeakFromFailsWhenNoSymlinkSwapSucceeds(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "missing-dir", "r.md")
+	r := runAssert(t, path, Outside(t), func() string { return "inside" })
+	if !r.failed {
+		t.Fatal("AssertNoLeakFrom passed with zero successful symlink swaps")
+	}
+}
+
+// hyperguild#177: a reader that always errors returns nothing, so it never
+// leaks either.
+func TestAssertNoLeakFromFailsWhenNoReadReturnsTheInsideNote(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "r.md")
+	r := runAssert(t, path, Outside(t), func() string { return "" })
+	if !r.failed {
+		t.Fatal("AssertNoLeakFrom passed with zero reads returning the inside note")
+	}
+}
+
+// Positive control: a reader that refuses symlinks and reads regular files
+// passes, so the floors do not fail a working reader.
+func TestAssertNoLeakFromPassesAReaderThatRefusesSymlinks(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "r.md")
+	read := func() string {
+		f, err := os.OpenFile(path, os.O_RDONLY|noFollow, 0)
+		if err != nil {
+			return ""
+		}
+		defer func() { _ = f.Close() }()
+		b := make([]byte, 64)
+		n, _ := f.Read(b)
+		return string(b[:n])
+	}
+	r := runAssert(t, path, Outside(t), read)
+	if r.failed {
+		t.Fatalf("a symlink-refusing reader failed: %s", r.msg)
+	}
+}
+
+const noFollow = syscall.O_NOFOLLOW

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/graphsync/graphsync.go

@@ -12,10 +12,14 @@ package graphsync
 
 import (
 	"context"
+	"errors"
 	"fmt"
-	"os"
+	"io/fs"
+	"path"
 	"path/filepath"
+	"strings"
 
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/graph"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/graphstore"
 )
@@ -46,8 +50,25 @@ func IndexDoc(ctx context.Context, store Store, brainDir, relPath string) error
 	if relPath == "" {
 		return nil
 	}
-	abs := filepath.Join(brainDir, filepath.FromSlash(relPath))
+	// Callers pass caller-supplied paths (brain_tunnel, brain_update): index
-	content, err := os.ReadFile(abs)
+	// only a clean path under wiki/ or knowledge/.
+	if path.Clean(relPath) != relPath || !filepath.IsLocal(relPath) ||
+		(!strings.HasPrefix(relPath, "wiki/") && !strings.HasPrefix(relPath, "knowledge/")) {
+		return fmt.Errorf("index %q: not a clean wiki/ or knowledge/ path", relPath)
+	}
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	return indexDoc(ctx, store, bfs, relPath)
+}
+
+// indexDoc reads relPath through the brain root, regular files only
+// (hyperguild#157): the brain is a Syncthing folder, and os.ReadFile
+// followed a synced symlink into the graph and blocked on a FIFO.
+func indexDoc(ctx context.Context, store Store, bfs *brainfs.Brain, relPath string) error {
+	content, err := bfs.ReadRegular(relPath)
 	if err != nil {
 		return fmt.Errorf("read %q: %w", relPath, err)
 	}
@@ -77,33 +98,34 @@ func BackfillFromBrainDir(ctx context.Context, store Store, brainDir string) (in
 	if store == nil {
 		return 0, nil
 	}
-	roots := []string{"wiki", "knowledge"}
+	bfs, err := brainfs.Open(brainDir)
-	for _, root := range roots {
+	if err != nil {
-		base := filepath.Join(brainDir, root)
+		return 0, fmt.Errorf("open brain: %w", err)
-		if _, err := os.Stat(base); os.IsNotExist(err) {
+	}
+	defer func() { _ = bfs.Close() }()
+	for _, root := range []string{"wiki", "knowledge"} {
+		if _, err := bfs.Lstat(root); errors.Is(err, fs.ErrNotExist) {
 			continue
 		}
-		err := filepath.WalkDir(base, func(path string, d os.DirEntry, walkErr error) error {
+		// Any walk error, including a root that is a symlink, aborts.
-			if walkErr != nil {
+		var walkErr error
-				return walkErr
+		err := bfs.WalkRegular(root, func(rel string) error {
-			}
+			if path.Ext(rel) != ".md" {
-			if d.IsDir() {
 				return nil
 			}
-			if filepath.Ext(path) != ".md" {
+			if err := indexDoc(ctx, store, bfs, rel); err != nil {
-				return nil
-			}
-			rel, relErr := filepath.Rel(brainDir, path)
-			if relErr != nil {
-				return fmt.Errorf("rel %q: %w", path, relErr)
-			}
-			rel = filepath.ToSlash(rel)
-			if err := IndexDoc(ctx, store, brainDir, rel); err != nil {
 				return fmt.Errorf("index %q: %w", rel, err)
 			}
 			indexed++
 			return nil
+		}, func(rel string, err error) {
+			if walkErr == nil {
+				walkErr = fmt.Errorf("%s: %w", rel, err)
+			}
 		})
+		if err == nil {
+			err = walkErr
+		}
 		if err != nil {
 			return indexed, fmt.Errorf("walk %s: %w", root, err)
 		}

ingestion/internal/graphsync/graphsync_root_test.go

@@ -0,0 +1,92 @@
+package graphsync
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest"
+)
+
+func (f *fakeStore) dump() string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return fmt.Sprintf("%+v %+v", f.upserts, f.replaces)
+}
+
+// hyperguild#157 slice 4: IndexDoc and BackfillFromBrainDir read notes with
+// os.ReadFile, so a symlinked note put the target's title and wikilinks into
+// the graph, and a FIFO hung the read.
+func TestIndexDocRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) {
+	brain := t.TempDir()
+	facts := filepath.Join(brain, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(facts, "ok.md"), []byte("---\ntitle: zqinside\n---\nbody [[other]]\n"), 0o644))
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(facts, "leak.md")))
+
+	store := newFakeStore()
+	require.NoError(t, IndexDoc(context.Background(), store, brain, "wiki/w/facts/ok.md"))
+	assert.Contains(t, store.dump(), "zqinside", "positive control: a regular note is indexed")
+	assert.Error(t, IndexDoc(context.Background(), store, brain, "wiki/w/facts/leak.md"))
+	// A link to a file elsewhere in the brain: os.Root allows it, only the
+	// regular-file check refuses it.
+	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.Error(t, IndexDoc(context.Background(), store, brain, "wiki/w/facts/inlink.md"))
+	assert.NotContains(t, store.dump(), brainfstest.Sentinel)
+
+	p := filepath.Join(facts, "r.md")
+	read := func() string {
+		s := newFakeStore()
+		_ = IndexDoc(context.Background(), s, brain, "wiki/w/facts/r.md")
+		return s.dump()
+	}
+	brainfstest.AssertNoLeak(t, p, "---\ntitle: zqinside\n---\n", 1500*time.Millisecond, read)
+	brainfstest.AssertNoLeakFrom(t, p, "---\ntitle: zqinside\n---\n", inBrain, 1500*time.Millisecond, read)
+	brainfstest.AssertNoHang(t, p, "---\ntitle: zqinside\n---\n", 1500*time.Millisecond, 6*time.Second, func() { _ = read() })
+}
+
+func TestBackfillSkipsSymlinkedNotesAndAbortsOnASymlinkedRoot(t *testing.T) {
+	brain := t.TempDir()
+	facts := filepath.Join(brain, "wiki", "w", "facts")
+	require.NoError(t, os.MkdirAll(facts, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(facts, "ok.md"), []byte("---\ntitle: zqinside\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(facts, "leak.md")))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "raw"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "raw", "r.md"), []byte("---\ntitle: zqrawonly\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "r.md"), filepath.Join(facts, "inlink.md")))
+	require.NoError(t, os.Symlink(".", filepath.Join(brain, "knowledge")))
+
+	store := newFakeStore()
+	_, err := BackfillFromBrainDir(context.Background(), store, brain)
+	assert.Error(t, err, "a symlinked root aborts the backfill")
+	assert.NotContains(t, store.dump(), brainfstest.Sentinel)
+	assert.NotContains(t, store.dump(), "zqrawonly")
+
+	require.NoError(t, os.Remove(filepath.Join(brain, "knowledge")))
+	store = newFakeStore()
+	n, err := BackfillFromBrainDir(context.Background(), store, brain)
+	require.NoError(t, err)
+	assert.Equal(t, 1, n, "only the regular note is indexed")
+	assert.Contains(t, store.dump(), "zqinside")
+	assert.NotContains(t, store.dump(), brainfstest.Sentinel)
+}
+
+// IndexDoc gets caller-supplied paths (brain_tunnel, brain_update): only a
+// clean path under wiki/ or knowledge/ is indexed.
+func TestIndexDocRefusesPathsOutsideWikiAndKnowledgeAndUncleanPaths(t *testing.T) {
+	brain := t.TempDir()
+	brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "secret.md"))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki", "w"), 0o755))
+	for _, p := range []string{"raw/secret.md", "wiki/w/../../raw/secret.md", "./raw/secret.md", "/raw/secret.md"} {
+		store := newFakeStore()
+		assert.Error(t, IndexDoc(context.Background(), store, brain, p), p)
+		assert.NotContains(t, store.dump(), brainfstest.Sentinel, p)
+	}
+}

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/migrate/migrate.go

@@ -0,0 +1,309 @@
+// Package migrate moves pages out of the retired wiki/{sources,concepts,
+// entities}/ layout into wiki/<wing>/{sources,facts}/ (hyperguild#205).
+//
+// It is a two-step tool on purpose. BuildPlan only reads and decides; Apply
+// performs exactly the items the plan marked Auto and nothing else. Sources are
+// placed by the wing Resolver. Concepts and entities have no wing of their own:
+// they inherit the strict-majority wing of the sources that cite them, which is
+// deterministic and needs no model. Whatever cannot be placed safely is an
+// Exception, left where it is for a human.
+package migrate
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io/fs"
+	"path"
+	"regexp"
+	"sort"
+	"strings"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/wing"
+)
+
+// Status is whether the plan moves a page by itself.
+type Status string
+
+const (
+	Auto      Status = "auto"
+	Exception Status = "exception"
+)
+
+// Item is one planned move.
+type Item struct {
+	From       string // brain-relative, e.g. wiki/entities/jev.md
+	To         string // brain-relative; empty for an Exception without a proposal
+	Slug       string
+	Kind       string // source | concept | entity
+	Wing       string // decided wing, or the proposal for an Exception
+	Status     Status
+	Method     string // resolver | inherited | junk | blocked
+	Confidence float64
+	Reason     string
+}
+
+// ResolverFor returns the Resolver to use for one page. It takes the page's
+// own path so a scorer can exclude the page from its evidence.
+type ResolverFor func(excludePath string) *wing.Resolver
+
+var (
+	linkSlugRE = regexp.MustCompile(`\[\[([^|\]]+)`)
+	legacy     = []struct{ dir, kind string }{
+		{"wiki/sources", "source"},
+		{"wiki/concepts", "concept"},
+		{"wiki/entities", "entity"},
+	}
+)
+
+// BuildPlan reads the legacy layout and decides, without writing anything.
+func BuildPlan(ctx context.Context, brainDir string, rf ResolverFor) ([]Item, error) {
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return nil, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+
+	taken, err := slugsInWings(bfs)
+	if err != nil {
+		return nil, err
+	}
+
+	var items []Item
+	decided := map[string]Item{} // source slug -> its decision
+	for _, l := range legacy {
+		names, err := bfs.ReadDirRegular(l.dir)
+		if errors.Is(err, fs.ErrNotExist) {
+			continue
+		}
+		if err != nil {
+			return nil, fmt.Errorf("read %s: %w", l.dir, err)
+		}
+		for _, name := range names {
+			if !strings.HasSuffix(name, ".md") || name == "_index.md" {
+				continue
+			}
+			rel := l.dir + "/" + name
+			slug := strings.TrimSuffix(name, ".md")
+			it := Item{From: rel, Slug: slug, Kind: l.kind}
+			if strings.HasPrefix(name, "tunnel-candidates-") {
+				it.Status, it.Method, it.Reason = Exception, "junk", "auto-tunnel review log ingested as a source; not a source"
+				items = append(items, it)
+				continue
+			}
+			content, err := bfs.ReadRegular(rel)
+			if err != nil {
+				it.Status, it.Method, it.Reason = Exception, "blocked", fmt.Sprintf("unreadable: %v", err)
+				items = append(items, it)
+				continue
+			}
+			if l.kind == "source" {
+				d := rf(rel).Resolve(ctx, wing.Note{Text: string(content), FrontmatterWing: frontmatterValue(string(content), "wing")})
+				it.Method, it.Wing, it.Confidence, it.Reason = "resolver", d.Wing, d.Confidence, d.Reason
+				if d.Source == wing.Exception {
+					it.Status = Exception
+				} else {
+					it.Status, it.To = Auto, "wiki/"+d.Wing+"/sources/"+name
+				}
+				decided[slug] = it
+			}
+			items = append(items, it)
+		}
+	}
+
+	// Second pass: concepts and entities inherit from their sources.
+	for i, it := range items {
+		if it.Kind == "source" || it.Method == "junk" || it.Method == "blocked" {
+			continue
+		}
+		content, err := bfs.ReadRegular(it.From)
+		if err != nil {
+			continue
+		}
+		it.Method = "inherited"
+		w, reason := inheritedWing(string(content), decided)
+		if w == "" {
+			it.Status, it.Reason = Exception, reason
+		} else {
+			it.Status, it.Wing, it.To = Auto, w, "wiki/"+w+"/facts/"+it.Slug+".md"
+			it.Reason = fmt.Sprintf("strict majority of its sources are in %q", w)
+		}
+		items[i] = it
+	}
+
+	blockCollisions(bfs, items, taken)
+	sort.SliceStable(items, func(i, j int) bool { return items[i].From < items[j].From })
+	return items, nil
+}
+
+// inheritedWing returns the wing held by a strict majority of the legacy
+// sources cited in the page's "## Sources" section, or "" with the reason.
+func inheritedWing(content string, decided map[string]Item) (string, string) {
+	section := sourcesSection(content)
+	if section == "" {
+		return "", "page has no Sources section to inherit a wing from"
+	}
+	total := 0
+	votes := map[string]int{}
+	for _, m := range linkSlugRE.FindAllStringSubmatch(section, -1) {
+		d, ok := decided[strings.TrimSpace(m[1])]
+		if !ok {
+			continue // not a legacy source (already migrated, or not a source)
+		}
+		total++
+		if d.Status == Auto {
+			votes[d.Wing]++
+		}
+	}
+	if total == 0 {
+		return "", "none of its cited sources are in the legacy layout"
+	}
+	for w, n := range votes {
+		if n*2 > total {
+			return w, ""
+		}
+	}
+	return "", fmt.Sprintf("its %d cited sources disagree on a wing or were not placed", total)
+}
+
+// blockCollisions turns an Auto item into an Exception when its destination
+// exists, its slug is already used in some wing (graph identity is the slug
+// alone), or two planned items would land on the same path.
+func blockCollisions(bfs *brainfs.Brain, items []Item, taken map[string]string) {
+	planned := map[string]int{}
+	for _, it := range items {
+		if it.Status == Auto {
+			planned[it.To]++
+		}
+	}
+	for i, it := range items {
+		if it.Status != Auto {
+			continue
+		}
+		switch {
+		case planned[it.To] > 1:
+			items[i].Status, items[i].Reason = Exception, fmt.Sprintf("another legacy page would land on %s", it.To)
+		case exists(bfs, it.To):
+			items[i].Status, items[i].Reason = Exception, fmt.Sprintf("%s already exists", it.To)
+		default:
+			if other, ok := taken[it.Slug]; ok {
+				items[i].Status, items[i].Reason = Exception, fmt.Sprintf("slug %q is already used by %s", it.Slug, other)
+			}
+		}
+	}
+}
+
+func exists(bfs *brainfs.Brain, rel string) bool {
+	_, err := bfs.Lstat(rel)
+	return err == nil
+}
+
+// slugsInWings maps every slug under wiki/<wing>/<hall>/ to its path.
+func slugsInWings(bfs *brainfs.Brain) (map[string]string, error) {
+	out := map[string]string{}
+	wings, err := bfs.ReadDirDirs("wiki")
+	if errors.Is(err, fs.ErrNotExist) {
+		return out, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("list wiki: %w", err)
+	}
+	for _, w := range wings {
+		if w == "sources" || w == "concepts" || w == "entities" {
+			continue
+		}
+		halls, err := bfs.ReadDirDirs("wiki/" + w)
+		if err != nil {
+			continue
+		}
+		for _, h := range halls {
+			names, err := bfs.ReadDirRegular("wiki/" + w + "/" + h)
+			if err != nil {
+				continue
+			}
+			for _, n := range names {
+				if strings.HasSuffix(n, ".md") && n != "_index.md" {
+					out[strings.TrimSuffix(n, ".md")] = "wiki/" + w + "/" + h + "/" + n
+				}
+			}
+		}
+	}
+	return out, nil
+}
+
+// Apply performs the Auto items, one at a time, and stops at the first
+// failure. Each move writes the destination with O_EXCL, then removes the
+// source, so a failure never loses a page. Exceptions are not touched.
+func Apply(brainDir string, items []Item) (int, error) {
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return 0, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+
+	n := 0
+	touched := map[string]bool{}
+	for _, it := range items {
+		if it.Status != Auto {
+			continue
+		}
+		content, err := bfs.ReadRegular(it.From)
+		if err != nil {
+			return n, fmt.Errorf("read %s: %w", it.From, err)
+		}
+		hall := path.Base(path.Dir(it.To))
+		if err := bfs.CreateRegular(it.To, []byte(stamp(string(content), it.Wing, hall, it.Kind))); err != nil {
+			return n, fmt.Errorf("write %s: %w", it.To, err)
+		}
+		if err := bfs.Remove(it.From); err != nil {
+			return n, fmt.Errorf("moved to %s but removing %s failed: %w", it.To, it.From, err)
+		}
+		touched[it.Wing] = true
+		n++
+	}
+	for w := range touched {
+		_ = brain.BuildWingIndex(brainDir, w) // best-effort upkeep; the pages are already moved
+	}
+	return n, nil
+}
+
+// stamp inserts wing/hall (and kind for facts) after the opening fence, leaving
+// every other byte of the page alone. A page without frontmatter gets a block.
+func stamp(content, w, hall, kind string) string {
+	extra := "wing: " + w + "\nhall: " + hall + "\n"
+	if hall == "facts" {
+		extra += "kind: " + kind + "\n"
+	}
+	if strings.HasPrefix(content, "---\n") {
+		return "---\n" + extra + content[4:]
+	}
+	return "---\n" + extra + "---\n" + content
+}
+
+// sourcesSection returns the text under a "## Sources" heading up to the next
+// "## " heading.
+func sourcesSection(content string) string {
+	_, rest, ok := strings.Cut(content, "\n## Sources")
+	if !ok {
+		return ""
+	}
+	if i := strings.Index(rest, "\n## "); i >= 0 {
+		rest = rest[:i]
+	}
+	return rest
+}
+
+func frontmatterValue(content, key string) string {
+	if !strings.HasPrefix(content, "---\n") {
+		return ""
+	}
+	block, _, _ := strings.Cut(content[4:], "\n---")
+	for _, line := range strings.Split(block, "\n") {
+		if k, v, ok := strings.Cut(line, ":"); ok && strings.TrimSpace(k) == key {
+			return strings.Trim(strings.TrimSpace(v), `"'`)
+		}
+	}
+	return ""
+}

ingestion/internal/migrate/migrate_test.go

@@ -0,0 +1,243 @@
+package migrate_test
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/migrate"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/wing"
+)
+
+// keywordClassifier picks a wing by a marker word in the text, and the scorer
+// agrees by the same marker, so a page "belongs" to the wing whose marker it holds.
+type keywordClassifier struct{}
+
+func (keywordClassifier) Classify(_ context.Context, text string, _ []string) (wing.Suggestion, error) {
+	for _, w := range []string{"alpha", "beta"} {
+		if strings.Contains(text, strings.ToUpper(w)) {
+			return wing.Suggestion{Wing: w, Confidence: 0.95, Reason: "marker"}, nil
+		}
+	}
+	return wing.Suggestion{}, nil
+}
+
+type keywordScorer struct{}
+
+func (keywordScorer) Score(text string) map[string]float64 {
+	out := map[string]float64{}
+	for _, w := range []string{"alpha", "beta"} {
+		if strings.Contains(text, strings.ToUpper(w)) {
+			out[w] = 1
+		}
+	}
+	return out
+}
+
+func resolverFor(string) *wing.Resolver {
+	return &wing.Resolver{
+		Known:      []string{"alpha", "beta", "client"},
+		Eligible:   func(w string) bool { return w != "client" },
+		Classifier: keywordClassifier{},
+		Scorer:     keywordScorer{},
+		Threshold:  0.8,
+	}
+}
+
+func page(t *testing.T, dir, rel, body string) {
+	t.Helper()
+	full := filepath.Join(dir, rel)
+	require.NoError(t, os.MkdirAll(filepath.Dir(full), 0o755))
+	require.NoError(t, os.WriteFile(full, []byte(body), 0o644))
+}
+
+func src(title, marker string) string {
+	return "---\ntitle: " + title + "\ntype: video\n---\n\n## Summary\n\n" + marker + " content.\n"
+}
+
+func entity(title string, sources ...string) string {
+	var b strings.Builder
+	b.WriteString("---\ntitle: " + title + "\ntype: tool\n---\n\n## Definition\n\nA thing.\n\n## Sources\n\n")
+	for _, s := range sources {
+		b.WriteString("- [[" + s + "|" + s + "]]\n")
+	}
+	return b.String()
+}
+
+func byFrom(items []migrate.Item) map[string]migrate.Item {
+	m := map[string]migrate.Item{}
+	for _, it := range items {
+		m[it.From] = it
+	}
+	return m
+}
+
+func TestPlan_AResolvedSourceGoesToItsWingsSourcesHall(t *testing.T) {
+	dir := t.TempDir()
+	page(t, dir, "wiki/sources/talk-a.md", src("Talk A", "ALPHA"))
+
+	items, err := migrate.BuildPlan(context.Background(), dir, resolverFor)
+	require.NoError(t, err)
+	it := byFrom(items)["wiki/sources/talk-a.md"]
+	assert.Equal(t, migrate.Auto, it.Status)
+	assert.Equal(t, "wiki/alpha/sources/talk-a.md", it.To)
+}
+
+func TestPlan_AutoTunnelLogsAreJunkNotSources(t *testing.T) {
+	dir := t.TempDir()
+	page(t, dir, "wiki/sources/tunnel-candidates-2026-06-14.md", src("t", "ALPHA"))
+
+	items, err := migrate.BuildPlan(context.Background(), dir, resolverFor)
+	require.NoError(t, err)
+	it := byFrom(items)["wiki/sources/tunnel-candidates-2026-06-14.md"]
+	assert.Equal(t, migrate.Exception, it.Status, "never auto-moved, whatever the classifier says")
+	assert.Equal(t, "junk", it.Method)
+}
+
+func TestPlan_AnEntityFollowsTheMajorityWingOfItsSources(t *testing.T) {
+	dir := t.TempDir()
+	page(t, dir, "wiki/sources/a1.md", src("A1", "ALPHA"))
+	page(t, dir, "wiki/sources/a2.md", src("A2", "ALPHA"))
+	page(t, dir, "wiki/sources/b1.md", src("B1", "BETA"))
+	page(t, dir, "wiki/entities/jev.md", entity("Jev", "a1", "a2", "b1"))
+	page(t, dir, "wiki/concepts/factory.md", "---\ntitle: Factory\n---\n\n## Definition\n\nx\n\n## Sources\n\n- [[a1|A1]]\n")
+
+	items, err := migrate.BuildPlan(context.Background(), dir, resolverFor)
+	require.NoError(t, err)
+	m := byFrom(items)
+	assert.Equal(t, "wiki/alpha/facts/jev.md", m["wiki/entities/jev.md"].To)
+	assert.Equal(t, "entity", m["wiki/entities/jev.md"].Kind)
+	assert.Equal(t, "wiki/alpha/facts/factory.md", m["wiki/concepts/factory.md"].To)
+	assert.Equal(t, "concept", m["wiki/concepts/factory.md"].Kind)
+}
+
+func TestPlan_ATieBetweenWingsIsAnException(t *testing.T) {
+	dir := t.TempDir()
+	page(t, dir, "wiki/sources/a1.md", src("A1", "ALPHA"))
+	page(t, dir, "wiki/sources/b1.md", src("B1", "BETA"))
+	page(t, dir, "wiki/entities/jev.md", entity("Jev", "a1", "b1"))
+
+	items, err := migrate.BuildPlan(context.Background(), dir, resolverFor)
+	require.NoError(t, err)
+	it := byFrom(items)["wiki/entities/jev.md"]
+	assert.Equal(t, migrate.Exception, it.Status)
+	assert.Contains(t, it.Reason, "disagree")
+}
+
+func TestPlan_AnEntityWhoseSourcesWereNotPlacedIsAnException(t *testing.T) {
+	dir := t.TempDir()
+	page(t, dir, "wiki/sources/mystery.md", src("Mystery", "nothing recognisable"))
+	page(t, dir, "wiki/entities/orphan.md", entity("Orphan", "mystery"))
+	page(t, dir, "wiki/entities/nosources.md", "---\ntitle: No Sources\n---\n\n## Definition\n\nx\n")
+
+	items, err := migrate.BuildPlan(context.Background(), dir, resolverFor)
+	require.NoError(t, err)
+	m := byFrom(items)
+	assert.Equal(t, migrate.Exception, m["wiki/entities/orphan.md"].Status)
+	assert.Equal(t, migrate.Exception, m["wiki/entities/nosources.md"].Status)
+}
+
+func TestPlan_ADestinationThatAlreadyExistsIsAnException(t *testing.T) {
+	dir := t.TempDir()
+	page(t, dir, "wiki/sources/talk-a.md", src("Talk A", "ALPHA"))
+	page(t, dir, "wiki/alpha/sources/talk-a.md", "someone else's page")
+
+	items, err := migrate.BuildPlan(context.Background(), dir, resolverFor)
+	require.NoError(t, err)
+	it := byFrom(items)["wiki/sources/talk-a.md"]
+	assert.Equal(t, migrate.Exception, it.Status)
+	assert.Contains(t, it.Reason, "already exists", "the occupied destination is named as the reason, not a generic slug clash")
+}
+
+func TestPlan_ASlugAlreadyUsedInAnotherWingIsAnException(t *testing.T) {
+	// Graph identity is the slug alone; two pages with one slug would merge.
+	dir := t.TempDir()
+	page(t, dir, "wiki/sources/talk-a.md", src("Talk A", "ALPHA"))
+	page(t, dir, "wiki/beta/facts/talk-a.md", "a beta page with the same slug")
+
+	items, err := migrate.BuildPlan(context.Background(), dir, resolverFor)
+	require.NoError(t, err)
+	it := byFrom(items)["wiki/sources/talk-a.md"]
+	assert.Equal(t, migrate.Exception, it.Status)
+	assert.Contains(t, it.Reason, "slug")
+}
+
+func TestApply_MovesOnlyAutoItemsAndStampsFrontmatterWithoutTouchingTheBody(t *testing.T) {
+	dir := t.TempDir()
+	body := src("Talk A", "ALPHA") + "\nSee [[jev|Jev]] and [[unknown-slug]].\n"
+	page(t, dir, "wiki/sources/talk-a.md", body)
+	page(t, dir, "wiki/sources/tunnel-candidates-2026-06-14.md", src("t", "ALPHA"))
+	page(t, dir, "wiki/entities/jev.md", entity("Jev", "talk-a"))
+
+	items, err := migrate.BuildPlan(context.Background(), dir, resolverFor)
+	require.NoError(t, err)
+	n, err := migrate.Apply(dir, items)
+	require.NoError(t, err)
+	assert.Equal(t, 2, n)
+
+	moved, err := os.ReadFile(filepath.Join(dir, "wiki/alpha/sources/talk-a.md"))
+	require.NoError(t, err)
+	assert.Contains(t, string(moved), "wing: alpha")
+	assert.Contains(t, string(moved), "hall: sources")
+	assert.Contains(t, string(moved), "See [[jev|Jev]] and [[unknown-slug]].", "links and body are byte-preserved")
+
+	ent, err := os.ReadFile(filepath.Join(dir, "wiki/alpha/facts/jev.md"))
+	require.NoError(t, err)
+	assert.Contains(t, string(ent), "kind: entity")
+
+	_, err = os.Stat(filepath.Join(dir, "wiki/sources/talk-a.md"))
+	assert.ErrorIs(t, err, os.ErrNotExist, "the original is removed after the copy is written")
+	_, err = os.Stat(filepath.Join(dir, "wiki/sources/tunnel-candidates-2026-06-14.md"))
+	assert.NoError(t, err, "an exception is left exactly where it is")
+}
+
+func TestApply_NeverOverwritesAndKeepsTheSourceWhenTheDestinationAppearsLate(t *testing.T) {
+	dir := t.TempDir()
+	page(t, dir, "wiki/sources/talk-a.md", src("Talk A", "ALPHA"))
+	items, err := migrate.BuildPlan(context.Background(), dir, resolverFor)
+	require.NoError(t, err)
+	page(t, dir, "wiki/alpha/sources/talk-a.md", "appeared after the plan")
+
+	n, err := migrate.Apply(dir, items)
+	require.Error(t, err)
+	assert.Zero(t, n)
+	got, _ := os.ReadFile(filepath.Join(dir, "wiki/alpha/sources/talk-a.md"))
+	assert.Equal(t, "appeared after the plan", string(got))
+	_, statErr := os.Stat(filepath.Join(dir, "wiki/sources/talk-a.md"))
+	assert.NoError(t, statErr, "the source survives a failed write")
+}
+
+func TestPlan_IsEmptyOnceEverythingIsMigrated(t *testing.T) {
+	dir := t.TempDir()
+	page(t, dir, "wiki/sources/talk-a.md", src("Talk A", "ALPHA"))
+	items, err := migrate.BuildPlan(context.Background(), dir, resolverFor)
+	require.NoError(t, err)
+	_, err = migrate.Apply(dir, items)
+	require.NoError(t, err)
+
+	again, err := migrate.BuildPlan(context.Background(), dir, resolverFor)
+	require.NoError(t, err)
+	assert.Empty(t, again)
+}
+
+// An exception that blocked on a collision still carries a destination; Apply
+// must treat Status, not the presence of a path, as the decision.
+func TestApply_LeavesACollisionExceptionAloneEvenThoughItHasADestination(t *testing.T) {
+	dir := t.TempDir()
+	page(t, dir, "wiki/sources/talk-a.md", src("Talk A", "ALPHA"))
+	page(t, dir, "wiki/alpha/sources/talk-a.md", "occupied")
+	items, err := migrate.BuildPlan(context.Background(), dir, resolverFor)
+	require.NoError(t, err)
+	require.Equal(t, migrate.Exception, byFrom(items)["wiki/sources/talk-a.md"].Status)
+
+	n, err := migrate.Apply(dir, items)
+	require.NoError(t, err)
+	assert.Zero(t, n)
+	_, statErr := os.Stat(filepath.Join(dir, "wiki/sources/talk-a.md"))
+	assert.NoError(t, statErr)
+}

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/build.go

@@ -14,6 +14,13 @@ import (
 // (derived from the filename, not the LLM title). Pages whose title resolves to an
 // empty slug are skipped and returned as warnings instead.
 func BuildPages(rawPages []RawPage, sourceSlug, date string) ([]wiki.Page, []string) {
+	return BuildPagesIn("", rawPages, sourceSlug, date)
+}
+
+// BuildPagesIn is BuildPages for a wing: sources go to wiki/<wing>/sources/,
+// concepts and entities to wiki/<wing>/facts/ with `kind:` recording which.
+// An empty wing is the retired wiki/{sources,concepts,entities}/ layout.
+func BuildPagesIn(wing string, rawPages []RawPage, sourceSlug, date string) ([]wiki.Page, []string) {
 	out := make([]wiki.Page, 0, len(rawPages))
 	var warnings []string
 	for _, rp := range rawPages {
@@ -28,7 +35,7 @@ func BuildPages(rawPages []RawPage, sourceSlug, date string) ([]wiki.Page, []str
 			warnings = append(warnings, fmt.Sprintf("skipped page with empty title (type: %s)", rp.Type))
 			continue
 		}
-		out = append(out, buildPage(rp, sourceSlug, date))
+		out = append(out, buildPage(rp, sourceSlug, date, wing))
 	}
 	return out, warnings
 }
@@ -42,7 +49,7 @@ func computeSlug(rp RawPage, sourceSlug string) string {
 	return wiki.Slug(rp.Title)
 }
 
-func buildPage(rp RawPage, sourceSlug, date string) wiki.Page {
+func buildPage(rp RawPage, sourceSlug, date, wing string) wiki.Page {
 	var slug, dir string
 	switch rp.Type {
 	case "source":
@@ -59,8 +66,21 @@ func buildPage(rp RawPage, sourceSlug, date string) wiki.Page {
 		dir = "wiki/" + rp.Type
 	}
 
+	hall := ""
+	if wing != "" {
+		switch rp.Type {
+		case "source":
+			hall = "sources"
+		default:
+			hall = "facts"
+		}
+		dir = "wiki/" + wing + "/" + hall
+	}
 	path := dir + "/" + slug + ".md"
 	fm := buildFrontmatter(rp, date)
+	if wing != "" {
+		fm = addWingFrontmatter(fm, wing, hall, rp.Type)
+	}
 
 	return wiki.Page{
 		Path:    path,
@@ -122,6 +142,16 @@ func buildFrontmatter(rp RawPage, date string) string {
 	return sb.String()
 }
 
+// addWingFrontmatter inserts wing/hall (and kind for facts pages) right after
+// the opening fence of an already-built frontmatter block.
+func addWingFrontmatter(fm, wing, hall, rpType string) string {
+	extra := "wing: " + wing + "\nhall: " + hall + "\n"
+	if hall == "facts" {
+		extra += "kind: " + rpType + "\n"
+	}
+	return strings.Replace(fm, "---\n", "---\n"+extra, 1)
+}
+
 func yamlScalar(s string) string {
 	// A raw newline or CR would end the scalar for every line-oriented
 	// frontmatter reader and start a new key (PR #147 review: a title of

ingestion/internal/pipeline/pipeline.go

@@ -5,7 +5,11 @@ import (
 	"context"
 	"crypto/sha256"
 	"encoding/hex"
+	"errors"
 	"fmt"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
@@ -23,6 +27,11 @@ type Config struct {
 	Complete  CompleteFunc
 	ChunkSize int    // 0 = no chunking
 	Schema    string // overrides brain/schema.md when set (useful in tests)
+
+	// Wing, when set, writes into wiki/<wing>/{sources,facts}/ and scopes the
+	// inventory (title resolution, back-references) to that wing alone. Empty
+	// keeps the retired wiki/{sources,concepts,entities}/ layout.
+	Wing string
 }
 
 // Result is the outcome of a pipeline run.
@@ -39,7 +48,16 @@ type Result struct {
 // Run ingests content and writes structured wiki pages to brainDir/wiki/.
 // In dry-run mode, pages are returned but not written to disk.
 func Run(ctx context.Context, cfg Config, brainDir, content, source string, dryRun bool) (Result, error) {
-	inventory, err := wiki.LoadInventory(brainDir)
+	if cfg.Wing != "" && brain.Sanitise(cfg.Wing) != cfg.Wing {
+		return Result{}, fmt.Errorf("invalid wing %q: must be a plain lower-case wing name", cfg.Wing)
+	}
+	var inventory map[wiki.PageType][]wiki.Entry
+	var err error
+	if cfg.Wing != "" {
+		inventory, err = wiki.LoadWingInventory(brainDir, cfg.Wing)
+	} else {
+		inventory, err = wiki.LoadInventory(brainDir)
+	}
 	if err != nil {
 		return Result{}, fmt.Errorf("load inventory: %w", err)
 	}
@@ -57,7 +75,7 @@ func Run(ctx context.Context, cfg Config, brainDir, content, source string, dryR
 	// The merge is already idempotent (#103), so this is cost and signal, not
 	// correctness — which is why it is safe for it to be an early return.
 	bodyHash := hashBody(content)
-	if !dryRun && bodyHash != "" && bodyHash == storedSourceHash(brainDir, sourceSlug) {
+	if !dryRun && bodyHash != "" && bodyHash == storedSourceHash(brainDir, cfg.Wing, sourceSlug) {
 		return Result{Skipped: true, Warnings: []string{
 			fmt.Sprintf("source %q unchanged since last ingest (hash %s) — extraction skipped", source, bodyHash[:12]),
 		}}, nil
@@ -68,7 +86,7 @@ func Run(ctx context.Context, cfg Config, brainDir, content, source string, dryR
 	// only exists once the model has produced a title. So page-aware
 	// extraction (#106) is scoped to the source page: it's the one page every
 	// chunk's prompt can be given in advance.
-	existingPage := readSourcePage(brainDir, sourceSlug)
+	existingPage := readSourcePage(brainDir, cfg.Wing, sourceSlug)
 
 	chunks := Chunk(content, cfg.ChunkSize)
 
@@ -90,7 +108,7 @@ func Run(ctx context.Context, cfg Config, brainDir, content, source string, dryR
 	meta.BodyHash = bodyHash
 	applySourceMeta(allRaw, meta)
 
-	return buildAndWrite(ctx, allRaw, sourceSlug, date, brainDir, source, inventory, allWarnings, dryRun)
+	return buildAndWrite(ctx, cfg.Wing, allRaw, sourceSlug, date, brainDir, source, inventory, allWarnings, dryRun)
 }
 
 // RunRaw runs the pipeline on pre-parsed RawPages, skipping the LLM extraction
@@ -109,12 +127,12 @@ func RunRaw(ctx context.Context, brainDir, source string, rawPages []RawPage, dr
 	sourceSlug := wiki.Slug(source)
 	date := time.Now().UTC().Format("2006-01-02")
 
-	return buildAndWrite(ctx, rawPages, sourceSlug, date, brainDir, source, inventory, nil, dryRun)
+	return buildAndWrite(ctx, "", rawPages, sourceSlug, date, brainDir, source, inventory, nil, dryRun)
 }
 
 // buildAndWrite runs BuildPages through write for both Run and RunRaw.
-func buildAndWrite(ctx context.Context, rawPages []RawPage, sourceSlug, date, brainDir, source string, inventory map[wiki.PageType][]wiki.Entry, warnings []string, dryRun bool) (Result, error) {
+func buildAndWrite(ctx context.Context, wing string, rawPages []RawPage, sourceSlug, date, brainDir, source string, inventory map[wiki.PageType][]wiki.Entry, warnings []string, dryRun bool) (Result, error) {
-	pages, buildWarnings := BuildPages(rawPages, sourceSlug, date)
+	pages, buildWarnings := BuildPagesIn(wing, rawPages, sourceSlug, date)
 	warnings = append(warnings, buildWarnings...)
 	resolved := Resolve(pages, inventory)
 	canonicalized, linkWarnings := CanonicalizeLinks(resolved, inventory)
@@ -129,7 +147,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
 			}
@@ -155,7 +173,11 @@ func buildAndWrite(ctx context.Context, rawPages []RawPage, sourceSlug, date, br
 	}
 
 	if !dryRun {
-		if err := wiki.RebuildIndex(brainDir, date); err != nil {
+		if wing != "" {
+			if err := brain.BuildWingIndex(brainDir, wing); err != nil {
+				warnings = append(warnings, fmt.Sprintf("rebuild wing index: %v", err))
+			}
+		} else if err := wiki.RebuildIndex(brainDir, date); err != nil {
 			warnings = append(warnings, fmt.Sprintf("rebuild index: %v", err))
 		}
 		if err := wiki.AppendLog(brainDir, source, written, warnings, date); err != nil {
@@ -188,22 +210,39 @@ 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.
-func readSourcePage(brainDir, sourceSlug string) string {
+// It reads through the brain root, regular files only (hyperguild#157): the
-	raw, err := os.ReadFile(filepath.Join(brainDir, "wiki", "sources", sourceSlug+".md"))
+// content goes into the LLM prompt.
+func readSourcePage(brainDir, wing, sourceSlug string) string {
+	rel := "wiki/sources/" + sourceSlug + ".md"
+	if wing != "" {
+		rel = "wiki/" + wing + "/sources/" + sourceSlug + ".md"
+	}
+	raw, err := readBrainFile(brainDir, rel)
 	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.
 //
 // Absence always means "extract". That is the fail-safe direction: a missed
 // skip costs one extraction, while a wrong skip loses an update silently — and
 // silence is the failure mode this repo keeps paying for.
-func storedSourceHash(brainDir, sourceSlug string) string {
+func storedSourceHash(brainDir, wing, sourceSlug string) string {
-	for _, line := range strings.Split(readSourcePage(brainDir, sourceSlug), "\n") {
+	for _, line := range strings.Split(readSourcePage(brainDir, wing, sourceSlug), "\n") {
 		if key, value, found := strings.Cut(line, ":"); found && strings.TrimSpace(key) == "source_hash" {
 			return strings.TrimSpace(value)
 		}
@@ -230,10 +269,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 +306,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"
@@ -24,7 +23,7 @@ func injectSourceRefs(pages []wiki.Page, inventory map[wiki.PageType][]wiki.Entr
 
 	var sourceContent string
 	for _, p := range pages {
-		if strings.HasPrefix(p.Path, "wiki/sources/") &&
+		if isSourcePath(p.Path) &&
 			strings.TrimSuffix(filepath.Base(p.Path), ".md") == sourceSlug {
 			sourceContent = p.Content
 			break
@@ -36,7 +35,7 @@ func injectSourceRefs(pages []wiki.Page, inventory map[wiki.PageType][]wiki.Entr
 
 	bySlug := make(map[string]int, len(pages))
 	for i, p := range pages {
-		if !strings.HasPrefix(p.Path, "wiki/sources/") {
+		if !isSourcePath(p.Path) {
 			bySlug[strings.TrimSuffix(filepath.Base(p.Path), ".md")] = i
 		}
 	}
@@ -53,13 +52,13 @@ func injectSourceRefs(pages []wiki.Page, inventory map[wiki.PageType][]wiki.Entr
 		if !ok {
 			continue
 		}
-		diskPath := filepath.Join(brainDir, "wiki", string(pt), slug+".md")
+		path := entryPath(slug, pt, inventory)
-		b, err := os.ReadFile(diskPath)
+		b, err := readBrainFile(brainDir, path)
 		if err != nil {
 			continue
 		}
 		page := wiki.Page{
-			Path:    "wiki/" + string(pt) + "/" + slug + ".md",
+			Path:    path,
 			Content: string(b),
 		}
 		pages = append(pages, addSourceRef(page, sourceRef))
@@ -90,7 +89,7 @@ func extractWikilinks(content string) map[string]bool {
 // findSourcePage returns the slug and title of the first wiki/sources/ page in pages.
 func findSourcePage(pages []wiki.Page) (slug, title string, found bool) {
 	for _, p := range pages {
-		if strings.HasPrefix(p.Path, "wiki/sources/") {
+		if isSourcePath(p.Path) {
 			slug = strings.TrimSuffix(filepath.Base(p.Path), ".md")
 			title = extractTitle(p.Content)
 			if title == "" {
@@ -113,3 +112,27 @@ func findInInventory(slug string, inventory map[wiki.PageType][]wiki.Entry) (wik
 	}
 	return "", false
 }
+
+// isSourcePath reports whether path is a source page in either layout:
+// wiki/sources/<slug>.md or wiki/<wing>/sources/<slug>.md.
+func isSourcePath(path string) bool {
+	parts := strings.Split(filepath.ToSlash(path), "/")
+	switch {
+	case len(parts) == 3 && parts[0] == "wiki" && parts[1] == "sources":
+		return true
+	case len(parts) == 4 && parts[0] == "wiki" && parts[2] == "sources":
+		return true
+	}
+	return false
+}
+
+// entryPath is the brain-relative path of an inventory page: the recorded Path
+// for a wing-layout entry, else the retired wiki/<type>/<slug>.md.
+func entryPath(slug string, pt wiki.PageType, inventory map[wiki.PageType][]wiki.Entry) string {
+	for _, e := range inventory[pt] {
+		if e.Slug == slug && e.Path != "" {
+			return e.Path
+		}
+	}
+	return "wiki/" + string(pt) + "/" + slug + ".md"
+}

ingestion/internal/pipeline/resolve.go

@@ -32,7 +32,7 @@ func Resolve(proposed []wiki.Page, inventory map[wiki.PageType][]wiki.Entry) []w
 
 	out := make([]wiki.Page, 0, len(proposed))
 	for _, page := range proposed {
-		pt := pageTypeFromPath(page.Path)
+		pt := pageTypeOf(page)
 		title := extractTitle(page.Content)
 		k := key{pt: pt, normalized: normalizeTitle(title)}
 		if canonicalSlug, ok := lookup[k]; ok {
@@ -55,6 +55,22 @@ func normalizeTitle(s string) string {
 	return strings.Join(strings.Fields(s), " ")
 }
 
+// pageTypeOf is the page's type: from its directory in the retired layout, or
+// from `kind:` for a wing-layout facts page (concepts and entities share facts/).
+func pageTypeOf(p wiki.Page) wiki.PageType {
+	parts := strings.Split(filepath.ToSlash(p.Path), "/")
+	if len(parts) >= 4 && parts[0] == "wiki" {
+		switch parts[2] {
+		case "sources":
+			return wiki.PageTypeSource
+		case "facts":
+			pt, _ := wiki.KindFromContent(p.Content)
+			return pt
+		}
+	}
+	return pageTypeFromPath(p.Path)
+}
+
 // pageTypeFromPath extracts the wiki.PageType from a path like "wiki/entities/foo.md".
 func pageTypeFromPath(path string) wiki.PageType {
 	parts := strings.Split(filepath.ToSlash(path), "/")

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/pipeline/wing_layout_test.go

@@ -0,0 +1,138 @@
+package pipeline
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func wingCfg(wing string, pages ...RawPage) Config {
+	return Config{
+		Wing:   wing,
+		Schema: "# Schema",
+		Complete: func(context.Context, string, string) (string, error) {
+			return mustJSON(pages), nil
+		},
+	}
+}
+
+func sourceAndEntity() []RawPage {
+	return []RawPage{
+		{Title: "Dark Factory Talk", Type: "source", Subtype: "video", Domain: "ai",
+			Content: "## Summary\n\nA talk.\n\n## Entities Mentioned\n\n[[Jev]]\n"},
+		{Title: "Jev", Type: "entity", Subtype: "tool", Domain: "ai",
+			Content: "## Definition\n\nA decision model.\n\n## Sources\n"},
+	}
+}
+
+func exists(dir, rel string) bool {
+	_, err := os.Stat(filepath.Join(dir, rel))
+	return err == nil
+}
+
+func read(t *testing.T, dir, rel string) string {
+	t.Helper()
+	b, err := os.ReadFile(filepath.Join(dir, rel))
+	require.NoError(t, err)
+	return string(b)
+}
+
+func TestRun_WithAWingWritesIntoThatWingsHalls(t *testing.T) {
+	dir := t.TempDir()
+	_, err := Run(context.Background(), wingCfg("radar", sourceAndEntity()...), dir, "body of the talk", "dark-factory-talk", false)
+	require.NoError(t, err)
+
+	src := read(t, dir, "wiki/radar/sources/dark-factory-talk.md")
+	assert.Contains(t, src, "wing: radar")
+	assert.Contains(t, src, "hall: sources")
+
+	ent := read(t, dir, "wiki/radar/facts/jev.md")
+	assert.Contains(t, ent, "wing: radar")
+	assert.Contains(t, ent, "hall: facts")
+	assert.Contains(t, ent, "kind: entity")
+}
+
+func TestRun_WithAWingDoesNotTouchTheRetiredLayout(t *testing.T) {
+	dir := t.TempDir()
+	_, err := Run(context.Background(), wingCfg("radar", sourceAndEntity()...), dir, "body of the talk", "dark-factory-talk", false)
+	require.NoError(t, err)
+	for _, retired := range []string{"wiki/sources", "wiki/concepts", "wiki/entities"} {
+		assert.False(t, exists(dir, retired), "%s is the retired layout and must not be written", retired)
+	}
+}
+
+func TestRun_WithAWingTheSourceLinksBackFromTheEntity(t *testing.T) {
+	dir := t.TempDir()
+	_, err := Run(context.Background(), wingCfg("radar", sourceAndEntity()...), dir, "body of the talk", "dark-factory-talk", false)
+	require.NoError(t, err)
+	assert.Contains(t, read(t, dir, "wiki/radar/facts/jev.md"), "[[dark-factory-talk|Dark Factory Talk]]")
+}
+
+func TestRun_WithAWingASecondSourceReusesTheSameEntityPage(t *testing.T) {
+	dir := t.TempDir()
+	_, err := Run(context.Background(), wingCfg("radar", sourceAndEntity()...), dir, "first body", "talk-one", false)
+	require.NoError(t, err)
+
+	again := []RawPage{
+		{Title: "Second Talk", Type: "source", Subtype: "video", Content: "## Summary\n\nMore.\n\n## Entities Mentioned\n\n[[The Jev]]\n"},
+		{Title: "The Jev", Type: "entity", Subtype: "tool", Content: "## Definition\n\nStill a decision model.\n\n## Sources\n"},
+	}
+	_, err = Run(context.Background(), wingCfg("radar", again...), dir, "second body", "talk-two", false)
+	require.NoError(t, err)
+
+	files, err := filepath.Glob(filepath.Join(dir, "wiki/radar/facts/*.md"))
+	require.NoError(t, err)
+	assert.Len(t, files, 1, "an entity matched by title (leading article ignored) is merged, not duplicated")
+	assert.Contains(t, read(t, dir, "wiki/radar/facts/jev.md"), "talk-two")
+}
+
+func TestRun_WithAWingNeverMergesIntoAnotherWingsPage(t *testing.T) {
+	dir := t.TempDir()
+	other := "---\ntitle: Jev\nwing: client-x\nhall: facts\nkind: entity\n---\n\n## Definition\n\nPrivate to another wing.\n"
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki/client-x/facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "wiki/client-x/facts/jev.md"), []byte(other), 0o644))
+
+	_, err := Run(context.Background(), wingCfg("radar", sourceAndEntity()...), dir, "body", "dark-factory-talk", false)
+	require.NoError(t, err)
+
+	assert.Equal(t, other, read(t, dir, "wiki/client-x/facts/jev.md"), "another wing's page is never read into or rewritten")
+	assert.True(t, exists(dir, "wiki/radar/facts/jev.md"))
+}
+
+func TestRun_WithAWingRejectsANameThatIsNotAPlainWing(t *testing.T) {
+	for _, bad := range []string{"../escape", "a/b", "Radar", "has space", "."} {
+		t.Run(bad, func(t *testing.T) {
+			dir := t.TempDir()
+			_, err := Run(context.Background(), wingCfg(bad, sourceAndEntity()...), dir, "body", "talk", false)
+			require.Error(t, err)
+			assert.Len(t, listAll(t, dir), 1, "nothing is written for a rejected wing (only the temp dir itself exists)")
+		})
+	}
+}
+
+func listAll(t *testing.T, dir string) []string {
+	t.Helper()
+	var out []string
+	_ = filepath.WalkDir(dir, func(p string, _ os.DirEntry, _ error) error { out = append(out, p); return nil })
+	return out
+}
+
+// The dangerous path is the back-reference: a source that links [[Jev]] without
+// proposing a Jev page makes the pipeline go and edit an existing Jev page. That
+// lookup must be confined to the target wing.
+func TestRun_WithAWingASourceLinkingToAnotherWingsEntityDoesNotEditIt(t *testing.T) {
+	dir := t.TempDir()
+	other := "---\ntitle: Jev\nwing: client-x\nhall: facts\nkind: entity\n---\n\n## Definition\n\nPrivate to another wing.\n\n## Sources\n"
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki/client-x/facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "wiki/client-x/facts/jev.md"), []byte(other), 0o644))
+
+	onlySource := sourceAndEntity()[:1]
+	_, err := Run(context.Background(), wingCfg("radar", onlySource...), dir, "body", "dark-factory-talk", false)
+	require.NoError(t, err)
+
+	assert.Equal(t, other, read(t, dir, "wiki/client-x/facts/jev.md"), "no back-reference may be written into another wing")
+}

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
@@ -93,16 +95,20 @@ func TestQueryDoesNotFollowASymlinkedWingUnderAWingAndHallRoot(t *testing.T) {
 // bypass of readOpened hung Query after 5 iterations).
 // startSwap runs swapInto until the test ends and waits for it before
 // t.TempDir's cleanup (hyperguild#162).
-func startSwap(t *testing.T, path, outside string, fifo bool) {
+// It returns the count of symlinks or FIFOs actually renamed into path
+// (hyperguild#177: a swapper whose every swap fails tests nothing).
+func startSwap(t *testing.T, path, outside string, fifo bool) *atomic.Int64 {
 	t.Helper()
 	var stop atomic.Bool
+	var swaps atomic.Int64
 	var wg sync.WaitGroup
 	wg.Add(1)
-	go func() { defer wg.Done(); swapInto(path, outside, fifo, &stop) }()
+	go func() { defer wg.Done(); swapInto(path, outside, fifo, &stop, &swaps) }()
 	t.Cleanup(func() { stop.Store(true); wg.Wait() })
+	return &swaps
 }
 
-func swapInto(path, outside string, fifo bool, stop *atomic.Bool) {
+func swapInto(path, outside string, fifo bool, stop *atomic.Bool, swaps *atomic.Int64) {
 	tmp := path + ".swap"
 	// Writers stay open until the swapper exits, so a reader parked on a
 	// FIFO stays parked (closing one would hand the reader EOF and hide the
@@ -115,33 +121,46 @@ func swapInto(path, outside string, fifo bool, stop *atomic.Bool) {
 	}()
 	for i := 0; !stop.Load(); i++ {
 		_ = os.Remove(tmp)
+		var made error
 		switch {
 		case i%2 == 0:
 			_ = os.WriteFile(tmp, []byte("# r\n\nzqinside "+"zqracenote"), 0o644)
 		case fifo:
-			if err := syscall.Mkfifo(tmp, 0o644); err == nil {
+			if made = syscall.Mkfifo(tmp, 0o644); made == nil {
 				if w, err := os.OpenFile(tmp, os.O_RDWR, 0); err == nil {
 					writers = append(writers, w)
 				}
 			}
 		default:
-			_ = os.Symlink(outside, tmp)
+			made = os.Symlink(outside, tmp)
+		}
+		if err := os.Rename(tmp, path); err == nil && made == nil && i%2 == 1 {
+			swaps.Add(1)
 		}
-		_ = os.Rename(tmp, path)
 	}
 }
 
 func TestQueryLeaksNothingUnderASymlinkSwapRace(t *testing.T) {
 	brain, facts, outside := searchBrain(t)
-	startSwap(t, filepath.Join(facts, "r.md"), outside, false)
+	swaps := startSwap(t, filepath.Join(facts, "r.md"), outside, false)
-	leaks, iters := 0, 0
+	leaks, iters, insideReads := 0, 0, 0
 	for deadline := time.Now().Add(1500 * time.Millisecond); time.Now().Before(deadline); iters++ {
-		rs, _ := Query(brain, QueryOptions{Query: sentinel157, Limit: 10})
+		rs, err := Query(brain, QueryOptions{Query: sentinel157, Limit: 10})
+		require.NoError(t, err)
 		leaks += leaked(rs)
+		// Positive control (hyperguild#177): a Query that always errors
+		// returns nothing and so never leaks.
+		rs, err = Query(brain, QueryOptions{Query: "zqracenote", Limit: 10})
+		require.NoError(t, err)
+		if len(rs) > 0 {
+			insideReads++
+		}
 	}
 	if leaks > 0 {
 		t.Fatalf("outside file leaked %d times in %d iterations", leaks, iters)
 	}
+	require.Positive(t, swaps.Load(), "no symlink was swapped in: the race did not run")
+	require.Positive(t, insideReads, "no Query returned the inside note")
 }
 
 func TestQueryDoesNotHangUnderAFIFOSwapRace(t *testing.T) {
@@ -172,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

@@ -0,0 +1,177 @@
+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
+// filepath.Join(sessionsDir, id+".jsonl") and opened it O_CREATE|O_APPEND:
+// path segments in the id created or appended files anywhere the pod could
+// write. The id is now a plain name, and the open does not follow a final
+// symlink.
+func TestAppendRefusesSessionIDsThatAreNotPlainNames(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, "sessions")
+	for _, id := range []string{"../x", "a/b", "/abs", ".", "..", ".hidden", "", "a\\b", "a\x00b"} {
+		assert.Error(t, Append(dir, id, Entry{SessionID: id}), "%q", id)
+	}
+	ents, _ := os.ReadDir(root)
+	for _, e := range ents {
+		assert.Equal(t, "sessions", e.Name(), "nothing created beside the sessions dir")
+	}
+	for _, id := range []string{"1557b2e1-bf0d-5c4f-bbe3-0754d087e356", "_routing", "2026-05-05-infra.plan", "0"} {
+		require.NoError(t, Append(dir, id, Entry{SessionID: id}), "positive control: %q", id)
+	}
+}
+
+func TestAppendDoesNotWriteThroughASymlinkedLog(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, "sessions")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	victim := filepath.Join(root, "victim.md")
+	require.NoError(t, os.WriteFile(victim, []byte("untouched\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "victim.md"), filepath.Join(dir, "s.jsonl")))
+	assert.Error(t, Append(dir, "s", Entry{SessionID: "s"}))
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched\n", string(got))
+}
+
+func TestReadRefusesSessionIDsThatAreNotPlainNames(t *testing.T) {
+	root := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(root, "x.jsonl"), []byte(`{"session_id":"x"}`+"\n"), 0o644))
+	_, err := Read(filepath.Join(root, "sessions"), "../x")
+	assert.Error(t, err)
+}
+
+// A name that starts plainly and then climbs out with ".." is exactly what the
+// ban on "/" in the id's tail stops: filepath.Join cleans "a/../../x" to a
+// path beside the sessions dir without needing sessions/a to exist. The
+// assertion is on the refusal itself (ErrInvalidID), not on any error.
+func TestAppendRefusesAnIDThatClimbsOutAfterAPlainPrefix(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, "sessions")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	for _, id := range []string{"a/../../escape", "a/../../../escape", "a/../b"} {
+		err := Append(dir, id, Entry{SessionID: id})
+		assert.ErrorIs(t, err, ErrInvalidID, "%q", id)
+	}
+	_, err := os.Lstat(filepath.Join(root, "escape.jsonl"))
+	assert.True(t, errors.Is(err, os.ErrNotExist), "nothing created beside the sessions dir")
+	_, err = os.Lstat(filepath.Join(dir, "b.jsonl"))
+	assert.True(t, errors.Is(err, os.ErrNotExist), "no in-dir alias created either")
+}
+
+// Append does no Lstat type check, so O_NONBLOCK is the only thing that keeps
+// a FIFO named <id>.jsonl with no reader from blocking session_log forever.
+func TestAppendReturnsPromptlyOnAFIFOLogWithNoReader(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "sessions")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	fifo := filepath.Join(dir, "s.jsonl")
+	require.NoError(t, syscall.Mkfifo(fifo, 0o644))
+	done := make(chan error, 1)
+	go func() { done <- Append(dir, "s", Entry{SessionID: "s"}) }()
+	select {
+	case err := <-done:
+		assert.Error(t, err, "a FIFO with no reader is refused, not written")
+	case <-time.After(3 * time.Second):
+		// Unblock the stuck open so the goroutine and TempDir cleanup finish.
+		if r, err := os.OpenFile(fifo, os.O_RDONLY|syscall.O_NONBLOCK, 0); err == nil {
+			defer r.Close() //nolint:errcheck
+		}
+		<-done
+		t.Fatal("Append blocked on a FIFO log with no reader")
+	}
+}
+
+// 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

@@ -9,6 +9,8 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"regexp"
+	"syscall"
 	"time"
 )
 
@@ -42,16 +44,63 @@ type Attempt struct {
 	RunnerOutput  string `json:"runner_output,omitempty"`
 }
 
+// idPattern is a plain file name: session_log takes the id from the caller,
+// and a path segment in it created or appended files anywhere the pod could
+// write (hyperguild#169).
+var idPattern = regexp.MustCompile(`^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$`)
+
+// ErrInvalidID is returned when a session id is not a plain file name.
+var ErrInvalidID = errors.New("session id is not a plain name")
+
+func checkID(sessionID string) error {
+	if !idPattern.MatchString(sessionID) {
+		return fmt.Errorf("%w: %q", ErrInvalidID, sessionID)
+	}
+	return nil
+}
+
 // Append writes entry as a single JSON line to sessionsDir/{sessionID}.jsonl.
+// The open does not follow a final symlink.
 func Append(sessionsDir, sessionID string, entry Entry) error {
-	if err := os.MkdirAll(sessionsDir, 0o755); err != nil {
+	if err := checkID(sessionID); err != nil {
+		return err
+	}
+	// 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, 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 {
@@ -70,6 +119,9 @@ func Append(sessionsDir, sessionID string, entry Entry) error {
 
 // Read returns all entries for sessionID. Returns empty slice if no log exists.
 func Read(sessionsDir, sessionID string) ([]Entry, error) {
+	if err := checkID(sessionID); err != nil {
+		return nil, err
+	}
 	path := filepath.Join(sessionsDir, sessionID+".jsonl")
 	f, err := os.Open(path)
 	if errors.Is(err, fs.ErrNotExist) {

ingestion/internal/startupretry/startupretry.go

@@ -1,75 +0,0 @@
-// Package startupretry retries a startup dependency that may not be serving
-// yet, instead of exiting on its first failure.
-//
-// It exists for the cold-boot ordering race (#83): on a cluster restart the
-// ingestion pod can reach OIDC discovery before dex is answering, gets a 502
-// from ingress, and dies — after having already connected postgres, backfilled
-// the graph and ingested session batches, all of which the restart redoes.
-// Nothing is misconfigured in that scenario; the pod simply started first.
-//
-// The budget is bounded on purpose. Retrying forever would turn a genuine
-// misconfiguration (wrong issuer URL, bad audience) into a process that looks
-// healthy and never serves, which is harder to diagnose than a crash loop.
-package startupretry
-
-import (
-	"context"
-	"fmt"
-	"time"
-)
-
-// Policy bounds the retry: at most Attempts calls, with the delay doubling
-// from Base and capped at Max.
-type Policy struct {
-	Attempts int           // total calls, including the first; < 1 means 1
-	Base     time.Duration // delay before the second attempt
-	Max      time.Duration // ceiling for the doubling delay
-}
-
-// Do calls fn until it succeeds, the attempt budget is spent, or ctx ends.
-//
-// The returned error wraps the last failure, so callers keep the diagnosis
-// they would have had without the retry.
-func Do[T any](ctx context.Context, p Policy, fn func(context.Context) (T, error)) (T, error) {
-	var zero T
-
-	attempts := p.Attempts
-	if attempts < 1 {
-		attempts = 1
-	}
-
-	delay := p.Base
-	var lastErr error
-
-	for i := range attempts {
-		if err := ctx.Err(); err != nil {
-			return zero, fmt.Errorf("startupretry: %w", err)
-		}
-
-		v, err := fn(ctx)
-		if err == nil {
-			return v, nil
-		}
-		lastErr = err
-
-		if i == attempts-1 {
-			break
-		}
-
-		if delay <= 0 {
-			delay = time.Second
-		}
-		if p.Max > 0 && delay > p.Max {
-			delay = p.Max
-		}
-
-		select {
-		case <-ctx.Done():
-			return zero, fmt.Errorf("startupretry: %w", ctx.Err())
-		case <-time.After(delay):
-		}
-		delay *= 2
-	}
-
-	return zero, fmt.Errorf("startupretry: gave up after %d attempts: %w", attempts, lastErr)
-}

ingestion/internal/startupretry/startupretry_test.go

@@ -1,142 +0,0 @@
-// ingestion/internal/startupretry/startupretry_test.go
-package startupretry
-
-import (
-	"context"
-	"errors"
-	"testing"
-	"time"
-)
-
-func fastPolicy(attempts int) Policy {
-	return Policy{Attempts: attempts, Base: time.Millisecond, Max: 2 * time.Millisecond}
-}
-
-func TestDo_ReturnsImmediatelyOnFirstSuccess(t *testing.T) {
-	calls := 0
-	got, err := Do(context.Background(), fastPolicy(5), func(context.Context) (string, error) {
-		calls++
-		return "ready", nil
-	})
-	if err != nil {
-		t.Fatalf("Do: %v", err)
-	}
-	if got != "ready" {
-		t.Errorf("got %q, want %q", got, "ready")
-	}
-	if calls != 1 {
-		t.Errorf("calls = %d, want 1", calls)
-	}
-}
-
-func TestDo_SurvivesTransientFailuresThenSucceeds(t *testing.T) {
-	// The observed cold-boot race: dex is not serving yet, ingress answers
-	// 502 for the first few attempts, then discovery works.
-	calls := 0
-	got, err := Do(context.Background(), fastPolicy(5), func(context.Context) (string, error) {
-		calls++
-		if calls < 4 {
-			return "", errors.New("oidc discovery: status 502")
-		}
-		return "ready", nil
-	})
-	if err != nil {
-		t.Fatalf("Do returned %v — a transient 502 must not be fatal", err)
-	}
-	if got != "ready" {
-		t.Errorf("got %q, want %q", got, "ready")
-	}
-	if calls != 4 {
-		t.Errorf("calls = %d, want 4", calls)
-	}
-}
-
-func TestDo_GivesUpAfterTheAttemptBudgetAndReportsTheLastError(t *testing.T) {
-	// A genuinely broken issuer must still fail — retrying forever would turn
-	// a config error into a silent hang, which is worse than crash-looping.
-	last := errors.New("oidc discovery: status 404")
-	calls := 0
-
-	_, err := Do(context.Background(), fastPolicy(3), func(context.Context) (string, error) {
-		calls++
-		return "", last
-	})
-
-	if !errors.Is(err, last) {
-		t.Fatalf("err = %v, want it to wrap the last failure", err)
-	}
-	if calls != 3 {
-		t.Errorf("calls = %d, want 3 (the attempt budget)", calls)
-	}
-}
-
-func TestDo_StopsPromptlyWhenTheContextIsCancelled(t *testing.T) {
-	ctx, cancel := context.WithCancel(context.Background())
-	calls := 0
-
-	done := make(chan struct{})
-	var err error
-	go func() {
-		defer close(done)
-		_, err = Do(ctx, Policy{Attempts: 100, Base: 50 * time.Millisecond, Max: time.Second},
-			func(context.Context) (string, error) {
-				calls++
-				if calls == 1 {
-					cancel()
-				}
-				return "", errors.New("still down")
-			})
-	}()
-
-	select {
-	case <-done:
-	case <-time.After(2 * time.Second):
-		t.Fatal("Do did not return after context cancellation")
-	}
-	if !errors.Is(err, context.Canceled) {
-		t.Errorf("err = %v, want context.Canceled", err)
-	}
-}
-
-func TestDo_BacksOffAndIsCappedByMax(t *testing.T) {
-	var delays []time.Duration
-	p := Policy{Attempts: 5, Base: 10 * time.Millisecond, Max: 25 * time.Millisecond}
-
-	last := time.Now()
-	_, _ = Do(context.Background(), p, func(context.Context) (string, error) {
-		now := time.Now()
-		delays = append(delays, now.Sub(last))
-		last = now
-		return "", errors.New("down")
-	})
-
-	// delays[0] is the first call (no wait); the rest are the sleeps.
-	if len(delays) != 5 {
-		t.Fatalf("attempts = %d, want 5", len(delays))
-	}
-	if delays[1] >= delays[2] {
-		t.Errorf("backoff is not growing: %v then %v", delays[1], delays[2])
-	}
-	for i, d := range delays[1:] {
-		if d > 2*p.Max {
-			t.Errorf("delay %d = %v, exceeds the Max cap %v with slack", i+1, d, p.Max)
-		}
-	}
-}
-
-func TestPolicy_ZeroValueStillMakesOneAttempt(t *testing.T) {
-	// A caller that forgets to configure the policy must not silently get a
-	// no-op that returns a nil validator and a nil error.
-	calls := 0
-	_, err := Do(context.Background(), Policy{}, func(context.Context) (string, error) {
-		calls++
-		return "", errors.New("down")
-	})
-
-	if calls != 1 {
-		t.Errorf("calls = %d, want 1", calls)
-	}
-	if err == nil {
-		t.Error("err = nil, want the failure surfaced")
-	}
-}

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

@@ -18,9 +18,14 @@ import (
 	"sort"
 	"strconv"
 	"strings"
+	"sync"
+	"sync/atomic"
 	"time"
 )
 
+// shutdownFlushTimeout bounds the final flush when Watch stops.
+var shutdownFlushTimeout = 5 * time.Second
+
 // DefaultInterval is used when Watch is given a non-positive interval.
 const DefaultInterval = 30 * time.Second
 
@@ -41,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.
@@ -54,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)))
 	}
@@ -108,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
@@ -133,13 +151,32 @@ func Scan(brainDir string) (Result, error) {
 // queue until Notify succeeds (see alertQueue): an outage delays them, and
 // any that do not fit the bounded queue, or are undeliverable, are counted in
 // a summary that is never dropped, so every incident is delivered or counted.
+//
+// Delivery runs in its own goroutine (hyperguild#164): a hung notifier, with
+// a full queue, blocked one flush for several notify timeouts, and while the
+// scan waited on it a planted link stayed readable for several intervals.
+// The scan hands alerts over without blocking; any that do not fit are
+// counted in the summary. When ctx ends, Watch returns after a final flush
+// of what was handed over (bounded by shutdownFlushTimeout); alerts that
+// flush cannot deliver are counted in one error log line instead. That
+// shutdown path only runs for a caller that cancels ctx: cmd/server passes
+// context.Background(), so in production the flush on handoff is what keeps
+// alerts from waiting on a restart.
 func Watch(ctx context.Context, brainDir string, interval time.Duration, n Notifier) {
 	if interval <= 0 {
 		interval = DefaultInterval
 	}
 	t := time.NewTicker(interval)
 	defer t.Stop()
-	q := &alertQueue{}
+	alerts := make(chan string, maxPending)
+	var overflow atomic.Int64
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() { defer wg.Done(); deliver(ctx, interval, n, alerts, &overflow) }()
+	// The scan is the only sender: closing alerts tells deliver to drain and
+	// flush once more, and Watch returns only after it has.
+	defer func() { close(alerts); wg.Wait() }()
+	q := alertSender{alerts: alerts, overflow: &overflow}
 	reported := ""
 	for {
 		select {
@@ -158,17 +195,92 @@ 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.")
 			}
 		}
-		q.flush(ctx, n)
+	}
+}
+
+// alertSender hands alerts to deliver without ever blocking the scan; an
+// alert that does not fit is counted in overflow, which deliver adds to the
+// summary.
+type alertSender struct {
+	alerts   chan<- string
+	overflow *atomic.Int64
+}
+
+func (s alertSender) push(msg string) {
+	select {
+	case s.alerts <- msg:
+	default:
+		s.overflow.Add(1)
+	}
+}
+
+// deliver owns the alertQueue. It flushes as soon as an alert is handed
+// over, and again every interval while any are pending (outage retries).
+// When alerts is closed (Watch is stopping) it drains it and flushes once
+// more, bounded by shutdownFlushTimeout, so an alert handed over just before
+// shutdown is not lost (PR #180 review). Whatever that flush cannot deliver
+// is logged as one error with its counts, never dropped silently.
+func deliver(ctx context.Context, interval time.Duration, n Notifier, alerts <-chan string, overflow *atomic.Int64) {
+	t := time.NewTicker(interval)
+	defer t.Stop()
+	q := &alertQueue{}
+	// drain moves everything handed over into the queue; it reports false
+	// once alerts is closed.
+	drain := func() bool {
+		defer func() { q.suppressed += int(overflow.Swap(0)) }()
+		for {
+			select {
+			case msg, ok := <-alerts:
+				if !ok {
+					return false
+				}
+				q.push(msg)
+			default:
+				return true
+			}
+		}
+	}
+	for {
+		select {
+		case msg, ok := <-alerts:
+			if ok {
+				q.push(msg)
+				ok = drain()
+			}
+			if !ok {
+				q.suppressed += int(overflow.Swap(0))
+				fctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), shutdownFlushTimeout)
+				q.flush(fctx, n)
+				cancel()
+				if len(q.items) > 0 || q.suppressed > 0 {
+					slog.Error("symlink tripwire alerts not delivered at shutdown",
+						"undelivered", len(q.items), "suppressed", q.suppressed)
+				}
+				return
+			}
+			q.flush(ctx, n)
+		case <-t.C:
+			if !drain() {
+				continue // the closed channel is handled by the case above
+			}
+			q.flush(ctx, n)
+		}
 	}
 }
 
@@ -229,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

@@ -1,10 +1,12 @@
 package symlinkguard
 
 import (
+	"bytes"
 	"context"
 	"errors"
 	"fmt"
 	"os"
+	"log/slog"
 	"path/filepath"
 	"strconv"
 	"strings"
@@ -345,13 +347,19 @@ func TestWatchDropsAMessageThatNeverSendsSoLaterAlertsFlow(t *testing.T) {
 	}, 3*time.Second, 10*time.Millisecond, "a later alert is delivered despite a poison message")
 }
 
-// toggleNotifier fails while down is set.
+// toggleNotifier fails while down is set. Like the real audit.NtfyNotifier
+// (http.NewRequestWithContext), it also fails, without recording, when its
+// ctx is already done (PR #180 round 2: notifiers that ignored ctx let a
+// final flush on the cancelled ctx pass).
 type toggleNotifier struct {
 	recNotifier
 	down atomic.Bool
 }
 
 func (r *toggleNotifier) Notify(ctx context.Context, m string) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
 	if r.down.Load() {
 		return errors.New("ntfy down")
 	}
@@ -373,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()
+		n.mu.Lock()
-	defer n.mu.Unlock()
+		defer n.mu.Unlock()
-	found := false
+		for _, m := range n.msgs {
-	for _, m := range n.msgs {
+			if strings.Contains(m, "suppressed") {
-		if strings.Contains(m, "suppressed") {
+				return true
-			found = true
+			}
 		}
-	}
+		return false
-	assert.True(t, found, "suppressed alerts are counted in a summary")
+	}, 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
@@ -403,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)
 	}
 }
 
@@ -449,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
+				}
+			}
+			if i := strings.Index(m, "): "); i >= 0 && strings.Contains(m, "suppressed") {
+				if _, err := fmt.Sscanf(m[i+3:], "%d", &k); err == nil {
+					counted += k
+				}
 			}
 		}
-		return false
+		return delivered, counted
-	}, 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)
-		}
 	}
-	assert.Equal(t, plants, delivered+counted, "delivered %d + counted %d must equal %d removals", delivered, counted, plants)
+	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
@@ -496,3 +516,271 @@ func TestWatchDropsAPoisonMessageAndCountsIt(t *testing.T) {
 		return false
 	}, 3*time.Second, 5*time.Millisecond, "the dropped poison alert is counted in a summary")
 }
+
+// hungNotifier answers every Notify only after latency (or when ctx ends),
+// with an outage error: an ntfy that accepts connections but never responds
+// until its timeout.
+type hungNotifier struct{ latency time.Duration }
+
+func (h hungNotifier) Notify(ctx context.Context, _ string) error {
+	select {
+	case <-time.After(h.latency):
+	case <-ctx.Done():
+	}
+	return errors.New("ntfy timeout")
+}
+
+func waitGone(t *testing.T, link string) {
+	t.Helper()
+	require.Eventually(t, func() bool { _, err := os.Lstat(link); return os.IsNotExist(err) }, 10*time.Second, time.Millisecond)
+}
+
+// hyperguild#164: alerts were flushed in the scan goroutine, so with a hung
+// ntfy and a full queue one flush (6 x notify timeout) delayed the next scan.
+// The notifier here is slower than the interval, as in production (10 s
+// timeout vs 30 s interval with 6 messages), so the alert handoff is full:
+// a scan that waited on it would keep a link for seconds.
+func TestWatchLinkLifetimeStaysNearOneIntervalWithANotifierSlowerThanTheInterval(t *testing.T) {
+	const interval = 100 * time.Millisecond
+	brain := t.TempDir()
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go Watch(ctx, brain, interval, hungNotifier{latency: 400 * time.Millisecond})
+
+	for i := 0; i < 2*maxPending+3; i++ { // overfill queue and handoff
+		link := filepath.Join(brain, "fill"+strconv.Itoa(i))
+		require.NoError(t, os.Symlink(t.TempDir(), link))
+		waitGone(t, link)
+	}
+	var worst time.Duration
+	for i := 0; i < 6; i++ {
+		link := filepath.Join(brain, "probe"+strconv.Itoa(i))
+		require.NoError(t, os.Symlink(t.TempDir(), link))
+		planted := time.Now()
+		waitGone(t, link)
+		worst = max(worst, time.Since(planted))
+	}
+	assert.LessOrEqual(t, worst, interval+interval/2, "worst link lifetime %v with a hung notifier", worst)
+}
+
+// Review of PR #180: delivery waited for its own tick, about one interval
+// after the removal. An alert is now flushed as soon as it is handed over.
+func TestWatchDeliversARemovalAlertWellWithinOneInterval(t *testing.T) {
+	const interval = 400 * time.Millisecond
+	brain := t.TempDir()
+	n := &recNotifier{}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go Watch(ctx, brain, interval, n)
+	link := filepath.Join(brain, "prompt")
+	require.NoError(t, os.Symlink(t.TempDir(), link))
+	waitGone(t, link)
+	removed := time.Now()
+	require.Eventually(t, func() bool { return n.count() == 1 }, 2*time.Second, time.Millisecond)
+	assert.Less(t, time.Since(removed), interval/4)
+}
+
+// Review of PR #180: on ctx end, deliver returned without draining what the
+// scan had handed over, so a removal just before shutdown was neither
+// delivered nor counted. Watch now drains and flushes before returning.
+func TestWatchDeliversAnAlertHandedOverJustBeforeShutdown(t *testing.T) {
+	for i := 0; i < 20; i++ {
+		brain := t.TempDir()
+		n := &recNotifier{}
+		ctx, cancel := context.WithCancel(context.Background())
+		done := make(chan struct{})
+		go func() { Watch(ctx, brain, 5*time.Millisecond, n); close(done) }()
+		link := filepath.Join(brain, "late")
+		require.NoError(t, os.Symlink(t.TempDir(), link))
+		waitGone(t, link)
+		cancel()
+		<-done
+		require.Equal(t, 1, n.count(), "iteration %d: the removal alert was lost at shutdown", i)
+	}
+}
+
+// blockingNotifier holds every Notify until its ctx ends, tracking calls in
+// flight.
+type blockingNotifier struct{ inFlight atomic.Int32 }
+
+func (b *blockingNotifier) Notify(ctx context.Context, _ string) error {
+	b.inFlight.Add(1)
+	defer b.inFlight.Add(-1)
+	<-ctx.Done()
+	return ctx.Err()
+}
+
+// Watch does not return while its delivery goroutine is still notifying.
+func TestWatchReturnsOnlyAfterDeliveryHasStopped(t *testing.T) {
+	prev := shutdownFlushTimeout
+	shutdownFlushTimeout = 50 * time.Millisecond
+	t.Cleanup(func() { shutdownFlushTimeout = prev })
+	brain := t.TempDir()
+	n := &blockingNotifier{}
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() { Watch(ctx, brain, 5*time.Millisecond, n); close(done) }()
+	link := filepath.Join(brain, "x")
+	require.NoError(t, os.Symlink(t.TempDir(), link))
+	waitGone(t, link)
+	require.Eventually(t, func() bool { return n.inFlight.Load() == 1 }, 2*time.Second, time.Millisecond)
+	cancel()
+	select {
+	case <-done:
+	case <-time.After(5 * time.Second):
+		t.Fatal("Watch did not return after cancel")
+	}
+	assert.Zero(t, n.inFlight.Load(), "Notify still running after Watch returned")
+}
+
+// slowToggleNotifier fails slowly (a hung ntfy) while down, then records.
+type slowToggleNotifier struct {
+	recNotifier
+	down    atomic.Bool
+	latency time.Duration
+}
+
+func (r *slowToggleNotifier) Notify(ctx context.Context, m string) error {
+	if r.down.Load() {
+		select {
+		case <-time.After(r.latency):
+		case <-ctx.Done():
+		}
+		return errors.New("ntfy timeout")
+	}
+	return r.recNotifier.Notify(ctx, m)
+}
+
+// Review of PR #180: with a slow notifier the scan's handoff overflows, and
+// those alerts exist only in the overflow counter. Every removal is still
+// delivered or counted in the summary.
+func TestWatchCountsHandoffOverflowWithASlowNotifier(t *testing.T) {
+	brain := t.TempDir()
+	n := &slowToggleNotifier{latency: 30 * time.Millisecond}
+	n.down.Store(true)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go Watch(ctx, brain, 2*time.Millisecond, n)
+	const plants = 40
+	for i := 0; i < plants; i++ {
+		link := filepath.Join(brain, "ov"+strconv.Itoa(i))
+		require.NoError(t, os.Symlink(t.TempDir(), link))
+		waitGone(t, link)
+	}
+	n.down.Store(false)
+	delivered, counted := 0, 0
+	require.Eventually(t, func() bool {
+		n.mu.Lock()
+		defer n.mu.Unlock()
+		delivered, counted = 0, 0
+		for _, m := range n.msgs {
+			if strings.Contains(m, "removed 1 symlink(s)") {
+				delivered++
+			}
+			if i := strings.Index(m, "): "); i >= 0 && strings.Contains(m, "suppressed") {
+				var c int
+				_, _ = fmt.Sscanf(m[i+3:], "%d", &c)
+				counted += c
+			}
+		}
+		return delivered+counted == plants
+	}, 5*time.Second, 10*time.Millisecond, "delivered %d + counted %d of %d", delivered, counted, plants)
+}
+
+// An alert still queued when Watch stops (its send failed, the notifier has
+// since recovered, the retry tick has not come) is flushed once more before
+// Watch returns, on a ctx that is not the cancelled one: toggleNotifier fails
+// on a done ctx, as the real ntfy notifier does.
+func TestWatchFinalFlushSendsAQueuedAlertOnACtxThatOutlivesTheCancel(t *testing.T) {
+	brain := t.TempDir()
+	n := &toggleNotifier{}
+	n.down.Store(true)
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() { Watch(ctx, brain, 300*time.Millisecond, n); close(done) }()
+	link := filepath.Join(brain, "queued")
+	require.NoError(t, os.Symlink(t.TempDir(), link))
+	waitGone(t, link)
+	time.Sleep(20 * time.Millisecond) // let the immediate send fail
+	n.down.Store(false)
+	cancel()
+	<-done
+	assert.Equal(t, 1, n.count(), "the queued alert was not flushed at shutdown")
+}
+
+// lockedBuffer is a goroutine-safe log sink: Watch goroutines of earlier
+// tests may still log while one test captures.
+type lockedBuffer struct {
+	mu  sync.Mutex
+	buf bytes.Buffer
+}
+
+func (b *lockedBuffer) Write(p []byte) (int, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.Write(p)
+}
+
+func (b *lockedBuffer) String() string { b.mu.Lock(); defer b.mu.Unlock(); return b.buf.String() }
+
+func captureLog(t *testing.T) *lockedBuffer {
+	t.Helper()
+	b := &lockedBuffer{}
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(b, nil)))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+	return b
+}
+
+// PR #180 round 2: when the final flush fails (ntfy hung at shutdown) the
+// undelivered alerts vanished with only "will retry" warnings. Watch now logs
+// one error with both counts.
+func TestWatchLogsUndeliveredAndSuppressedCountsWhenTheFinalFlushFails(t *testing.T) {
+	prev := shutdownFlushTimeout
+	shutdownFlushTimeout = 50 * time.Millisecond
+	t.Cleanup(func() { shutdownFlushTimeout = prev })
+	logs := captureLog(t)
+	brain := t.TempDir()
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() { Watch(ctx, brain, 5*time.Millisecond, hungNotifier{latency: time.Hour}); close(done) }()
+	link := filepath.Join(brain, "lost")
+	require.NoError(t, os.Symlink(t.TempDir(), link))
+	waitGone(t, link)
+	cancel()
+	<-done
+	out := logs.String()
+	assert.Contains(t, out, "level=ERROR")
+	assert.Contains(t, out, `msg="symlink tripwire alerts not delivered at shutdown"`)
+	assert.Contains(t, out, "undelivered=1")
+	assert.Contains(t, out, "suppressed=0")
+}
+
+// deliver, given a handoff that already holds alerts and is closed, moves them
+// into the queue and runs the final flush, even though the ctx is cancelled:
+// the drain-on-close path, without depending on when the close lands.
+func TestDeliverFlushesAlertsDrainedFromAClosedHandoffOnACancelledCtx(t *testing.T) {
+	alerts := make(chan string, 3)
+	alerts <- "a1"
+	alerts <- "a2"
+	close(alerts)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	n := &toggleNotifier{}
+	var overflow atomic.Int64
+	deliver(ctx, time.Hour, n, alerts, &overflow)
+	assert.Equal(t, []string{"a1", "a2"}, n.msgs)
+}
+
+// PR #180 round 2: when the first receive after close finds the handoff empty,
+// overflow counted by the scan was never moved into the summary.
+func TestDeliverCountsOverflowWhenTheHandoffIsClosedAndEmpty(t *testing.T) {
+	alerts := make(chan string)
+	close(alerts)
+	n := &recNotifier{}
+	var overflow atomic.Int64
+	overflow.Store(3)
+	deliver(context.Background(), time.Hour, n, alerts, &overflow)
+	require.Len(t, n.msgs, 1)
+	assert.Contains(t, n.msgs[0], "3 further alert(s)")
+}

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/watcher/park.go

@@ -0,0 +1,44 @@
+package watcher
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"path/filepath"
+	"strings"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+)
+
+// Kept out of watcher.go on purpose: that file is covered by the raw-reader
+// guard (internal/extract/callsites_test.go), which forbids any .Open selector
+// there. This function reads nothing from raw/; it creates a file under the
+// brain root, which refuses symlinked directories and never follows a final
+// symlink.
+
+// createParked writes data to raw/needs-review/<filename> through the brain
+// root, never replacing a parked note: on a name clash it tries -2, -3, ...
+// A needs-review that is a symlink, or any non-directory, is refused.
+func createParked(brainDir, filename string, data []byte) error {
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = bfs.Close() }()
+	ext := filepath.Ext(filename)
+	stem := strings.TrimSuffix(filename, ext)
+	for n := 1; n < 10000; n++ {
+		name := filename
+		if n > 1 {
+			name = fmt.Sprintf("%s-%d%s", stem, n, ext)
+		}
+		err := bfs.CreateRegular("raw/needs-review/"+name, data)
+		if err == nil {
+			return nil
+		}
+		if !errors.Is(err, fs.ErrExist) {
+			return err
+		}
+	}
+	return fmt.Errorf("no free name for %q in raw/needs-review", filename)
+}

ingestion/internal/watcher/watcher.go

@@ -9,11 +9,14 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"sync"
 	"time"
 	"unicode"
 
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/extract"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/wing"
 )
 
 // Config holds watcher configuration.
@@ -21,11 +24,24 @@ type Config struct {
 	BrainDir string
 	Interval time.Duration
 	Pipeline pipeline.Config
+
+	// stuck remembers notes that were ingested but could neither be removed
+	// from raw/ nor marked (e.g. a read-only raw/), so later polls skip them
+	// instead of ingesting them again. In memory only: a restart retries once.
+	stuck *sync.Map
+
+	// Resolver, when set, decides each note's wing (hyperguild#205): explicit
+	// subfolder/frontmatter, else classifier + scorer. A note it cannot place
+	// is parked in raw/needs-review/ for a human. Nil keeps the retired layout.
+	Resolver *wing.Resolver
 }
 
 // Start launches the watcher in a background goroutine.
 // It returns immediately. The watcher stops when ctx is cancelled.
 func Start(ctx context.Context, cfg Config) {
+	if cfg.stuck == nil {
+		cfg.stuck = &sync.Map{}
+	}
 	go func() {
 		ticker := time.NewTicker(cfg.Interval)
 		defer ticker.Stop()
@@ -85,7 +101,7 @@ func processDir(ctx context.Context, cfg Config, date string) []error {
 		// path that treats raw/ as "awaiting processing" — this is that path.
 		if d.IsDir() {
 			name := d.Name()
-			if name == "processed" || name == "failed" || name == "rejected" {
+			if name == "processed" || name == "failed" || name == "rejected" || name == "needs-review" {
 				return filepath.SkipDir
 			}
 			return nil
@@ -108,6 +124,12 @@ func processDir(ctx context.Context, cfg Config, date string) []error {
 			return nil
 		}
 
+		if cfg.stuck != nil {
+			if _, skip := cfg.stuck.Load(path); skip {
+				return nil
+			}
+		}
+
 		// Skip files that have already been processed or permanently failed.
 		if _, err := os.Stat(path + ".processed"); err == nil {
 			return nil
@@ -127,9 +149,12 @@ func processDir(ctx context.Context, cfg Config, date string) []error {
 	return errs
 }
 
-// processFile reads a file, calls pipeline.Run, copies it to processed/ or failed/,
+// processFile reads a file, calls pipeline.Run, and archives it into processed/
-// and writes a marker file next to the original so the watcher skips it next poll.
+// or failed/. The original is then removed from raw/ so that raw/ only ever
-// The original file is never deleted, keeping Syncthing-connected vaults (e.g. Obsidian) intact.
+// holds unprocessed input (inbox zero). The removal syncs to Syncthing peers;
+// the archive copy under raw/processed/ or raw/failed/ is what they keep. A
+// marker is written next to the original only if the removal fails, so a
+// stuck file is not re-ingested every poll.
 func processFile(ctx context.Context, cfg Config, root *os.Root, rawDir, path, date string) error {
 	filename := filepath.Base(path)
 	source := deriveSource(filename)
@@ -138,12 +163,25 @@ func processFile(ctx context.Context, cfg Config, root *os.Root, rawDir, path, d
 		return fmt.Errorf("relative path: %w", err)
 	}
 
+	before, err := root.Lstat(rel)
+	if err != nil {
+		return fmt.Errorf("stat before ingest: %w", err)
+	}
 	content, err := extract.TextIn(root, rel)
 	if err != nil {
 		return fmt.Errorf("extract text: %w", err)
 	}
 
-	_, runErr := pipeline.Run(ctx, cfg.Pipeline, cfg.BrainDir, content, source, false)
+	pcfg := cfg.Pipeline
+	if cfg.Resolver != nil {
+		d := cfg.Resolver.Resolve(ctx, wing.Note{Dir: topDir(rel), FrontmatterWing: frontmatterWing(content), Text: content})
+		if d.Source == wing.Exception {
+			return parkForReview(cfg, root, rel, path, filename, content, d, date, before)
+		}
+		pcfg.Wing = d.Wing
+		slog.Info("watcher: wing resolved", "file", filename, "wing", d.Wing, "how", d.Source, "reason", d.Reason)
+	}
+	_, runErr := pipeline.Run(ctx, pcfg, cfg.BrainDir, content, source, false)
 	if runErr != nil {
 		// Copy to failed/ and leave a .failed marker so we don't retry.
 		failedDir := filepath.Join(cfg.BrainDir, "raw", "failed")
@@ -154,9 +192,11 @@ func processFile(ctx context.Context, cfg Config, root *os.Root, rawDir, path, d
 		if cpErr := copyFromRoot(root, rel, dest); cpErr != nil {
 			return fmt.Errorf("copy to failed: %w", cpErr)
 		}
-		if mkErr := os.WriteFile(path+".failed", []byte(runErr.Error()), 0o644); mkErr != nil {
+		if changedSince(root, rel, before) {
-			slog.Error("watcher: failed to write .failed marker", "error", mkErr)
+			slog.Warn("watcher: note changed during ingest; leaving it in raw/ for the next poll", "file", filename)
+			return nil
 		}
+		retire(cfg, root, rel, path, ".failed", runErr.Error())
 
 		slog.Warn("watcher: file failed", "file", filename, "error", runErr)
 
@@ -182,14 +222,45 @@ func processFile(ctx context.Context, cfg Config, root *os.Root, rawDir, path, d
 	if err := copyFromRoot(root, rel, dest); err != nil {
 		return fmt.Errorf("copy to processed: %w", err)
 	}
-	if err := os.WriteFile(path+".processed", []byte(date), 0o644); err != nil {
+	if changedSince(root, rel, before) {
-		slog.Error("watcher: failed to write .processed marker", "error", err)
+		slog.Warn("watcher: note changed during ingest; leaving it in raw/ for the next poll", "file", filename)
+		return nil
 	}
+	retire(cfg, root, rel, path, ".processed", date)
 
 	slog.Info("watcher: file processed", "file", filename, "source", source)
 	return nil
 }
 
+// changedSince reports whether the note at rel differs (size or mtime) from
+// before. A note replaced mid-ingest (Syncthing) was extracted from older
+// content than it now holds, so it must not be removed. Limits: a same-size
+// rewrite with a restored mtime is not detected (the new bytes then survive
+// only in the archive copy), nor a change between this check and Remove.
+func changedSince(root *os.Root, rel string, before os.FileInfo) bool {
+	now, err := root.Lstat(rel)
+	if err != nil {
+		return true
+	}
+	return now.Size() != before.Size() || !now.ModTime().Equal(before.ModTime())
+}
+
+// retire removes an archived original from raw/ (inbox zero). If the removal
+// fails it falls back to a marker file so the watcher still skips the file.
+func retire(cfg Config, root *os.Root, rel, path, markerSuffix, markerBody string) {
+	rmErr := root.Remove(rel)
+	if rmErr == nil {
+		return
+	}
+	slog.Error("watcher: failed to remove archived original; writing marker", "file", rel, "error", rmErr)
+	if err := os.WriteFile(path+markerSuffix, []byte(markerBody), 0o644); err != nil {
+		slog.Error("watcher: failed to write marker; skipping this note until restart", "file", rel, "error", err)
+		if cfg.stuck != nil {
+			cfg.stuck.Store(path, struct{}{})
+		}
+	}
+}
+
 // deriveSource turns a filename into a human-readable source name.
 // "shape-up-book.md" → "Shape Up Book"
 func deriveSource(filename string) string {
@@ -253,3 +324,116 @@ func copyFromRoot(root *os.Root, rel, dst string) error {
 	}
 	return out.Close()
 }
+
+// topDir is the first directory of a raw/-relative path, "" for a top-level file.
+func topDir(rel string) string {
+	if i := strings.IndexByte(filepath.ToSlash(rel), '/'); i > 0 {
+		return filepath.ToSlash(rel)[:i]
+	}
+	return ""
+}
+
+// frontmatterWing reads `wing:` from a note's leading frontmatter, "" if none.
+func frontmatterWing(content string) string {
+	content = strings.ReplaceAll(content, "\r\n", "\n")
+	if !strings.HasPrefix(content, "---\n") {
+		return ""
+	}
+	block, _, _ := strings.Cut(content[4:], "\n---")
+	for _, line := range strings.Split(block, "\n") {
+		if key, val, ok := strings.Cut(line, ":"); ok && strings.TrimSpace(key) == "wing" {
+			return strings.Trim(strings.TrimSpace(val), `"'`)
+		}
+	}
+	return ""
+}
+
+// parkForReview moves a note the resolver could not place into
+// raw/needs-review/, recording the proposal in its frontmatter so a human can
+// approve it by moving it into raw/<wing>/. Nothing is extracted or written to
+// the wiki.
+//
+// The parked copy is created through the brain root (real directories only,
+// O_EXCL, never overwriting) and is the only copy once the original is retired,
+// so the original is removed only after that write succeeds and only if it has
+// not changed since it was read: a newer version delivered while the resolver
+// ran stays in raw/ for the next poll.
+func parkForReview(cfg Config, root *os.Root, rel, path, filename, content string, d wing.Decision, date string, before os.FileInfo) error {
+	var data []byte
+	if strings.ToLower(filepath.Ext(filename)) == ".pdf" {
+		// Binary: park the bytes untouched; the proposal is in log.md only.
+		in, _, err := extract.OpenRegular(root, rel)
+		if err != nil {
+			return fmt.Errorf("park pdf: %w", err)
+		}
+		data, err = io.ReadAll(in)
+		_ = in.Close()
+		if err != nil {
+			return fmt.Errorf("park pdf: %w", err)
+		}
+	} else {
+		data = []byte(withProposal(content, d))
+	}
+	if err := createParked(cfg.BrainDir, filename, data); err != nil {
+		return fmt.Errorf("park note: %w", err)
+	}
+	if err := appendWatcherLog(cfg.BrainDir, filename, fmt.Errorf("needs review (proposed wing %q): %s", d.Wing, d.Reason), date); err != nil {
+		slog.Error("watcher: failed to write log entry", "error", err)
+	}
+	slog.Info("watcher: parked for review", "file", filename, "proposed_wing", d.Wing, "reason", d.Reason)
+	if changedSince(root, rel, before) {
+		slog.Warn("watcher: note changed while it was being resolved; leaving the newer version in raw/", "file", filename)
+		return nil
+	}
+	retire(cfg, root, rel, path, ".processed", date)
+	return nil
+}
+
+// proposalKeys are the frontmatter keys the resolver owns in a parked note.
+var proposalKeys = map[string]bool{"proposed_wing": true, "proposal_confidence": true, "proposal_reason": true}
+
+// withProposal adds the resolver's proposal to a note's frontmatter, creating
+// the block when the note has none. Every value is on one line: the wing only
+// if it is a plain wing name (else it appears in the reason alone), strings
+// Go-quoted. Any proposal keys the note already carried are dropped first, so a
+// note cannot pre-empt the resolver's (frontmatter reads are first-wins).
+// Line endings are normalised to LF so a CRLF note keeps one valid block.
+func withProposal(content string, d wing.Decision) string {
+	content = strings.ReplaceAll(content, "\r\n", "\n")
+	reason := d.Reason
+	var kv strings.Builder
+	if d.Wing != "" && brain.Sanitise(d.Wing) == d.Wing {
+		fmt.Fprintf(&kv, "proposed_wing: %s\n", d.Wing)
+	} else if d.Wing != "" {
+		reason = fmt.Sprintf("proposed wing %q is not a plain wing name; %s", d.Wing, reason)
+	}
+	fmt.Fprintf(&kv, "proposal_confidence: %.2f\nproposal_reason: %q\n", d.Confidence, reason)
+
+	if !strings.HasPrefix(content, "---\n") {
+		return "---\n" + kv.String() + "---\n" + content
+	}
+	block, rest, found := cutFence(content[4:])
+	if !found {
+		return "---\n" + kv.String() + "---\n" + content
+	}
+	var kept []string
+	for _, line := range strings.Split(block, "\n") {
+		if key, _, ok := strings.Cut(line, ":"); ok && proposalKeys[strings.TrimSpace(key)] && !strings.HasPrefix(line, " ") {
+			continue
+		}
+		kept = append(kept, line)
+	}
+	return "---\n" + kv.String() + strings.Join(kept, "\n") + "\n---" + rest
+}
+
+// cutFence splits s at the first closing fence: a line that is exactly "---".
+// "----" or "---x" is not a fence, matching how the frontmatter readers parse.
+func cutFence(s string) (block, rest string, found bool) {
+	if i := strings.Index(s, "\n---\n"); i >= 0 {
+		return s[:i], s[i+4:], true
+	}
+	if strings.HasSuffix(s, "\n---") {
+		return s[:len(s)-4], "", true
+	}
+	return "", "", false
+}

ingestion/internal/watcher/watcher_test.go

@@ -89,13 +89,12 @@ func TestStart_ProcessesFile(t *testing.T) {
 	}
 	require.True(t, found, "file should be copied to processed/")
 
-	// Original file should still exist (copy, not move — keeps Obsidian vault intact).
+	// Inbox zero: once archived, the original leaves raw/ and no marker is
+	// left behind, so what remains in raw/ is exactly the unprocessed set.
 	_, err := os.Stat(rawFile)
-	assert.NoError(t, err, "original file should remain in raw/")
+	assert.ErrorIs(t, err, os.ErrNotExist, "original should be removed from raw/ once archived")
-
-	// A .processed marker should exist next to the original.
 	_, err = os.Stat(rawFile + ".processed")
-	assert.NoError(t, err, ".processed marker should be written")
+	assert.ErrorIs(t, err, os.ErrNotExist, "no .processed marker: the archive copy is the record")
 
 	// Wiki page should exist.
 	wikiPath := filepath.Join(brainDir, "wiki", "sources", "shape-up-book.md")
@@ -142,13 +141,11 @@ func TestStart_MovesToFailedOnError(t *testing.T) {
 	}
 	require.True(t, found, "file should be copied to failed/")
 
-	// Original file should still exist (copy, not move — keeps Obsidian vault intact).
+	// Inbox zero: a quarantined original leaves raw/ too, no marker beside it.
 	_, err := os.Stat(rawFile)
-	assert.NoError(t, err, "original file should remain in raw/")
+	assert.ErrorIs(t, err, os.ErrNotExist, "original should be removed from raw/ once quarantined")
-
-	// A .failed marker should exist next to the original.
 	_, err = os.Stat(rawFile + ".failed")
-	assert.NoError(t, err, ".failed marker should be written")
+	assert.ErrorIs(t, err, os.ErrNotExist, "no .failed marker: failed/ is the record")
 
 	// log.md should contain a watcher error entry.
 	logContent, err := os.ReadFile(filepath.Join(brainDir, "log.md"))
@@ -390,3 +387,86 @@ func TestProcessDir_DoesNotHangUnderAFIFOSwapRace(t *testing.T) {
 		t.Fatalf("the watcher hung on a swapped-in FIFO after %d iterations", iters.Load())
 	}
 }
+
+// A note whose removal AND marker write both fail (read-only raw/) must not be
+// re-ingested on every poll: each pass would write another archive copy.
+func TestProcessDir_DoesNotReingestANoteItCannotRetire(t *testing.T) {
+	brainDir := setupBrainDir(t)
+	rawDir := filepath.Join(brainDir, "raw")
+	require.NoError(t, os.WriteFile(filepath.Join(rawDir, "stuck.md"), []byte("Content."), 0o644))
+	// processed/ must exist and stay writable; only raw/ itself is locked.
+	require.NoError(t, os.MkdirAll(filepath.Join(rawDir, "processed"), 0o755))
+	require.NoError(t, os.Chmod(rawDir, 0o555))
+	t.Cleanup(func() { _ = os.Chmod(rawDir, 0o755) })
+
+	var calls atomic.Int32
+	cfg := Config{
+		BrainDir: brainDir,
+		Pipeline: pipeline.Config{
+			Complete: func(ctx context.Context, s, u string) (string, error) {
+				calls.Add(1)
+				return successComplete(pipeline.RawPage{Title: "Stuck", Type: "source", Subtype: "article", Content: "x\n"})(ctx, s, u)
+			},
+			Schema: "# Schema",
+		},
+		stuck: &sync.Map{},
+	}
+	for i := 0; i < 3; i++ {
+		processDir(context.Background(), cfg, "2026-10-19")
+	}
+	assert.Equal(t, int32(1), calls.Load(), "a note that cannot be retired is ingested once, not once per poll")
+}
+
+// If the archive copy cannot be written, the original is the only copy left:
+// it must stay in raw/.
+func TestProcessDir_KeepsTheOriginalWhenTheArchiveCopyFails(t *testing.T) {
+	brainDir := setupBrainDir(t)
+	rawDir := filepath.Join(brainDir, "raw")
+	note := filepath.Join(rawDir, "keep-me.md")
+	require.NoError(t, os.WriteFile(note, []byte("Content."), 0o644))
+	// The dated archive dir exists but is read-only: MkdirAll succeeds, the
+	// copy itself (os.Create) fails.
+	dated := filepath.Join(rawDir, "processed", "2026-10-19")
+	require.NoError(t, os.MkdirAll(dated, 0o755))
+	require.NoError(t, os.Chmod(dated, 0o555))
+	t.Cleanup(func() { _ = os.Chmod(dated, 0o755) })
+
+	cfg := Config{
+		BrainDir: brainDir,
+		Pipeline: pipeline.Config{
+			Complete: successComplete(pipeline.RawPage{Title: "Keep Me", Type: "source", Subtype: "article", Content: "x\n"}),
+			Schema:   "# Schema",
+		},
+	}
+	errs := processDir(context.Background(), cfg, "2026-10-19")
+
+	assert.NotEmpty(t, errs, "the failed archive is reported")
+	_, err := os.Stat(note)
+	assert.NoError(t, err, "original stays in raw/ when it could not be archived")
+}
+
+// If the note is replaced (e.g. by Syncthing) while it is being ingested, the
+// wiki page was extracted from the old content; removing the original would
+// leave the new content only in the archive and never re-ingest it. Observes
+// size/mtime change only: a same-size rewrite with a restored mtime is not caught.
+func TestProcessDir_KeepsANoteThatChangedWhileItWasBeingIngested(t *testing.T) {
+	brainDir := setupBrainDir(t)
+	note := filepath.Join(brainDir, "raw", "edited.md")
+	require.NoError(t, os.WriteFile(note, []byte("old"), 0o644))
+
+	cfg := Config{
+		BrainDir: brainDir,
+		Pipeline: pipeline.Config{
+			Complete: func(ctx context.Context, s, u string) (string, error) {
+				require.NoError(t, os.WriteFile(note, []byte("newer and longer content"), 0o644))
+				return successComplete(pipeline.RawPage{Title: "Edited", Type: "source", Subtype: "article", Content: "x\n"})(ctx, s, u)
+			},
+			Schema: "# Schema",
+		},
+	}
+	processDir(context.Background(), cfg, "2026-10-19")
+
+	got, err := os.ReadFile(note)
+	require.NoError(t, err, "a note that changed during ingest must stay in raw/")
+	assert.Equal(t, "newer and longer content", string(got))
+}

ingestion/internal/watcher/watcher_wing_test.go

@@ -0,0 +1,331 @@
+package watcher
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/wing"
+)
+
+type stubClassifier struct {
+	s     wing.Suggestion
+	err   error
+	calls atomic.Int32
+}
+
+func (c *stubClassifier) Classify(context.Context, string, []string) (wing.Suggestion, error) {
+	c.calls.Add(1)
+	return c.s, c.err
+}
+
+type stubScorer map[string]float64
+
+func (s stubScorer) Score(string) map[string]float64 { return s }
+
+func wingResolver(c wing.Classifier, s wing.Scorer) *wing.Resolver {
+	return &wing.Resolver{
+		Known:      []string{"radar", "homelab", "client-x"},
+		Eligible:   func(w string) bool { return w != "client-x" },
+		Classifier: c,
+		Scorer:     s,
+		Threshold:  0.8,
+	}
+}
+
+func wingTestCfg(t *testing.T, r *wing.Resolver, llmCalls *atomic.Int32) (Config, string) {
+	t.Helper()
+	brainDir := setupBrainDir(t)
+	return Config{
+		BrainDir: brainDir,
+		Resolver: r,
+		Pipeline: pipeline.Config{
+			Schema: "# Schema",
+			Complete: func(ctx context.Context, s, u string) (string, error) {
+				llmCalls.Add(1)
+				return successComplete(pipeline.RawPage{Title: "Talk", Type: "source", Subtype: "video", Content: "## Summary\n\nx\n"})(ctx, s, u)
+			},
+		},
+	}, brainDir
+}
+
+func put(t *testing.T, brainDir, rel, body string) {
+	t.Helper()
+	full := filepath.Join(brainDir, "raw", rel)
+	require.NoError(t, os.MkdirAll(filepath.Dir(full), 0o755))
+	require.NoError(t, os.WriteFile(full, []byte(body), 0o644))
+}
+
+func has(brainDir, rel string) bool {
+	_, err := os.Stat(filepath.Join(brainDir, rel))
+	return err == nil
+}
+
+func TestProcessDir_ASubfolderNamesTheWing(t *testing.T) {
+	var llmCalls atomic.Int32
+	clf := &stubClassifier{}
+	cfg, brainDir := wingTestCfg(t, wingResolver(clf, stubScorer{}), &llmCalls)
+	put(t, brainDir, "radar/dark-factory.md", "A talk about factories.")
+
+	errs := processDir(context.Background(), cfg, "2026-10-20")
+
+	require.Empty(t, errs)
+	assert.True(t, has(brainDir, "wiki/radar/sources/dark-factory.md"), "lands in the named wing")
+	assert.False(t, has(brainDir, "raw/radar/dark-factory.md"), "inbox zero holds for subfolders too")
+	assert.Zero(t, clf.calls.Load(), "an explicit wing costs no classification")
+}
+
+func TestProcessDir_ANoteTheResolverCannotPlaceIsParkedNotIngested(t *testing.T) {
+	var llmCalls atomic.Int32
+	clf := &stubClassifier{s: wing.Suggestion{Wing: "radar", Confidence: 0.5, Reason: "maybe"}}
+	cfg, brainDir := wingTestCfg(t, wingResolver(clf, stubScorer{"radar": 3}), &llmCalls)
+	put(t, brainDir, "unsure.md", "Some note.")
+
+	errs := processDir(context.Background(), cfg, "2026-10-20")
+
+	require.Empty(t, errs)
+	assert.Zero(t, llmCalls.Load(), "no extraction runs for an unplaced note")
+	assert.False(t, has(brainDir, "raw/unsure.md"), "leaves the top of raw/")
+	parked, err := os.ReadFile(filepath.Join(brainDir, "raw", "needs-review", "unsure.md"))
+	require.NoError(t, err)
+	assert.Contains(t, string(parked), "proposed_wing: radar")
+	assert.Contains(t, string(parked), "below threshold")
+	assert.Contains(t, string(parked), "Some note.", "the note body is preserved")
+}
+
+func TestProcessDir_ANoteInAClientWingFolderIsParked(t *testing.T) {
+	var llmCalls atomic.Int32
+	cfg, brainDir := wingTestCfg(t, wingResolver(&stubClassifier{}, stubScorer{}), &llmCalls)
+	put(t, brainDir, "client-x/secret.md", "Client material.")
+
+	require.Empty(t, processDir(context.Background(), cfg, "2026-10-20"))
+
+	assert.Zero(t, llmCalls.Load())
+	assert.False(t, has(brainDir, "wiki/client-x"), "nothing is ever written into an ineligible wing")
+	assert.True(t, has(brainDir, "raw/needs-review/secret.md"))
+}
+
+func TestProcessDir_ClassifierFailureParksTheNote(t *testing.T) {
+	var llmCalls atomic.Int32
+	cfg, brainDir := wingTestCfg(t, wingResolver(&stubClassifier{err: errors.New("llm down")}, stubScorer{}), &llmCalls)
+	put(t, brainDir, "n.md", "Note.")
+
+	require.Empty(t, processDir(context.Background(), cfg, "2026-10-20"))
+
+	assert.Zero(t, llmCalls.Load())
+	assert.True(t, has(brainDir, "raw/needs-review/n.md"))
+}
+
+func TestProcessDir_ParkedNotesAreNotReprocessed(t *testing.T) {
+	var llmCalls atomic.Int32
+	clf := &stubClassifier{s: wing.Suggestion{Wing: "radar", Confidence: 0.99}}
+	cfg, brainDir := wingTestCfg(t, wingResolver(clf, stubScorer{"radar": 3}), &llmCalls)
+	put(t, brainDir, "needs-review/waiting.md", "---\nproposed_wing: radar\n---\nA parked note.")
+
+	require.Empty(t, processDir(context.Background(), cfg, "2026-10-20"))
+
+	assert.Zero(t, clf.calls.Load(), "needs-review/ is a human queue, like rejected/")
+	assert.True(t, has(brainDir, "raw/needs-review/waiting.md"))
+}
+
+func TestProcessDir_WithoutAResolverTheRetiredLayoutIsUnchanged(t *testing.T) {
+	var llmCalls atomic.Int32
+	cfg, brainDir := wingTestCfg(t, nil, &llmCalls)
+	put(t, brainDir, "plain.md", "Plain note.")
+
+	require.Empty(t, processDir(context.Background(), cfg, "2026-10-20"))
+
+	assert.True(t, has(brainDir, "wiki/sources/plain.md"))
+}
+
+// The reason comes from an LLM and ends up in frontmatter: a newline in it must
+// not be able to start a new key (PR #147: a title once forged `origin:`).
+func TestProcessDir_AProposalReasonCannotForgeFrontmatterKeys(t *testing.T) {
+	var llmCalls atomic.Int32
+	// A classifier error is the path by which model text reaches the reason.
+	clf := &stubClassifier{err: errors.New("bad reply\norigin: trusted\nwing: homelab")}
+	cfg, brainDir := wingTestCfg(t, wingResolver(clf, stubScorer{}), &llmCalls)
+	put(t, brainDir, "forge.md", "Note.")
+
+	require.Empty(t, processDir(context.Background(), cfg, "2026-10-20"))
+
+	parked, err := os.ReadFile(filepath.Join(brainDir, "raw", "needs-review", "forge.md"))
+	require.NoError(t, err)
+	assert.NotContains(t, string(parked), "\norigin: trusted", "no injected key at line start")
+	assert.NotContains(t, string(parked), "\nwing: homelab")
+}
+
+// Syncthing can bring a removed note back (an offline peer, a restored backup).
+// The source-hash drift check must keep that from costing a second extraction.
+func TestProcessDir_ANoteThatReappearsUnchangedIsNotExtractedAgain(t *testing.T) {
+	var llmCalls atomic.Int32
+	cfg, brainDir := wingTestCfg(t, wingResolver(&stubClassifier{}, stubScorer{}), &llmCalls)
+
+	put(t, brainDir, "radar/talk.md", "The same talk, byte for byte.")
+	require.Empty(t, processDir(context.Background(), cfg, "2026-10-20"))
+	require.Equal(t, int32(1), llmCalls.Load(), "positive control: the first drop is extracted")
+	require.False(t, has(brainDir, "raw/radar/talk.md"))
+
+	put(t, brainDir, "radar/talk.md", "The same talk, byte for byte.") // the peer sends it back
+	require.Empty(t, processDir(context.Background(), cfg, "2026-10-21"))
+
+	assert.Equal(t, int32(1), llmCalls.Load(), "an unchanged source is not extracted twice")
+	assert.False(t, has(brainDir, "raw/radar/talk.md"), "and inbox zero still holds")
+}
+
+func TestProcessDir_ANoteThatReappearsChangedIsExtractedAgain(t *testing.T) {
+	var llmCalls atomic.Int32
+	cfg, brainDir := wingTestCfg(t, wingResolver(&stubClassifier{}, stubScorer{}), &llmCalls)
+
+	put(t, brainDir, "radar/talk.md", "Version one.")
+	require.Empty(t, processDir(context.Background(), cfg, "2026-10-20"))
+	put(t, brainDir, "radar/talk.md", "Version two, edited.")
+	require.Empty(t, processDir(context.Background(), cfg, "2026-10-21"))
+
+	assert.Equal(t, int32(2), llmCalls.Load(), "a real edit must still be picked up")
+}
+
+// The parked copy is the only copy once the original is retired, so two notes
+// that share a name must both survive.
+func TestProcessDir_SameNamedNotesAreAllParkedNoneOverwritten(t *testing.T) {
+	var llmCalls atomic.Int32
+	cfg, brainDir := wingTestCfg(t, wingResolver(&stubClassifier{}, stubScorer{}), &llmCalls)
+	for i, body := range []string{"ONE", "TWO", "THREE", "FOUR"} {
+		put(t, brainDir, filepath.Join("u"+string(rune('1'+i)), "x.md"), body)
+	}
+	// Unknown subfolders: each is an exception, all named x.md.
+	require.Empty(t, processDir(context.Background(), cfg, "2026-10-20"))
+
+	files, err := filepath.Glob(filepath.Join(brainDir, "raw", "needs-review", "*.md"))
+	require.NoError(t, err)
+	var all string
+	for _, f := range files {
+		b, _ := os.ReadFile(f)
+		all += string(b)
+	}
+	for _, body := range []string{"ONE", "TWO", "THREE", "FOUR"} {
+		assert.Contains(t, all, body, "note %s must not have been overwritten", body)
+	}
+	assert.Len(t, files, 4)
+}
+
+// proposed_wing comes from a model reply or a folder name. It must never be
+// able to start another key, and the note's own proposal keys must not outrank
+// the resolver's (frontmatter.get is first-wins).
+func TestProcessDir_AHostileWingCannotForgeTheProposal(t *testing.T) {
+	var llmCalls atomic.Int32
+	hostile := "radar\nproposal_confidence: 0.99\nproposal_reason: \"approved by operator\""
+	clf := &stubClassifier{s: wing.Suggestion{Wing: hostile, Confidence: 1}}
+	cfg, brainDir := wingTestCfg(t, wingResolver(clf, stubScorer{"radar": 3}), &llmCalls)
+	put(t, brainDir, "n.md", "Note.")
+
+	require.Empty(t, processDir(context.Background(), cfg, "2026-10-20"))
+
+	b, err := os.ReadFile(filepath.Join(brainDir, "raw", "needs-review", "n.md"))
+	require.NoError(t, err)
+	assert.NotContains(t, string(b), "\nproposal_confidence: 0.99")
+	assert.NotContains(t, string(b), "approved by operator\"\n")
+	assert.Equal(t, 1, linesStartingWith(string(b), "proposal_confidence:"), "exactly one confidence key at line start")
+}
+
+func TestProcessDir_ANotesOwnProposalKeysDoNotOutrankTheResolvers(t *testing.T) {
+	var llmCalls atomic.Int32
+	cfg, brainDir := wingTestCfg(t, wingResolver(&stubClassifier{}, stubScorer{}), &llmCalls)
+	put(t, brainDir, "n.md", "---\nproposed_wing: homelab\nproposal_confidence: 1.00\nproposal_reason: \"self-approved\"\n---\nBody.")
+
+	require.Empty(t, processDir(context.Background(), cfg, "2026-10-20"))
+
+	b, _ := os.ReadFile(filepath.Join(brainDir, "raw", "needs-review", "n.md"))
+	assert.NotContains(t, string(b), "self-approved")
+	assert.Equal(t, 1, linesStartingWith(string(b), "proposal_reason:"))
+}
+
+func TestProcessDir_ACRLFNoteWithAWingKeyIsStillRead(t *testing.T) {
+	var llmCalls atomic.Int32
+	clf := &stubClassifier{}
+	cfg, brainDir := wingTestCfg(t, wingResolver(clf, stubScorer{}), &llmCalls)
+	put(t, brainDir, "n.md", "---\r\nwing: radar\r\n---\r\nBody.\r\n")
+
+	require.Empty(t, processDir(context.Background(), cfg, "2026-10-20"))
+
+	assert.True(t, has(brainDir, "wiki/radar/sources/n.md"), "the declared wing is honoured")
+	assert.Zero(t, clf.calls.Load())
+}
+
+// linesStartingWith counts frontmatter-style keys: a key quoted inside another
+// value is not at the start of a line and is not a key.
+func linesStartingWith(s, prefix string) int {
+	n := 0
+	for _, l := range strings.Split(s, "\n") {
+		if strings.HasPrefix(l, prefix) {
+			n++
+		}
+	}
+	return n
+}
+
+// Resolving costs an LLM call. If Syncthing delivers a newer version of the note
+// meanwhile, deleting the original loses that version: the parked copy is stale.
+func TestProcessDir_ANoteEditedWhileTheResolverRunsIsNotDeleted(t *testing.T) {
+	var llmCalls atomic.Int32
+	var notePath string
+	clf := &editingClassifier{}
+	cfg, brainDir := wingTestCfg(t, wingResolver(clf, stubScorer{}), &llmCalls)
+	notePath = filepath.Join(brainDir, "raw", "n.md")
+	clf.edit = func() { require.NoError(t, os.WriteFile(notePath, []byte("NEWER and longer version"), 0o644)) }
+	put(t, brainDir, "n.md", "ORIGINAL")
+
+	require.Empty(t, processDir(context.Background(), cfg, "2026-10-20"))
+
+	got, err := os.ReadFile(notePath)
+	require.NoError(t, err, "the edited note must still be in raw/")
+	assert.Equal(t, "NEWER and longer version", string(got))
+}
+
+type editingClassifier struct{ edit func() }
+
+func (c *editingClassifier) Classify(context.Context, string, []string) (wing.Suggestion, error) {
+	c.edit()
+	return wing.Suggestion{}, nil
+}
+
+// A planted symlink at raw/needs-review must not redirect a parked note out of
+// the brain, nor lose it from the review queue.
+func TestProcessDir_AParkedNoteIsNeverWrittenThroughASymlinkedNeedsReview(t *testing.T) {
+	var llmCalls atomic.Int32
+	cfg, brainDir := wingTestCfg(t, wingResolver(&stubClassifier{}, stubScorer{}), &llmCalls)
+	outside := t.TempDir()
+	require.NoError(t, os.Symlink(outside, filepath.Join(brainDir, "raw", "needs-review")))
+	put(t, brainDir, "n.md", "Note.")
+
+	errs := processDir(context.Background(), cfg, "2026-10-20")
+
+	assert.NotEmpty(t, errs, "parking is refused, loudly")
+	entries, _ := os.ReadDir(outside)
+	assert.Empty(t, entries, "nothing was written through the symlink")
+	assert.True(t, has(brainDir, "raw/n.md"), "the note stays where it was")
+}
+
+func TestWithProposal_ANonFenceDashLineDoesNotCloseTheBlock(t *testing.T) {
+	out := withProposal("---\nfoo: bar\n----\nBody", wing.Decision{Wing: "radar", Confidence: 0.4, Reason: "r"})
+	lines := strings.Split(out, "\n")
+	require.Equal(t, "---", lines[0])
+	closing := -1
+	for i := 1; i < len(lines); i++ {
+		if lines[i] == "---" {
+			closing = i
+			break
+		}
+	}
+	require.Positive(t, closing, "the proposal block is closed by a real fence")
+	assert.Contains(t, strings.Join(lines[:closing], "\n"), "proposal_reason:")
+	assert.NotContains(t, strings.Join(lines[:closing], "\n"), "foo: bar", "the unfenced note is body, not part of the block")
+}

ingestion/internal/wiki/index.go

@@ -3,10 +3,9 @@ package wiki
 
 import (
 	"fmt"
-	"os"
-	"path/filepath"
 	"strings"
 
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/textutil"
 )
 
@@ -16,6 +15,11 @@ func RebuildIndex(brainDir, date string) error {
 	if err != nil {
 		return fmt.Errorf("load inventory: %w", err)
 	}
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
 
 	total := len(inv[PageTypeConcept]) + len(inv[PageTypeEntity]) + len(inv[PageTypeSource])
 	var sb strings.Builder
@@ -34,7 +38,7 @@ func RebuildIndex(brainDir, date string) error {
 		label := strings.ToUpper(string(pt)[:1]) + string(pt)[1:]
 		fmt.Fprintf(&sb, "## %s\n\n", label)
 		for _, e := range entries {
-			summary := pageFirstSentence(brainDir, e)
+			summary := pageFirstSentence(bfs, e)
 			if summary != "" {
 				fmt.Fprintf(&sb, "- [[%s|%s]] — %s\n", e.Slug, e.Title, summary)
 			} else {
@@ -44,13 +48,14 @@ 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()))
 }
 
-func pageFirstSentence(brainDir string, e Entry) string {
+// pageFirstSentence reads the page through the brain root, regular files
-	path := filepath.Join(brainDir, "wiki", string(e.Type), e.Slug+".md")
+// only (hyperguild#157).
-	content, err := os.ReadFile(path)
+func pageFirstSentence(bfs *brainfs.Brain, e Entry) string {
+	content, err := bfs.ReadRegular("wiki/" + string(e.Type) + "/" + e.Slug + ".md")
 	if err != nil {
 		return ""
 	}

ingestion/internal/wiki/inventory.go

@@ -3,36 +3,45 @@ package wiki
 
 import (
 	"bufio"
+	"bytes"
+	"errors"
 	"fmt"
-	"os"
+	"io/fs"
-	"path/filepath"
 	"strings"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
 )
 
 // LoadInventory walks brain/wiki/ and returns all pages grouped by type.
-// Missing subdirectories are silently skipped.
+// Missing subdirectories are silently skipped. Pages are listed and read
+// through the brain root, regular files only (hyperguild#157); a type
+// directory that is a symlink is an error.
 func LoadInventory(brainDir string) (map[PageType][]Entry, error) {
 	result := map[PageType][]Entry{
 		PageTypeConcept: {},
 		PageTypeEntity:  {},
 		PageTypeSource:  {},
 	}
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return nil, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
 	for pt := range result {
-		dir := filepath.Join(brainDir, "wiki", string(pt))
+		dir := "wiki/" + string(pt)
-		entries, err := os.ReadDir(dir)
+		names, err := bfs.ReadDirRegular(dir)
-		if os.IsNotExist(err) {
+		if errors.Is(err, fs.ErrNotExist) {
 			continue
 		}
 		if err != nil {
 			return nil, fmt.Errorf("read dir %s: %w", dir, err)
 		}
-		for _, e := range entries {
+		for _, name := range names {
-			if e.IsDir() || !strings.HasSuffix(e.Name(), ".md") {
+			if !strings.HasSuffix(name, ".md") {
 				continue
 			}
-			slug := strings.TrimSuffix(e.Name(), ".md")
+			slug := strings.TrimSuffix(name, ".md")
-			path := filepath.Join(dir, e.Name())
+			title, aliases := readFrontmatter(bfs, dir+"/"+name, slug)
-			title, aliases := readFrontmatter(path, slug)
 			result[pt] = append(result[pt], Entry{Slug: slug, Title: title, Aliases: aliases, Type: pt})
 		}
 	}
@@ -41,15 +50,14 @@ func LoadInventory(brainDir string) (map[PageType][]Entry, error) {
 
 // readFrontmatter extracts title and aliases from YAML frontmatter.
 // Falls back to slug for title and empty aliases on any error.
-func readFrontmatter(path, fallbackSlug string) (title string, aliases []string) {
+func readFrontmatter(bfs *brainfs.Brain, rel, fallbackSlug string) (title string, aliases []string) {
 	title = fallbackSlug
-	f, err := os.Open(path)
+	content, err := bfs.ReadRegular(rel)
 	if err != nil {
 		return
 	}
-	defer f.Close() //nolint:errcheck
 
-	scanner := bufio.NewScanner(f)
+	scanner := bufio.NewScanner(bytes.NewReader(content))
 	inFM := false
 	inAliases := false
 	for scanner.Scan() {
@@ -88,3 +96,79 @@ func readFrontmatter(path, fallbackSlug string) (title string, aliases []string)
 	}
 	return
 }
+
+// LoadWingInventory returns the pages of ONE wing, grouped by type. Sources
+// come from wiki/<wing>/sources/; concepts and entities live together in
+// wiki/<wing>/facts/ and are told apart by their `kind:` frontmatter. A facts
+// page without a kind (a hand-written note) is left out, so extraction can
+// never merge into something it did not create. Other wings are never read.
+func LoadWingInventory(brainDir, wing string) (map[PageType][]Entry, error) {
+	result := map[PageType][]Entry{PageTypeConcept: {}, PageTypeEntity: {}, PageTypeSource: {}}
+	bfs, err := brainfs.Open(brainDir)
+	if err != nil {
+		return nil, fmt.Errorf("open brain: %w", err)
+	}
+	defer func() { _ = bfs.Close() }()
+	for _, hall := range []string{"sources", "facts"} {
+		dir := "wiki/" + wing + "/" + hall
+		names, err := bfs.ReadDirRegular(dir)
+		if errors.Is(err, fs.ErrNotExist) {
+			continue
+		}
+		if err != nil {
+			return nil, fmt.Errorf("read dir %s: %w", dir, err)
+		}
+		for _, name := range names {
+			if !strings.HasSuffix(name, ".md") {
+				continue
+			}
+			rel := dir + "/" + name
+			slug := strings.TrimSuffix(name, ".md")
+			pt := PageTypeSource
+			if hall == "facts" {
+				var ok bool
+				if pt, ok = kindOf(bfs, rel); !ok {
+					continue
+				}
+			}
+			title, aliases := readFrontmatter(bfs, rel, slug)
+			result[pt] = append(result[pt], Entry{Slug: slug, Title: title, Aliases: aliases, Type: pt, Path: rel})
+		}
+	}
+	return result, nil
+}
+
+// kindOf reads `kind:` from a facts page's frontmatter.
+func kindOf(bfs *brainfs.Brain, rel string) (PageType, bool) {
+	content, err := bfs.ReadRegular(rel)
+	if err != nil {
+		return "", false
+	}
+	return KindFromContent(string(content))
+}
+
+// KindFromContent maps frontmatter `kind: concept|entity` to a PageType.
+func KindFromContent(content string) (PageType, bool) {
+	inFM := false
+	for _, line := range strings.Split(content, "\n") {
+		if strings.TrimSpace(line) == "---" {
+			if inFM {
+				break
+			}
+			inFM = true
+			continue
+		}
+		if !inFM {
+			continue
+		}
+		if key, val, ok := strings.Cut(line, ":"); ok && strings.TrimSpace(key) == "kind" {
+			switch strings.Trim(strings.TrimSpace(val), `"'`) {
+			case "concept":
+				return PageTypeConcept, true
+			case "entity":
+				return PageTypeEntity, true
+			}
+		}
+	}
+	return "", false
+}

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/root_test.go

@@ -0,0 +1,79 @@
+package wiki
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest"
+)
+
+// hyperguild#157 slice 4: LoadInventory listed wiki/<type>/ with os.ReadDir
+// and opened each .md by path, so a symlinked page put the target's title and
+// aliases into the inventory (and the LLM prompts built from it), and a FIFO
+// hung it. RebuildIndex read first sentences the same way.
+func TestLoadInventoryRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) {
+	brain := t.TempDir()
+	dir := filepath.Join(brain, "wiki", "concepts")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "ok.md"), []byte("---\ntitle: zqinside\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(dir, "leak.md")))
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "s.md"), filepath.Join(dir, "inlink.md")))
+
+	inv, err := LoadInventory(brain)
+	require.NoError(t, err)
+	got := fmt.Sprintf("%+v", inv)
+	assert.Contains(t, got, "zqinside", "positive control")
+	assert.NotContains(t, got, brainfstest.Sentinel)
+	assert.NotContains(t, got, "leak", "a symlinked page is not listed")
+	assert.NotContains(t, got, "inlink", "a page linked to another brain file is not listed")
+
+	p := filepath.Join(dir, "r.md")
+	read := func() string {
+		inv, _ := LoadInventory(brain)
+		return fmt.Sprintf("%+v", inv)
+	}
+	brainfstest.AssertNoLeak(t, p, "---\ntitle: zqinside\n---\n", 1500*time.Millisecond, read)
+	brainfstest.AssertNoLeakFrom(t, p, "---\ntitle: zqinside\n---\n", inBrain, 1500*time.Millisecond, read)
+	brainfstest.AssertNoHang(t, p, "---\ntitle: zqinside\n---\n", 1500*time.Millisecond, 6*time.Second, func() { _ = read() })
+}
+
+func TestLoadInventoryReturnsErrNotRegularForASymlinkedTypeDir(t *testing.T) {
+	brain := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "wiki"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(brain, "raw"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(brain, "raw", "r.md"), []byte("---\ntitle: zqrawonly\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "raw"), filepath.Join(brain, "wiki", "concepts")))
+	inv, err := LoadInventory(brain)
+	require.ErrorIs(t, err, brainfs.ErrNotRegular)
+	assert.NotContains(t, fmt.Sprintf("%+v", inv), "zqrawonly")
+}
+
+func TestRebuildIndexDoesNotReadAPageSwappedForASymlink(t *testing.T) {
+	brain := t.TempDir()
+	dir := filepath.Join(brain, "wiki", "concepts")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	p := filepath.Join(dir, "r.md")
+	require.NoError(t, os.WriteFile(p, []byte("---\ntitle: R\n---\nzqinside sentence.\n"), 0o644))
+	require.NoError(t, RebuildIndex(brain, "2026-10-04"))
+	idx, err := os.ReadFile(filepath.Join(brain, "wiki", "index.md"))
+	require.NoError(t, err)
+	require.Contains(t, string(idx), "zqinside", "positive control: the summary is read")
+
+	read := func() string {
+		_ = RebuildIndex(brain, "2026-10-04")
+		b, _ := os.ReadFile(filepath.Join(brain, "wiki", "index.md"))
+		return string(b)
+	}
+	brainfstest.AssertNoLeak(t, p, "---\ntitle: R\n---\nzqinside sentence.\n", 1500*time.Millisecond, read)
+	inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md"))
+	brainfstest.AssertNoLeakFrom(t, p, "---\ntitle: R\n---\nzqinside sentence.\n", inBrain, 1500*time.Millisecond, read)
+	brainfstest.AssertNoHang(t, p, "---\ntitle: R\n---\nzqinside sentence.\n", 1500*time.Millisecond, 6*time.Second, func() { _ = read() })
+}

ingestion/internal/wiki/types.go

@@ -22,4 +22,5 @@ type Entry struct {
 	Title   string
 	Aliases []string
 	Type    PageType
+	Path    string // brain-relative path; set for wing-layout entries
 }

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")
+}

ingestion/internal/wing/backtest.go

@@ -0,0 +1,43 @@
+package wing
+
+// Sample is one backtest observation: the human-decided wing of an existing
+// page, and what the two independent opinions said about it with the wing
+// label removed.
+type Sample struct {
+	Truth      string
+	Suggested  string // classifier's wing, "" if it abstained or failed
+	Confidence float64
+	ScorerTop  string // scorer's single best wing, "" if no clear opinion
+}
+
+// Result is the policy outcome at one threshold.
+type Result struct {
+	N         int
+	Auto      int     // placed without a human
+	Correct   int     // of Auto, matching Truth
+	Coverage  float64 // Auto / N
+	Precision float64 // Correct / Auto; 0 when Auto == 0
+}
+
+// Evaluate applies the Resolver's classified-path rule (confident, and the
+// scorer agrees) to recorded samples. Eligibility is not modelled: callers
+// backtest only on wings they would allow.
+func Evaluate(samples []Sample, threshold float64) Result {
+	r := Result{N: len(samples)}
+	for _, s := range samples {
+		if s.Suggested == "" || s.Confidence < threshold || s.ScorerTop != s.Suggested {
+			continue
+		}
+		r.Auto++
+		if s.Suggested == s.Truth {
+			r.Correct++
+		}
+	}
+	if r.N > 0 {
+		r.Coverage = float64(r.Auto) / float64(r.N)
+	}
+	if r.Auto > 0 {
+		r.Precision = float64(r.Correct) / float64(r.Auto)
+	}
+	return r
+}

ingestion/internal/wing/backtest_test.go

@@ -0,0 +1,38 @@
+package wing_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/wing"
+)
+
+func TestEvaluate_PolicyAtAThreshold(t *testing.T) {
+	samples := []wing.Sample{
+		{Truth: "a", Suggested: "a", Confidence: 0.9, ScorerTop: "a"},  // auto, correct
+		{Truth: "a", Suggested: "b", Confidence: 0.9, ScorerTop: "b"},  // auto, WRONG (both models agree on a wrong wing)
+		{Truth: "a", Suggested: "a", Confidence: 0.5, ScorerTop: "a"},  // below threshold -> exception
+		{Truth: "a", Suggested: "a", Confidence: 0.95, ScorerTop: "b"}, // scorer disagrees -> exception
+		{Truth: "a", Suggested: "", Confidence: 0.99, ScorerTop: "a"},  // abstain -> exception
+	}
+	r := wing.Evaluate(samples, 0.8)
+	assert.Equal(t, 5, r.N)
+	assert.Equal(t, 2, r.Auto)
+	assert.Equal(t, 1, r.Correct)
+	assert.InDelta(t, 0.4, r.Coverage, 1e-9)
+	assert.InDelta(t, 0.5, r.Precision, 1e-9)
+}
+
+func TestEvaluate_NothingAutoHasZeroPrecisionNotNaN(t *testing.T) {
+	r := wing.Evaluate([]wing.Sample{{Truth: "a", Suggested: "a", Confidence: 0.1, ScorerTop: "a"}}, 0.8)
+	assert.Zero(t, r.Auto)
+	assert.Zero(t, r.Precision)
+	assert.Zero(t, r.Coverage)
+}
+
+func TestEvaluate_EmptyInput(t *testing.T) {
+	r := wing.Evaluate(nil, 0.8)
+	assert.Zero(t, r.N)
+	assert.Zero(t, r.Coverage)
+}

ingestion/internal/wing/bm25scorer.go

@@ -0,0 +1,85 @@
+package wing
+
+import (
+	"sort"
+	"strings"
+	"unicode"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/search"
+)
+
+const (
+	maxQueryTerms = 12
+	minTermLen    = 5
+)
+
+// BM25Scorer scores a note against each wing by running the brain's own BM25
+// search scoped to that wing. It is deliberately a different mechanism from
+// the LLM, so agreement between the two is evidence and not an echo.
+type BM25Scorer struct {
+	brainDir string
+	wings    []string
+	exclude  string
+}
+
+// NewBM25Scorer scores against wings under brainDir. exclude is a brain-
+// relative path ignored in results (the backtest sample itself); "" for none.
+func NewBM25Scorer(brainDir string, wings []string, exclude string) *BM25Scorer {
+	return &BM25Scorer{brainDir: brainDir, wings: wings, exclude: exclude}
+}
+
+// Score implements Scorer. A wing whose search fails scores 0 rather than
+// failing the note: the Resolver treats "no clear opinion" as an Exception.
+func (b *BM25Scorer) Score(text string) map[string]float64 {
+	query := strings.Join(topTerms(text), " ")
+	out := map[string]float64{}
+	if query == "" {
+		return out
+	}
+	for _, w := range b.wings {
+		hits, err := search.Query(b.brainDir, search.QueryOptions{Query: query, Wing: w, Limit: 2})
+		if err != nil {
+			continue
+		}
+		for _, h := range hits {
+			if b.exclude != "" && h.Path == b.exclude {
+				continue
+			}
+			// Hits come best-first: a wing is scored by its single best
+			// page, so a big wing cannot win on volume alone.
+			out[w] = float64(h.Score)
+			break
+		}
+	}
+	return out
+}
+
+// topTerms picks the most frequent longer words, ties broken alphabetically
+// so the query is deterministic.
+func topTerms(text string) []string {
+	if len(text) > maxNoteChars {
+		text = text[:maxNoteChars]
+	}
+	counts := map[string]int{}
+	for _, f := range strings.FieldsFunc(strings.ToLower(text), func(r rune) bool {
+		return !unicode.IsLetter(r) && !unicode.IsDigit(r)
+	}) {
+		if len([]rune(f)) >= minTermLen {
+			counts[f]++
+		}
+	}
+	terms := make([]string, 0, len(counts))
+	for t := range counts {
+		terms = append(terms, t)
+	}
+	sort.Slice(terms, func(i, j int) bool {
+		if counts[terms[i]] != counts[terms[j]] {
+			return counts[terms[i]] > counts[terms[j]]
+		}
+		return terms[i] < terms[j]
+	})
+	if len(terms) > maxQueryTerms {
+		terms = terms[:maxQueryTerms]
+	}
+	return terms
+}

ingestion/internal/wing/bm25scorer_test.go

@@ -0,0 +1,61 @@
+package wing_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/wing"
+)
+
+func writePage(t *testing.T, dir, rel, body string) {
+	t.Helper()
+	full := filepath.Join(dir, rel)
+	require.NoError(t, os.MkdirAll(filepath.Dir(full), 0o755))
+	require.NoError(t, os.WriteFile(full, []byte(body), 0o644))
+}
+
+func scorerBrain(t *testing.T) string {
+	dir := t.TempDir()
+	writePage(t, dir, "wiki/infra/facts/k3s.md", "---\ntitle: K3s cluster\n---\nkubernetes cluster nodes scheduling pods deployment\n")
+	writePage(t, dir, "wiki/finance/facts/invoice.md", "---\ntitle: Invoices\n---\ninvoice payment bookkeeping ledger reconciliation\n")
+	return dir
+}
+
+func TestBM25Scorer_RanksTheWingWhosePagesMatch(t *testing.T) {
+	s := wing.NewBM25Scorer(scorerBrain(t), []string{"infra", "finance"}, "")
+	got := s.Score("notes about kubernetes cluster scheduling and pods")
+	assert.Greater(t, got["infra"], got["finance"])
+	assert.Greater(t, got["infra"], 0.0)
+}
+
+func TestBM25Scorer_ExcludesThePageBeingClassified(t *testing.T) {
+	// A page must not vouch for its own wing when it is the backtest sample.
+	s := wing.NewBM25Scorer(scorerBrain(t), []string{"infra", "finance"}, "wiki/infra/facts/k3s.md")
+	got := s.Score("kubernetes cluster nodes scheduling pods deployment")
+	assert.Zero(t, got["infra"], "the excluded page is the only infra match")
+}
+
+func TestBM25Scorer_NoUsableTermsScoresNothing(t *testing.T) {
+	s := wing.NewBM25Scorer(scorerBrain(t), []string{"infra", "finance"}, "")
+	assert.Empty(t, s.Score("a an to of"))
+}
+
+// A big wing must not win just by having more pages that brush the query: a
+// wing is scored by its single best page, not by the sum of its top hits.
+func TestBM25Scorer_ABigWingDoesNotWinOnVolume(t *testing.T) {
+	dir := t.TempDir()
+	writePage(t, dir, "wiki/small/facts/target.md", "---\ntitle: Target\n---\nkubernetes cluster scheduling pods deployment nodes\n")
+	for i := 0; i < 8; i++ {
+		writePage(t, dir, filepath.Join("wiki/big/facts", "p"+string(rune('a'+i))+".md"),
+			"---\ntitle: Filler\n---\nkubernetes cluster scheduling mentioned in passing among bookkeeping ledger entries\n")
+	}
+	s := wing.NewBM25Scorer(dir, []string{"small", "big"}, "")
+	got := s.Score("kubernetes cluster scheduling pods deployment nodes")
+	top, ok := wing.TopWing(got)
+	assert.True(t, ok)
+	assert.Equal(t, "small", top)
+}

ingestion/internal/wing/configured.go

@@ -0,0 +1,32 @@
+package wing
+
+import (
+	"fmt"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
+)
+
+// NewConfiguredResolver builds the production Resolver for a brain: Known from
+// the wiki, Eligible from classification.yaml (a wing is auto-assignable only
+// when it classifies below Confidential, so an untagged wing never is), the
+// LLM classifier over complete, and BM25 over the known wings as the scorer.
+//
+// Known is read once. A wing created later is unknown to this Resolver until
+// the process restarts, which fails safe: notes aimed at it are parked.
+func NewConfiguredResolver(brainDir string, complete CompleteFunc, threshold float64) (*Resolver, error) {
+	known, err := KnownWings(brainDir)
+	if err != nil {
+		return nil, err
+	}
+	cls, err := classification.Load(brainDir)
+	if err != nil {
+		return nil, fmt.Errorf("load classification: %w", err)
+	}
+	return &Resolver{
+		Known:      known,
+		Eligible:   func(w string) bool { return cls.Wing(w) < classification.Confidential },
+		Classifier: NewLLMClassifier(complete),
+		Scorer:     NewBM25Scorer(brainDir, known, ""),
+		Threshold:  threshold,
+	}, nil
+}

ingestion/internal/wing/configured_test.go

@@ -0,0 +1,47 @@
+package wing_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/wing"
+)
+
+func configuredBrain(t *testing.T, classification string) string {
+	dir := t.TempDir()
+	writePage(t, dir, "wiki/homelab/facts/a.md", "x")
+	writePage(t, dir, "wiki/radar/facts/b.md", "x")
+	writePage(t, dir, "wiki/client-x/facts/c.md", "x")
+	if classification != "" {
+		writePage(t, dir, "classification.yaml", classification)
+	}
+	return dir
+}
+
+func TestNewConfiguredResolver_EligibilityComesFromClassification(t *testing.T) {
+	dir := configuredBrain(t, "wings:\n  radar: internal\n")
+	r, err := wing.NewConfiguredResolver(dir, func(context.Context, string, string) (string, error) { return "", nil }, 0.9)
+	require.NoError(t, err)
+
+	assert.ElementsMatch(t, []string{"client-x", "homelab", "radar"}, r.Known)
+	assert.True(t, r.Eligible("radar"), "tagged internal")
+	assert.True(t, r.Eligible("homelab"), "internal by built-in default")
+	assert.False(t, r.Eligible("client-x"), "an untagged wing fails safe to confidential")
+	assert.InDelta(t, 0.9, r.Threshold, 1e-9)
+}
+
+func TestNewConfiguredResolver_AMalformedClassificationFileIsAnError(t *testing.T) {
+	dir := configuredBrain(t, "wings: [not, a, map")
+	_, err := wing.NewConfiguredResolver(dir, nil, 0.9)
+	assert.Error(t, err, "a classification source that cannot be trusted must not degrade to 'everything eligible'")
+}
+
+func TestNewConfiguredResolver_AConfidentialTagIsNeverEligible(t *testing.T) {
+	dir := configuredBrain(t, "wings:\n  radar: confidential\n")
+	r, err := wing.NewConfiguredResolver(dir, nil, 0.9)
+	require.NoError(t, err)
+	assert.False(t, r.Eligible("radar"))
+}

ingestion/internal/wing/known.go

@@ -0,0 +1,46 @@
+package wing
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+)
+
+// legacyDirs are the retired wiki/{concepts,entities,sources}/ layout, not wings.
+var legacyDirs = map[string]bool{"concepts": true, "entities": true, "sources": true}
+
+// KnownWings lists wiki/<wing>/ directories that contain at least one hall
+// subdirectory, sorted. The retired layout is not a wing. A missing wiki/ is
+// an error: an unreadable brain must not look like "no wings".
+func KnownWings(brainDir string) ([]string, error) {
+	entries, err := os.ReadDir(filepath.Join(brainDir, "wiki"))
+	if err != nil {
+		return nil, fmt.Errorf("list wings: %w", err)
+	}
+	var out []string
+	for _, e := range entries {
+		if !e.IsDir() || legacyDirs[e.Name()] || !plainWingName(e.Name()) {
+			continue
+		}
+		subs, err := os.ReadDir(filepath.Join(brainDir, "wiki", e.Name()))
+		if err != nil {
+			continue
+		}
+		for _, s := range subs {
+			if s.IsDir() {
+				out = append(out, e.Name())
+				break
+			}
+		}
+	}
+	sort.Strings(out)
+	return out, nil
+}
+
+// plainWingName reports whether name is already in the canonical lower-case form
+// the pipeline writes. Anything else would make the pipeline create a different
+// wing than the one matched.
+func plainWingName(name string) bool { return brain.Sanitise(name) == name }

ingestion/internal/wing/known_test.go

@@ -0,0 +1,42 @@
+package wing_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/wing"
+)
+
+func TestKnownWings_ListsWingsWithHallsAndSkipsTheRetiredLayout(t *testing.T) {
+	dir := t.TempDir()
+	writePage(t, dir, "wiki/homelab/facts/a.md", "x")
+	writePage(t, dir, "wiki/tapir/decisions/b.md", "x")
+	writePage(t, dir, "wiki/concepts/c.md", "x")       // retired layout, a file directly under a legacy dir
+	writePage(t, dir, "wiki/sources/d.md", "x")        // retired layout
+	writePage(t, dir, "wiki/entities/e.md", "x")       // retired layout
+	writePage(t, dir, "wiki/loose-note.md", "x")       // a file, not a wing
+	writePage(t, dir, "wiki/emptywing/_index.md", "x") // a dir with no hall subdirectory
+	got, err := wing.KnownWings(dir)
+	require.NoError(t, err)
+	assert.Equal(t, []string{"homelab", "tapir"}, got)
+}
+
+func TestKnownWings_NoWikiDirIsAnError(t *testing.T) {
+	_, err := wing.KnownWings(t.TempDir())
+	assert.Error(t, err, "a brain without wiki/ must not look like a brain with no wings")
+}
+
+// Known matches case-insensitively and the pipeline writes the lower-case name,
+// so a wiki directory that is not already plain lower-case would make the
+// pipeline create a different, new wing. It is not a candidate.
+func TestKnownWings_SkipsADirectoryThatIsNotAPlainWingName(t *testing.T) {
+	dir := t.TempDir()
+	writePage(t, dir, "wiki/Radar/facts/a.md", "x")
+	writePage(t, dir, "wiki/has space/facts/a.md", "x")
+	writePage(t, dir, "wiki/ok/facts/a.md", "x")
+	got, err := wing.KnownWings(dir)
+	require.NoError(t, err)
+	assert.Equal(t, []string{"ok"}, got)
+}

ingestion/internal/wing/llmclassifier.go

@@ -0,0 +1,99 @@
+package wing
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+)
+
+// CompleteFunc is a chat completion, matching llm.Client.Complete. It must be
+// backed by a local model: note content is sent to it.
+type CompleteFunc func(ctx context.Context, system, user string) (string, error)
+
+// maxNoteChars bounds what is sent for classification; the start of a note
+// carries its subject, and a whole transcript is cost with no benefit.
+const maxNoteChars = 6000
+
+const classifySystem = `You file notes into a personal knowledge base. Pick the single wing the note belongs to, from the candidate list only.
+Answer with ONLY a JSON object: {"wing": "<name or none>", "confidence": <0..1>, "reason": "<one short sentence>"}.
+Use "none" when no candidate clearly fits. Do not invent wings.`
+
+// LLMClassifier asks a model to pick a wing.
+type LLMClassifier struct{ complete CompleteFunc }
+
+// NewLLMClassifier wraps a chat completion as a Classifier.
+func NewLLMClassifier(c CompleteFunc) *LLMClassifier { return &LLMClassifier{complete: c} }
+
+type classifyReply struct {
+	Wing       string  `json:"wing"`
+	Confidence float64 `json:"confidence"`
+	Reason     string  `json:"reason"`
+}
+
+// Classify implements Classifier. Any reply it cannot parse is an error, which
+// the Resolver turns into an Exception: an unreadable answer is not a guess.
+func (l *LLMClassifier) Classify(ctx context.Context, text string, candidates []string) (Suggestion, error) {
+	if len(text) > maxNoteChars {
+		text = text[:maxNoteChars]
+	}
+	user := "Candidate wings: " + strings.Join(candidates, ", ") + "\n\nNote:\n" + text
+	out, err := l.complete(ctx, classifySystem, user)
+	if err != nil {
+		return Suggestion{}, fmt.Errorf("classify: %w", err)
+	}
+	raw, ok := firstJSONObject(out)
+	if !ok {
+		return Suggestion{}, errors.New("classify: reply contains no JSON object")
+	}
+	var r classifyReply
+	if err := json.Unmarshal([]byte(raw), &r); err != nil {
+		return Suggestion{}, fmt.Errorf("classify: parse reply: %w", err)
+	}
+	w := strings.TrimSpace(r.Wing)
+	if strings.EqualFold(w, "none") {
+		w = ""
+	}
+	return Suggestion{Wing: w, Confidence: clamp01(r.Confidence), Reason: r.Reason}, nil
+}
+
+// firstJSONObject returns the first balanced {...} in s, ignoring braces
+// inside JSON strings, so prose or code fences around the reply are tolerated.
+func firstJSONObject(s string) (string, bool) {
+	start := strings.IndexByte(s, '{')
+	if start < 0 {
+		return "", false
+	}
+	depth, inStr, esc := 0, false, false
+	for i := start; i < len(s); i++ {
+		c := s[i]
+		switch {
+		case esc:
+			esc = false
+		case inStr && c == '\\':
+			esc = true
+		case c == '"':
+			inStr = !inStr
+		case inStr:
+		case c == '{':
+			depth++
+		case c == '}':
+			depth--
+			if depth == 0 {
+				return s[start : i+1], true
+			}
+		}
+	}
+	return "", false
+}
+
+func clamp01(f float64) float64 {
+	switch {
+	case f < 0:
+		return 0
+	case f > 1:
+		return 1
+	}
+	return f
+}

ingestion/internal/wing/llmclassifier_test.go

@@ -0,0 +1,67 @@
+package wing_test
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/wing"
+)
+
+func completes(reply string, err error) wing.CompleteFunc {
+	return func(_ context.Context, _, _ string) (string, error) { return reply, err }
+}
+
+func TestLLMClassifier_ParsesTheReply(t *testing.T) {
+	tests := []struct {
+		name    string
+		reply   string
+		want    wing.Suggestion
+		wantErr bool
+	}{
+		{"bare json", `{"wing":"tapir","confidence":0.9,"reason":"video summariser"}`, wing.Suggestion{Wing: "tapir", Confidence: 0.9, Reason: "video summariser"}, false},
+		{"json inside prose and fences", "Sure!\n```json\n{\"wing\":\"homelab\",\"confidence\":0.7,\"reason\":\"k3s\"}\n```\nDone.", wing.Suggestion{Wing: "homelab", Confidence: 0.7, Reason: "k3s"}, false},
+		{"none means abstain", `{"wing":"none","confidence":0.2,"reason":"generic"}`, wing.Suggestion{Wing: "", Confidence: 0.2, Reason: "generic"}, false},
+		{"confidence above 1 is clamped", `{"wing":"tapir","confidence":7,"reason":"x"}`, wing.Suggestion{Wing: "tapir", Confidence: 1, Reason: "x"}, false},
+		{"negative confidence is clamped", `{"wing":"tapir","confidence":-1,"reason":"x"}`, wing.Suggestion{Wing: "tapir", Confidence: 0, Reason: "x"}, false},
+		{"empty reply (a reasoning model that ran out of tokens)", ``, wing.Suggestion{}, true},
+		{"no json at all", `I think it is tapir`, wing.Suggestion{}, true},
+		{"malformed json", `{"wing":"tapir","confidence":`, wing.Suggestion{}, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			c := wing.NewLLMClassifier(completes(tt.reply, nil))
+			got, err := c.Classify(context.Background(), "note", []string{"tapir", "homelab"})
+			if tt.wantErr {
+				require.Error(t, err)
+				return
+			}
+			require.NoError(t, err)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestLLMClassifier_PropagatesTheModelError(t *testing.T) {
+	boom := errors.New("model down")
+	_, err := wing.NewLLMClassifier(completes("", boom)).Classify(context.Background(), "n", []string{"tapir"})
+	assert.ErrorIs(t, err, boom)
+}
+
+func TestLLMClassifier_PromptListsCandidatesAndBoundsTheNote(t *testing.T) {
+	var gotUser string
+	c := wing.NewLLMClassifier(func(_ context.Context, _, user string) (string, error) {
+		gotUser = user
+		return `{"wing":"tapir","confidence":0.9,"reason":"x"}`, nil
+	})
+	long := strings.Repeat("word ", 5000)
+	_, err := c.Classify(context.Background(), long, []string{"tapir", "homelab"})
+	require.NoError(t, err)
+	assert.Contains(t, gotUser, "tapir")
+	assert.Contains(t, gotUser, "homelab")
+	assert.Less(t, len(gotUser), 12000, "a whole transcript must not be sent as the classification input")
+}

ingestion/internal/wing/resolve.go

@@ -0,0 +1,176 @@
+// Package wing decides which brain wing an incoming raw note belongs to
+// without the human typing it (hyperguild#205).
+//
+// The contract is conservative: a note is placed automatically only when the
+// decision is explicit, or when two independent opinions (an LLM and a
+// deterministic scorer) agree with enough confidence on a wing that is both
+// known and eligible. Everything else is an Exception for a human to approve.
+// A wing is never created here, and a wing the caller does not mark eligible
+// (client wings, anything not deliberately tagged) is never auto-assigned.
+package wing
+
+import (
+	"context"
+	"fmt"
+	"strings"
+)
+
+// Source says how a Decision was reached.
+type Source string
+
+const (
+	Explicit   Source = "explicit"   // subfolder or frontmatter named the wing
+	Classified Source = "classified" // classifier + scorer agreed, confident
+	Exception  Source = "exception"  // needs a human
+)
+
+// Note is what the resolver sees of an incoming raw note.
+type Note struct {
+	Dir             string // first subfolder under raw/, "" when dropped at the top
+	FrontmatterWing string // `wing:` from the note's frontmatter, "" if absent
+	Text            string
+}
+
+// Suggestion is a Classifier's answer. An empty Wing means "none fits".
+type Suggestion struct {
+	Wing       string
+	Confidence float64 // 0..1
+	Reason     string
+}
+
+// Classifier proposes a wing from the candidates. Implementations must run on
+// a local model; the resolver cannot enforce that.
+type Classifier interface {
+	Classify(ctx context.Context, text string, candidates []string) (Suggestion, error)
+}
+
+// Scorer is an independent, deterministic opinion (e.g. BM25 against each
+// wing's index). Higher is better; the key is the wing name.
+type Scorer interface {
+	Score(text string) map[string]float64
+}
+
+// Decision is the outcome. For an Exception, Wing holds the proposal when
+// there was one (so a reviewer can approve it) and is empty otherwise.
+type Decision struct {
+	Wing       string
+	Source     Source
+	Confidence float64
+	Reason     string
+}
+
+// Resolver holds the policy. Known is every existing wing; Eligible reports
+// whether a known wing may be assigned automatically.
+type Resolver struct {
+	Known      []string
+	Eligible   func(wing string) bool
+	Classifier Classifier
+	Scorer     Scorer
+	Threshold  float64
+}
+
+// Resolve never returns an error: anything it cannot decide safely is an
+// Exception with the reason spelled out.
+func (r Resolver) Resolve(ctx context.Context, n Note) Decision {
+	dir := norm(n.Dir)
+	fm := norm(n.FrontmatterWing)
+	switch {
+	case dir != "" && fm != "" && dir != fm:
+		return exception("", 0, fmt.Sprintf("subfolder %q and frontmatter wing %q disagree", dir, fm))
+	case dir != "":
+		return r.explicit(dir, "subfolder")
+	case fm != "":
+		return r.explicit(fm, "frontmatter")
+	}
+	return r.classify(ctx, n)
+}
+
+func (r Resolver) explicit(w, via string) Decision {
+	if why := r.refuse(w); why != "" {
+		return exception(w, 0, fmt.Sprintf("%s names %q: %s", via, w, why))
+	}
+	return Decision{Wing: w, Source: Explicit, Confidence: 1, Reason: "named by " + via}
+}
+
+func (r Resolver) classify(ctx context.Context, n Note) Decision {
+	if r.Classifier == nil {
+		return exception("", 0, "no classifier configured")
+	}
+	s, err := r.Classifier.Classify(ctx, n.Text, r.Known)
+	if err != nil {
+		return exception("", 0, fmt.Sprintf("classifier failed: %v", err))
+	}
+	w := norm(s.Wing)
+	if w == "" {
+		return exception("", s.Confidence, "classifier found no fitting wing")
+	}
+	if why := r.refuse(w); why != "" {
+		return exception(w, s.Confidence, fmt.Sprintf("classifier proposed %q: %s", w, why))
+	}
+	if s.Confidence < r.Threshold {
+		return exception(w, s.Confidence, fmt.Sprintf("confidence %.2f below threshold %.2f", s.Confidence, r.Threshold))
+	}
+	top, ok := r.scorerTop(n.Text)
+	if !ok {
+		return exception(w, s.Confidence, "scorer has no clear opinion to cross-check against")
+	}
+	if top != w {
+		return exception(w, s.Confidence, fmt.Sprintf("classifier says %q, scorer says %q", w, top))
+	}
+	return Decision{Wing: w, Source: Classified, Confidence: s.Confidence,
+		Reason: fmt.Sprintf("classifier and scorer agree (%.2f): %s", s.Confidence, s.Reason)}
+}
+
+// refuse returns why a wing may not be auto-assigned, or "" if it may.
+func (r Resolver) refuse(w string) string {
+	if !r.known(w) {
+		return "not an existing wing (new wings are never created automatically)"
+	}
+	if r.Eligible == nil || !r.Eligible(w) {
+		return "not eligible for automatic assignment"
+	}
+	return ""
+}
+
+func (r Resolver) known(w string) bool {
+	for _, k := range r.Known {
+		if norm(k) == w {
+			return true
+		}
+	}
+	return false
+}
+
+// scorerTop returns the single best-scoring wing; a missing scorer, no scores,
+// or a tie at the top is "no clear opinion".
+func (r Resolver) scorerTop(text string) (string, bool) {
+	if r.Scorer == nil {
+		return "", false
+	}
+	return TopWing(r.Scorer.Score(text))
+}
+
+// TopWing returns the unique highest-scoring wing in scores, or false when
+// there is none or the top is tied. Shared by the Resolver and the backtest so
+// both apply the same notion of "the scorer has an opinion".
+func TopWing(scores map[string]float64) (string, bool) {
+	best, bestScore, tied := "", 0.0, false
+	for k, v := range scores {
+		switch {
+		case v > bestScore:
+			best, bestScore, tied = norm(k), v, false
+		case v == bestScore && v > 0:
+			tied = true
+		}
+	}
+	if best == "" || tied {
+		return "", false
+	}
+	return best, true
+}
+
+func exception(w string, conf float64, reason string) Decision {
+	return Decision{Wing: w, Source: Exception, Confidence: conf, Reason: reason}
+}
+
+func norm(s string) string { return strings.ToLower(strings.TrimSpace(s)) }

ingestion/internal/wing/resolve_test.go

@@ -0,0 +1,112 @@
+package wing_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/wing"
+)
+
+type fakeClassifier struct {
+	s     wing.Suggestion
+	err   error
+	calls int
+}
+
+func (f *fakeClassifier) Classify(_ context.Context, _ string, _ []string) (wing.Suggestion, error) {
+	f.calls++
+	return f.s, f.err
+}
+
+type fakeScorer map[string]float64
+
+func (f fakeScorer) Score(string) map[string]float64 { return f }
+
+// eligibleExcept allows every name except the listed ones. Being permissive on
+// names it has never heard of means only the "known wing" check can stop an
+// invented wing, so a test of that check cannot pass by accident.
+func eligibleExcept(names ...string) func(string) bool {
+	deny := map[string]bool{}
+	for _, n := range names {
+		deny[n] = true
+	}
+	return func(w string) bool { return !deny[w] }
+}
+
+func newResolver(c wing.Classifier, s wing.Scorer) wing.Resolver {
+	return wing.Resolver{
+		Known:      []string{"homelab", "hyperguild", "tapir", "rikatillsammans"},
+		Eligible:   eligibleExcept("rikatillsammans"), // a client wing: known, never auto
+		Classifier: c,
+		Scorer:     s,
+		Threshold:  0.8,
+	}
+}
+
+func TestResolve_ExplicitSignal(t *testing.T) {
+	tests := []struct {
+		name     string
+		note     wing.Note
+		want     wing.Source
+		wantWing string
+	}{
+		{"subfolder of a known eligible wing", wing.Note{Dir: "homelab"}, wing.Explicit, "homelab"},
+		{"frontmatter of a known eligible wing", wing.Note{FrontmatterWing: "tapir"}, wing.Explicit, "tapir"},
+		{"subfolder and frontmatter agree", wing.Note{Dir: "tapir", FrontmatterWing: "tapir"}, wing.Explicit, "tapir"},
+		{"subfolder and frontmatter disagree", wing.Note{Dir: "tapir", FrontmatterWing: "homelab"}, wing.Exception, ""},
+		{"unknown wing is never created", wing.Note{Dir: "hoemlab"}, wing.Exception, "hoemlab"},
+		{"known but not eligible (client) wing is never auto-assigned", wing.Note{Dir: "rikatillsammans"}, wing.Exception, "rikatillsammans"},
+		{"subfolder is case-insensitive", wing.Note{Dir: "HomeLab"}, wing.Explicit, "homelab"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			c := &fakeClassifier{}
+			d := newResolver(c, fakeScorer{}).Resolve(context.Background(), tt.note)
+			assert.Equal(t, tt.want, d.Source)
+			assert.Equal(t, tt.wantWing, d.Wing)
+			assert.Zero(t, c.calls, "an explicit signal must not spend an LLM call")
+			assert.NotEmpty(t, d.Reason)
+		})
+	}
+}
+
+func TestResolve_Classified(t *testing.T) {
+	tests := []struct {
+		name     string
+		sugg     wing.Suggestion
+		err      error
+		scores   fakeScorer
+		want     wing.Source
+		wantWing string
+	}{
+		{"confident and scorer agrees", wing.Suggestion{Wing: "tapir", Confidence: 0.9}, nil, fakeScorer{"tapir": 3, "homelab": 1}, wing.Classified, "tapir"},
+		{"confidence exactly at threshold passes", wing.Suggestion{Wing: "tapir", Confidence: 0.8}, nil, fakeScorer{"tapir": 3}, wing.Classified, "tapir"},
+		{"below threshold is an exception, proposal kept", wing.Suggestion{Wing: "tapir", Confidence: 0.79}, nil, fakeScorer{"tapir": 3}, wing.Exception, "tapir"},
+		{"scorer disagrees", wing.Suggestion{Wing: "tapir", Confidence: 0.95}, nil, fakeScorer{"homelab": 5, "tapir": 1}, wing.Exception, "tapir"},
+		{"scorer has no opinion also needs review", wing.Suggestion{Wing: "tapir", Confidence: 0.95}, nil, fakeScorer{}, wing.Exception, "tapir"},
+		{"classifier proposes a client wing", wing.Suggestion{Wing: "rikatillsammans", Confidence: 0.99}, nil, fakeScorer{"rikatillsammans": 9}, wing.Exception, "rikatillsammans"},
+		{"classifier invents a wing", wing.Suggestion{Wing: "brand-new-wing", Confidence: 0.99}, nil, fakeScorer{"brand-new-wing": 9}, wing.Exception, "brand-new-wing"},
+		{"classifier abstains", wing.Suggestion{Wing: "", Confidence: 0}, nil, fakeScorer{"tapir": 3}, wing.Exception, ""},
+		{"classifier error", wing.Suggestion{}, errors.New("llm down"), fakeScorer{"tapir": 3}, wing.Exception, ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			c := &fakeClassifier{s: tt.sugg, err: tt.err}
+			d := newResolver(c, tt.scores).Resolve(context.Background(), wing.Note{Text: "some note"})
+			assert.Equal(t, tt.want, d.Source)
+			assert.Equal(t, tt.wantWing, d.Wing)
+			assert.NotEmpty(t, d.Reason, "every decision says why, so a spot-check can judge it")
+			assert.Equal(t, 1, c.calls)
+		})
+	}
+}
+
+func TestResolve_NilDependenciesFailClosed(t *testing.T) {
+	r := wing.Resolver{Known: []string{"tapir"}, Eligible: eligibleExcept(), Threshold: 0.8}
+	d := r.Resolve(context.Background(), wing.Note{Text: "x"})
+	require.Equal(t, wing.Exception, d.Source, "no classifier configured must route to review, not panic or guess")
+}