webveil 0.1.0 → 0.2.0

package/README.md

@@ -13,33 +13,261 @@ works perfectly well non-anonymously (direct egress).
 webveil is a pnpm workspace monorepo. The **core** (`search()` / `fetch()`) is plain,
 framework-agnostic. Two thin frontends wrap that same core:
 
-- **[`webveil`](packages/webveil)** — an [incur](https://github.com/wevm/incur)-based
+- **[`webveil`](packages/webveil)**, an [incur](https://github.com/wevm/incur)-based
   **CLI + MCP server** (`--mcp`, skills, `--llms`, TOON output). Pi-agnostic; usable by any
   agent (pi via pi-mcp-adapter, Claude Code, Cursor, Codex, bash). Has a `webveil` bin.
-- **[`pi-webveil`](packages/pi-webveil)** — a **pi extension** registering `web_search` and
+- **[`pi-webveil`](packages/pi-webveil)**, a **pi extension** registering `web_search` and
   `web_fetch` tools that call the core in-process. A drop-in replacement for Ollama's tools
   (same names), which is the original motivation. Depends on `webveil` via `workspace:*`.
 
+## Quick start
+
+webveil needs a **backend** to get results from. The zero-config default is a local
+**SearXNG** at `http://127.0.0.1:8080` on `direct` egress (non-anonymous). There is
+**no** zero-setup + anonymous + real-web-results option in the ecosystem, see
+[`work/notes/ideas/default-backend-policy-account-vs-origin.md`](work/notes/ideas/default-backend-policy-account-vs-origin.md);
+SearXNG (you run it) is the closest, `tavily-compat` (needs an account/key) is the other.
+
+### Run SearXNG (matches the default with no config)
+
+```sh
+# Docker: the container binds 8080 internally; map host 8080 -> container 8080
+# so it matches webveil's default baseUrl exactly.
+docker run -d --name searxng -p 8080:8080 searxng/searxng
+```
+
+Then `webveil search "…"` / `web_fetch` work with no config.
+
+> **Port gotcha (you WILL hit this):** SearXNG's default port depends on how you install
+> it. A bare-metal / pip / source install defaults to **8888** (`settings.yml`
+> `server.port: 8888`). The Docker image binds **8080** internally regardless (its
+> entrypoint forces `0.0.0.0:8080`). SearXNG's own docs suggest `docker run … -p 8888:8080`
+> (host 8888 → container 8080). webveil's default expects **8080**. If your instance is on
+> any other port, point webveil at it:
+>
+> ```sh
+> export WEBVEIL_BASE_URL=http://127.0.0.1:8888   # or wherever your instance listens
+> ```
+>
+> or set `baseUrl` in `webveil.json` (see config seam below).
+
+### Other SearXNG install options
+
+webveil needs something to point `baseUrl` at: an **HTTP `host:port`**, or (script install)
+the **Unix socket** itself. How you get one:
+
+- **Docker (above)**, binds a real TCP port directly; simplest if you only need webveil.
+- **Install script as a background service** (`sudo -H ./utils/searxng.sh install all`,
+  see <https://docs.searxng.org/admin/installation-scripts.html>), sets SearXNG up as a
+  systemd/uWSGI service. **Gotcha:** by default this listens on a **Unix socket**
+  (`socket = /usr/local/searxng/run/socket`), NOT a TCP port. And, crucially, that default
+  socket speaks the **native uwsgi protocol, NOT HTTP** (`socket = …`, not `http-socket =
+  …`), so even a `curl --unix-socket … http://localhost/` returns HTTP 000. webveil's
+  `unix:` baseUrl speaks **HTTP over a unix socket** via undici, so it CANNOT reach that
+  default uwsgi socket directly. Three ways to reach the install-script instance:
+  - **Point webveil straight at an HTTP unix socket** (no proxy, no extra process), once the
+    socket actually speaks HTTP. The install-script default does NOT, so first make uWSGI
+    serve HTTP on the socket: in the generated `.ini`, replace
+    `socket = /usr/local/searxng/run/socket` with
+    `http-socket = /usr/local/searxng/run/socket` (HTTP over the socket instead of the
+    uwsgi protocol). THEN point webveil at it with a `unix:` URL naming the socket file:
+    ```sh
+    export WEBVEIL_BASE_URL=unix:/usr/local/searxng/run/socket
+    ```
+    webveil dials the socket directly over undici (`Agent({connect:{socketPath}})`, no
+    extra dependency) and issues its normal `/search?...&format=json` request. The grammar
+    is `unix:<socketPath>[:<httpPath>]`: the socket file path, then an OPTIONAL `:` +
+    base path (mount point) the SearXNG app lives under (defaults to `/`, so the example
+    above requests `/search`; a non-root mount is `unix:/usr/local/searxng/run/socket:/searxng`).
+    (`unix:` works against ANY HTTP-on-a-unix-socket server, e.g. a Caddy/nginx upstream
+    bound to a socket; the uwsgi-vs-`http-socket` distinction above is the SearXNG-specific
+    catch.)
+    **Egress must be `direct`** for this: a Unix socket is inherently local, so combining a
+    `unix:` baseUrl with `egress=http`/`socks5` fails loud (proxying a local hop is fake
+    anonymity, see "Where does anonymity live?" below; proxy SearXNG's `outgoing.proxies`
+    instead and keep webveil `direct`).
+  - **Front it with a reverse proxy** (this is what the SearXNG docs' nginx/apache step is
+    for, it bridges HTTP-on-a-port to the uWSGI socket, serving BOTH the browser UI and
+    webveil). **Any HTTP server works**, the docs say so explicitly; **Caddy is fine** and
+    a good pick if you already run it. Plain Caddy `reverse_proxy` speaks **HTTP** to its
+    upstream, so point it at an `http-socket` (see below) or a TCP `http-socket`:
+    ```caddy
+    searxng.example.com {
+        reverse_proxy unix//usr/local/searxng/run/socket   # plain reverse_proxy = HTTP, so the socket must be http-socket = (not the uwsgi socket =)
+    }
+    ```
+    Then point webveil at the Caddy address. (Set SearXNG's `server.base_url` in
+    `settings.yml` to match, and keep the limiter in mind, see below.) If you want a Caddy
+    frontend AND webveil-direct, the simplest path is ONE `http-socket` that both consume
+    (Caddy's HTTP `reverse_proxy` and webveil's `unix:` both speak HTTP to it); you only
+    need the uwsgi `socket = ` form if Caddy uses an explicit uwsgi transport.
+  - **Or make uWSGI listen on a TCP port** instead of the socket: in the generated
+    `.ini`, replace `socket = …/run/socket` with `http-socket = 127.0.0.1:8888`, then point
+    webveil at `http://127.0.0.1:8888`. Good when you want ONLY webveil (no public web UI /
+    TLS).
+
+> **You will also need to enable the JSON API and (for a local instance) disable the
+> limiter.** A fresh script install ships with `server.limiter: true` and often no `json`
+> output format, so webveil gets `429 TOO MANY REQUESTS` or an HTML page. In SearXNG's
+> `settings.yml` set `server.limiter: false` + `server.public_instance: false` (safe for a
+> LOCAL, socket-only instance, NOT internet-exposed) and add `json` under `search.formats:`
+> (`[html, json]`), then restart uWSGI. This applies to EVERY option above, it is a
+> SearXNG-side requirement, not a webveil one.
+
+Full SearXNG install options (Docker, Compose, script, bare-metal): the official docs at
+<https://docs.searxng.org/admin/installation.html>. Install topology + the
+uwsgi-vs-`http-socket`, limiter, and reverse-proxy details captured in
+[`work/notes/findings/searxng-install-topology.md`](work/notes/findings/searxng-install-topology.md)
+and
+[`work/notes/findings/searxng-script-socket-is-uwsgi-not-http.md`](work/notes/findings/searxng-script-socket-is-uwsgi-not-http.md).
+
+### Where does anonymity live? (read before turning on egress)
+
+**webveil's egress only anonymizes webveil's OWN outbound hop** (webveil → backend, and
+`web_fetch` → the target URL). It does NOT anonymize what a backend does next. This has a
+load-bearing consequence for SearXNG:
+
+- A **local** SearXNG makes its actual search-engine requests (→ Google/Bing/…) from
+  **its own process, on your machine, with your real IP**. That hop is OUTSIDE webveil's
+  egress. So setting `WEBVEIL_EGRESS=socks5` while `baseUrl` is `127.0.0.1` does **NOT**
+  make your searches anonymous, webveil would just be proxying a pointless localhost call,
+  while SearXNG crawls the web from your real IP. That is **false confidence**, the worst
+  outcome.
+- **webveil refuses this combo (fail-loud):** a non-`direct` egress (`http`/`socks5`) with
+  a **loopback `baseUrl`** is rejected with an error, rather than silently giving you fake
+  anonymity. (A *remote* SearXNG over SOCKS is legitimate and allowed, the guard keys on
+  loopback specifically.)
+
+So the correct setups:
+
+| Goal | webveil egress | backend | Who anonymizes the web hop |
+| --- | --- | --- | --- |
+| Local SearXNG, anonymous searches | `direct` | local SearXNG | **SearXNG itself**, set its `outgoing.proxies` (Tor/SOCKS) in `settings.yml` |
+| Remote SearXNG, hide your IP from it | `socks5` | the **remote** SearXNG url | webveil's hop (Mullvad/Tor) |
+| Anonymous `web_fetch` of arbitrary URLs | `socks5` | (any) | webveil's hop |
+| Non-anonymous everyday use | `direct` | local SearXNG | nobody (honest) |
+
+Rule of thumb: **proxy the hop that actually reaches the public internet.** For a
+self-hosted SearXNG that hop is SearXNG's, so the proxy goes on SearXNG
+(`outgoing.proxies`), and webveil stays `direct`. webveil's `socks5` mode is for *remote*
+backends and for `web_fetch`. See
+[`work/notes/findings/webveil-anonymity-boundary.md`](work/notes/findings/webveil-anonymity-boundary.md).
+
 ## How it works (seams)
 
-- **core** — the framework-agnostic `search(query, opts)` and `fetch(url, opts)` functions.
+- **core**, the framework-agnostic `search(query, opts)` and `fetch(url, opts)` functions.
   Both frontends call the same core.
-- **backend seam** — where results/content come from: `searxng` (keyless self-hosted
+- **backend seam**, where results/content come from: `searxng` (keyless self-hosted
   metasearch), `tavily-compat` (a generic Tavily-shaped `/search` + `/extract`), and
   `custom` (a local command via a JSON stdin/stdout contract). The backend is handed a
   proxied `http` helper so it cannot bypass egress.
-- **egress seam** — how outbound HTTP leaves the machine: `direct`, `http` (undici
+- **egress seam**, how outbound HTTP leaves the machine: `direct`, `http` (undici
   `ProxyAgent`), or `socks5` (Tor `127.0.0.1:9050`, Mullvad `10.64.0.1:1080`). SOCKS5 is
   the mode that matters for anonymity. Fail-loud if a configured proxy cannot be built.
-- **config seam** — per-folder resolution: env > nearest `.pi/webveil.json` walking up from
-  cwd > global `~/.pi/agent/webveil.json` > defaults. Per folder = per account/egress.
-- **extractor seam** — `urlToMarkdown` via `distilly/fetch` by default, injected with
+  **Egress is per-request and scoped to webveil ONLY**, it is NOT a system-wide proxy. It
+  governs webveil's own search/fetch traffic (and the `fetch` it injects into distilly),
+  and nothing else: your shell, `git push`, the browser, and the OS are untouched. So
+  webveil on `socks5` does NOT route your `git push` through the proxy. See
+  [Anonymous egress](#anonymous-egress-mullvad--tor) and
+  [`work/notes/findings/mullvad-socks5-egress-mechanics.md`](work/notes/findings/mullvad-socks5-egress-mechanics.md).
+- **config seam**, per-folder resolution: env > nearest `webveil.json` walking up from
+  cwd > global `$XDG_CONFIG_HOME/webveil/config.json` (default
+  `~/.config/webveil/config.json`) > defaults. Per folder = per account/egress. The
+  project file is a frontend-neutral `webveil.json` read identically by the CLI and the
+  pi extension. See [`docs/adr/0002`](docs/adr/0002-config-file-location-neutral-webveil-json.md).
+- **extractor seam**, `urlToMarkdown` via `distilly/fetch` by default, injected with
   webveil's egress-bound `fetch`; a backend's own `/extract` (Tavily-compat) may override
   it. Owns the context-friendly markdown + size presets (`s`/`m`/`l`/`f`). See
   [`docs/adr/0001`](docs/adr/0001-extractor-uses-distilly-fetch-with-injected-egress.md).
-- **security** — an SSRF guard lives in the egress fetch, so it covers distilly's
+- **security**, an SSRF guard lives in the egress fetch, so it covers distilly's
   rule-rewritten requests too.
 
+## Anonymous egress (Mullvad / Tor)
+
+By default webveil uses `direct` egress (your real IP, non-anonymous). Anonymity is
+**opt-in**: it is enabled ONLY when you set it in config/env. webveil never auto-enables a
+proxy (silent anonymity would be a footgun in the other direction).
+
+Enable SOCKS5 egress for webveil:
+
+```sh
+export WEBVEIL_EGRESS=socks5
+export WEBVEIL_EGRESS_URL=socks5://10.64.0.1:1080     # Mullvad
+# or socks5://127.0.0.1:9050                          # Tor
+```
+
+or per folder in `webveil.json`:
+
+```json
+{ "egress": { "mode": "socks5", "url": "socks5://10.64.0.1:1080" } }
+```
+
+### Two layers keep your `git push` (and everything else) off the proxy
+
+A common worry: "if I route through Mullvad, will my `git push` to GitHub leak under the
+VPN exit IP?" With webveil, **no**, for two independent reasons:
+
+1. **webveil's egress is per-request and webveil-only.** It applies the SOCKS5 dispatcher
+   inside its own search/fetch code; it does not install a system proxy. `git`, your shell,
+   and the OS are never touched. webveil on `socks5` proxies webveil's traffic and nothing
+   else.
+2. **You configure split routing** (below) so that even at the OS level, only the proxy IP
+   goes through the tunnel.
+
+### Mullvad: use the SOCKS5 proxy WITHOUT tunnelling all your traffic
+
+Mullvad's SOCKS5 proxy at `10.64.0.1:1080` **only exists while a Mullvad WireGuard tunnel
+is up** (it is reachable only through the tunnel). The trick is to keep the tunnel up but
+tell WireGuard NOT to route your normal traffic through it, only the proxy IP. Add this to
+your Mullvad WireGuard `.conf` (`[Interface]` section):
+
+```ini
+Table = off
+PostUp  = ip -4 route add 10.64.0.1/32 dev %i; ip -4 route add 10.124.0.0/22 dev %i
+PreDown = ip -4 route delete 10.64.0.1/32 dev %i; ip -4 route delete 10.124.0.0/22 dev %i
+```
+
+`Table = off` stops WireGuard from grabbing the default route; the manual routes send ONLY
+Mullvad's SOCKS5 proxy IPs through the tunnel (`10.124.0.0/22` is the multihop range).
+Result: webveil's SOCKS5 requests exit via Mullvad; all other traffic (git, browser, OS)
+uses your normal ISP connection. (Simpler alternative: leave WireGuard's routing alone and
+rely on layer 1, but split routing is the belt-and-braces version.)
+
+Verify the proxy works: `curl https://ipv4.am.i.mullvad.net --socks5-hostname 10.64.0.1`
+should return a Mullvad exit IP; a plain `curl https://am.i.mullvad.net` should return your
+real IP (proving only the proxy is tunnelled).
+
+### "Different exit identity for webveil than for the rest of the machine"
+
+If you want webveil to exit somewhere different from your system, you have options, but be
+clear on what is and isn't possible (see
+[`work/notes/findings/mullvad-socks5-egress-mechanics.md`](work/notes/findings/mullvad-socks5-egress-mechanics.md)):
+
+- **Different exit LOCATION, same account (easy).** Point webveil at a specific multihop
+  SOCKS5 host so it exits elsewhere than your tunnel's entry:
+  `WEBVEIL_EGRESS_URL=socks5://us-nyc-wg-socks5-001.relays.mullvad.net:1080`. Your tunnel
+  enters where your Mullvad app is connected; webveil's traffic exits in NYC. Same Mullvad
+  account, unlinkable-by-location.
+- **Two DIFFERENT Mullvad ACCOUNTS at once (hard, not a webveil feature).** Mullvad's
+  SOCKS5 proxy is a property of the ONE active WireGuard tunnel, which is tied to ONE
+  account's key. SOCKS5 multihop changes exit location, NOT account. To run account A
+  system-wide AND account B for webveil simultaneously, you must isolate them at the OS
+  level: run webveil inside its own network namespace / VM / container that has its own
+  WireGuard tunnel on account B, while the host runs account A. That is infrastructure work
+  outside webveil. For most people, "don't link my searches to my git" is already solved by
+  split routing above (searches exit via Mullvad, git stays on your real IP, not correlated
+  by exit IP), without needing a second account.
+
+### Tor
+
+`WEBVEIL_EGRESS_URL=socks5://127.0.0.1:9050` with the Tor daemon running. Same per-request,
+webveil-only scoping applies.
+
+> **Caveat:** webveil's `socks5` mode is NOT a whole-machine VPN. Do not assume enabling it
+> anonymizes anything other than webveil. Conversely, a system-wide full-tunnel VPN under
+> your logged-in identity is the thing that CAN deanonymize a `git push`; webveil's scoped
+> egress deliberately avoids that.
+
 ## License
 
 AGPL-3.0-or-later. webveil depends on `distilly` (MIT, the local HTML-to-markdown
@@ -62,7 +290,7 @@ a promise); `LOC` is the actual line count of the built file.
 | src/cli.ts (incur frontend)        |  106 |    ~80 |
 | src/core/search.ts                 |  104 |    ~90 |
 | src/core/fetch.ts                  |  132 |    ~90 |
-| src/core/config.ts                 |  106 |    ~80 |
+| src/core/config.ts                 |  128 |    ~80 |
 | src/core/egress.ts                 |  106 |    ~70 |
 | src/core/http.ts                   |   62 |    ~60 |
 | src/core/extract.ts                |   82 |    ~60 |
@@ -72,7 +300,7 @@ a promise); `LOC` is the actual line count of the built file.
 | src/core/backends/searxng.ts       |   70 |    ~90 |
 | src/core/backends/tavily-compat.ts |  156 |    ~90 |
 | src/core/backends/custom.ts        |  159 |    ~70 |
-| **subtotal**                       | 1408 |        |
+| **subtotal**                       | 1430 |        |
 
 ### `packages/pi-webveil` (pi extension frontend)
 
@@ -80,7 +308,7 @@ a promise); `LOC` is the actual line count of the built file.
 | ------------ | --: | -----: |
 | src/index.ts | 168 |    ~90 |
 
-**Total own source: 1576 LOC** (excluding deps).
+**Total own source: 1598 LOC** (excluding deps).
 
 > Reality vs. target: several modules currently exceed their `CONTEXT.md` ceilings (notably
 > `tavily-compat.ts`, `custom.ts`, `pi-webveil/src/index.ts`), and two built modules

package/dist/core/baseurl.d.ts

@@ -0,0 +1,42 @@
+import { type Dispatcher } from 'undici';
+/** A parsed Unix-socket baseUrl: the socket file path + the app's base path. */
+export interface UnixBaseUrl {
+    socketPath: string;
+    /** The app's base path (mount point); the backend appends `search` to it. */
+    httpPath: string;
+}
+/** Is this resolved `baseUrl` a Unix-domain-socket form (`unix:…`)? */
+export declare function isUnixBaseUrl(baseUrl: string): boolean;
+/**
+ * Parse a `unix:<socketPath>[:<httpPath>]` baseUrl into `{socketPath, httpPath}`.
+ * Splits on the FIRST `:` after the `unix:` scheme (socket paths conventionally
+ * carry no colon); an absent/empty `<httpPath>` defaults to `/`.
+ *
+ * Throws if the socket path is empty (there is nothing to connect to).
+ */
+export declare function parseUnixBaseUrl(baseUrl: string): UnixBaseUrl;
+/**
+ * The result of resolving a `baseUrl` for the BACKEND hop: the (possibly
+ * rewritten) HTTP base the backend builds its request URL on, plus an OPTIONAL
+ * undici `Dispatcher` to carry that hop. For a normal TCP baseUrl the dispatcher
+ * is `undefined` (the caller uses the config-wide egress dispatcher); for a
+ * `unix:` baseUrl it is a socket-bound `Agent` and the base is a synthetic
+ * `http://localhost<httpPath>`.
+ */
+export interface BackendTransport {
+    baseUrl: string;
+    dispatcher?: Dispatcher;
+}
+/**
+ * Resolve a `baseUrl` into a backend-hop transport. For a `unix:` baseUrl this
+ * builds a socket-bound `Agent({connect:{socketPath}})` and a synthetic
+ * `http://localhost<httpPath>` base (the URL host is irrelevant to routing — the
+ * socket decides — and only becomes the `Host` header). For any other baseUrl it
+ * returns the baseUrl unchanged with NO dispatcher (the caller keeps using the
+ * shared config-wide egress dispatcher).
+ *
+ * NOTE: this is the BACKEND-hop transport only. It is never bound into the
+ * shared egress dispatcher, so `web_fetch`/SSRF egress is unaffected.
+ */
+export declare function resolveBackendTransport(baseUrl: string): BackendTransport;
+//# sourceMappingURL=baseurl.d.ts.map

package/dist/core/baseurl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseurl.d.ts","sourceRoot":"","sources":["../../src/core/baseurl.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAQ,KAAK,UAAU,EAAC,MAAM,QAAQ,CAAC;AAK9C,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAgB7D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,UAAU,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAQzE"}

package/dist/core/baseurl.js

@@ -0,0 +1,79 @@
+// baseUrl transport parsing — the small, transport-AWARE helper that classifies
+// a resolved `baseUrl` into either a normal TCP HTTP base or a Unix-domain-socket
+// form, and (for the socket form) rewrites it into a synthetic `http://localhost`
+// base that the transport-UNAWARE backends can build their request URL on top of.
+//
+// WHY THIS LIVES HERE (and not in egress.ts): the egress dispatcher
+// (`buildDispatcher`) is built ONCE from config and SHARED by both the backend
+// hop (search.ts) AND the arbitrary-public-URL fetch (fetch.ts). Binding a socket
+// `Agent` into that shared dispatcher would route every `web_fetch` into the
+// SearXNG socket. So the socket transport is scoped to the BACKEND `baseUrl` hop
+// only: search.ts asks this helper to translate the baseUrl, gets back a real
+// `http://localhost…` base (which the searxng backend's `new URL('search', base)`
+// still works on, unchanged) plus the per-hop socket `Agent`, and leaves the
+// fetch/SSRF egress path untouched.
+//
+// GRAMMAR (recorded decision, see the task's done record):
+//   unix:<socketPath>[:<httpPath>]
+//     - `<socketPath>`: the absolute path to the uWSGI Unix domain socket
+//       (e.g. /usr/local/searxng/run/socket). Must not contain a `:` (the parse
+//       splits on the FIRST `:` after the `unix:` scheme; conventional socket
+//       paths never contain a colon).
+//     - `<httpPath>`: OPTIONAL base path the SearXNG app is mounted under,
+//       defaulting to `/`. It is the SAME thing the TCP `baseUrl` encodes as its
+//       path: the backend appends `search` to it (`new URL('search', base + '/')`),
+//       so the install default is just `unix:/usr/local/searxng/run/socket` (the
+//       backend then requests `/search`). A non-root mount is `…/socket:/searxng`.
+//   A raw `unix:…` string is NOT a valid base for `new URL('search', …)`, so this
+//   translation MUST run BEFORE the backend builds its URL.
+import { Agent } from 'undici';
+/** The `unix:` scheme prefix this helper recognizes on a `baseUrl`. */
+const UNIX_PREFIX = 'unix:';
+/** Is this resolved `baseUrl` a Unix-domain-socket form (`unix:…`)? */
+export function isUnixBaseUrl(baseUrl) {
+    return baseUrl.startsWith(UNIX_PREFIX);
+}
+/**
+ * Parse a `unix:<socketPath>[:<httpPath>]` baseUrl into `{socketPath, httpPath}`.
+ * Splits on the FIRST `:` after the `unix:` scheme (socket paths conventionally
+ * carry no colon); an absent/empty `<httpPath>` defaults to `/`.
+ *
+ * Throws if the socket path is empty (there is nothing to connect to).
+ */
+export function parseUnixBaseUrl(baseUrl) {
+    const rest = baseUrl.slice(UNIX_PREFIX.length);
+    const sep = rest.indexOf(':');
+    const socketPath = sep === -1 ? rest : rest.slice(0, sep);
+    const rawHttpPath = sep === -1 ? '' : rest.slice(sep + 1);
+    if (!socketPath)
+        throw new Error(`webveil: malformed unix baseUrl ${JSON.stringify(baseUrl)} — ` +
+            `expected unix:<socketPath>[:<httpPath>] with a non-empty socket path`);
+    const httpPath = rawHttpPath
+        ? rawHttpPath.startsWith('/')
+            ? rawHttpPath
+            : '/' + rawHttpPath
+        : '/';
+    return { socketPath, httpPath };
+}
+/**
+ * Resolve a `baseUrl` into a backend-hop transport. For a `unix:` baseUrl this
+ * builds a socket-bound `Agent({connect:{socketPath}})` and a synthetic
+ * `http://localhost<httpPath>` base (the URL host is irrelevant to routing — the
+ * socket decides — and only becomes the `Host` header). For any other baseUrl it
+ * returns the baseUrl unchanged with NO dispatcher (the caller keeps using the
+ * shared config-wide egress dispatcher).
+ *
+ * NOTE: this is the BACKEND-hop transport only. It is never bound into the
+ * shared egress dispatcher, so `web_fetch`/SSRF egress is unaffected.
+ */
+export function resolveBackendTransport(baseUrl) {
+    if (!isUnixBaseUrl(baseUrl))
+        return { baseUrl };
+    const { socketPath, httpPath } = parseUnixBaseUrl(baseUrl);
+    const dispatcher = new Agent({ connect: { socketPath } });
+    return {
+        baseUrl: `http://localhost${httpPath === '/' ? '' : httpPath}`,
+        dispatcher,
+    };
+}
+//# sourceMappingURL=baseurl.js.map

package/dist/core/baseurl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseurl.js","sourceRoot":"","sources":["../../src/core/baseurl.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,kFAAkF;AAClF,kFAAkF;AAClF,kFAAkF;AAClF,EAAE;AACF,oEAAoE;AACpE,+EAA+E;AAC/E,kFAAkF;AAClF,6EAA6E;AAC7E,iFAAiF;AACjF,8EAA8E;AAC9E,kFAAkF;AAClF,6EAA6E;AAC7E,oCAAoC;AACpC,EAAE;AACF,2DAA2D;AAC3D,mCAAmC;AACnC,0EAA0E;AAC1E,gFAAgF;AAChF,8EAA8E;AAC9E,sCAAsC;AACtC,2EAA2E;AAC3E,iFAAiF;AACjF,oFAAoF;AACpF,iFAAiF;AACjF,mFAAmF;AACnF,kFAAkF;AAClF,4DAA4D;AAE5D,OAAO,EAAC,KAAK,EAAkB,MAAM,QAAQ,CAAC;AAE9C,uEAAuE;AACvE,MAAM,WAAW,GAAG,OAAO,CAAC;AAS5B,uEAAuE;AACvE,MAAM,UAAU,aAAa,CAAC,OAAe;IAC5C,OAAO,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC/C,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,UAAU,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC1D,MAAM,WAAW,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAC1D,IAAI,CAAC,UAAU;QACd,MAAM,IAAI,KAAK,CACd,mCAAmC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK;YAC9D,sEAAsE,CACvE,CAAC;IACH,MAAM,QAAQ,GAAG,WAAW;QAC3B,CAAC,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC;YAC5B,CAAC,CAAC,WAAW;YACb,CAAC,CAAC,GAAG,GAAG,WAAW;QACpB,CAAC,CAAC,GAAG,CAAC;IACP,OAAO,EAAC,UAAU,EAAE,QAAQ,EAAC,CAAC;AAC/B,CAAC;AAeD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACtD,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;QAAE,OAAO,EAAC,OAAO,EAAC,CAAC;IAC9C,MAAM,EAAC,UAAU,EAAE,QAAQ,EAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACzD,MAAM,UAAU,GAAG,IAAI,KAAK,CAAC,EAAC,OAAO,EAAE,EAAC,UAAU,EAAC,EAAC,CAAC,CAAC;IACtD,OAAO;QACN,OAAO,EAAE,mBAAmB,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE;QAC9D,UAAU;KACV,CAAC;AACH,CAAC"}

package/dist/core/config.d.ts

@@ -25,9 +25,14 @@ export interface ResolveOptions {
     cwd?: string;
     /** Environment to read overrides from. Defaults to process.env. */
     env?: Record<string, string | undefined>;
+    /** Home directory for the XDG fallback. Defaults to os.homedir(). */
+    homeDir?: string;
     /**
-     * Path to the global config file. Defaults to ~/.pi/agent/webveil.json.
-     * Tests point this at a temp dir to isolate the real home directory.
+     * Path to the global config file. When given it WINS outright and the XDG
+     * resolution is skipped. Tests point this at a temp dir to isolate the real
+     * home directory. When absent, the global file resolves to
+     * $XDG_CONFIG_HOME/webveil/config.json, falling back to
+     * <homeDir>/.config/webveil/config.json.
      */
     globalPath?: string;
 }

package/dist/core/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAUA,2DAA2D;AAC3D,MAAM,MAAM,MAAM,GACf;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAC,GAChB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,GAC3B;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,CAAC;AAEjC,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAE9C,+DAA+D;AAC/D,MAAM,WAAW,MAAM;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;CACrB;AAED,mEAAmE;AACnE,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC9B,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AA+CD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,MAAM,CAalE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAcA,2DAA2D;AAC3D,MAAM,MAAM,MAAM,GACf;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAC,GAChB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,GAC3B;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,CAAC;AAEjC,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAE9C,+DAA+D;AAC/D,MAAM,WAAW,MAAM;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;CACrB;AAED,mEAAmE;AACnE,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC9B,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AA4DD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,MAAM,CAalE"}

package/dist/core/config.js

@@ -1,8 +1,12 @@
 // config seam — per-folder resolution. Precedence (highest wins):
-//   env > nearest .pi/webveil.json (walking up from cwd) > global
-//   ~/.pi/agent/webveil.json > defaults.
+//   env > nearest webveil.json (walking up from cwd) > global
+//   $XDG_CONFIG_HOME/webveil/config.json (~/.config/webveil/config.json) >
+//   defaults.
 // "Per folder = per account/egress." Each layer is a partial; later (lower)
-// layers fill gaps the higher layers leave.
+// layers fill gaps the higher layers leave. The project file is a
+// frontend-neutral `webveil.json` (no `.pi/`): both the pi-agnostic CLI and the
+// pi extension resolve the same name, so a project is configured the same way
+// regardless of which frontend reads it. See docs/adr/0002.
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, parse } from 'node:path';
@@ -12,7 +16,7 @@ const DEFAULTS = {
     egress: { mode: 'direct' },
     fetchSize: 'm',
 };
-const PROJECT_FILE = join('.pi', 'webveil.json');
+const PROJECT_FILE = 'webveil.json';
 function readJson(path) {
     let text;
     try {
@@ -23,7 +27,7 @@ function readJson(path) {
     }
     return JSON.parse(text);
 }
-/** The nearest `.pi/webveil.json` walking up from `cwd` (first found wins). */
+/** The nearest `webveil.json` walking up from `cwd` (first found wins). */
 function readProjectChain(cwd) {
     let dir = cwd;
     const { root } = parse(dir);
@@ -53,6 +57,15 @@ function readEnv(env) {
         layer.egress = { mode, url: env.WEBVEIL_EGRESS_URL ?? '' };
     return layer;
 }
+/**
+ * The global config path, XDG-style: `$XDG_CONFIG_HOME/webveil/config.json`,
+ * falling back to `<homeDir>/.config/webveil/config.json` when XDG_CONFIG_HOME
+ * is unset. (`options.globalPath`, when given, bypasses this entirely.)
+ */
+function resolveGlobalPath(env, homeDir = homedir()) {
+    const base = env.XDG_CONFIG_HOME || join(homeDir, '.config');
+    return join(base, 'webveil', 'config.json');
+}
 /**
  * Resolve the effective config. Higher-precedence layers override lower ones,
  * key by key: env > project chain > global file > defaults.
@@ -60,7 +73,7 @@ function readEnv(env) {
 export function resolveConfig(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const env = options.env ?? process.env;
-    const globalPath = options.globalPath ?? join(homedir(), '.pi', 'agent', 'webveil.json');
+    const globalPath = options.globalPath ?? resolveGlobalPath(env, options.homeDir);
     const layers = [
         DEFAULTS,
         readJson(globalPath) ?? {},

package/dist/core/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"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"}

package/dist/core/egress.d.ts

@@ -6,6 +6,22 @@ export declare class EgressError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * Fail-loud guard for the false-confidence combo: a `unix:` (local-socket)
+ * backend `baseUrl` configured with a NON-direct egress (`http`/`socks5`). A
+ * Unix socket is inherently local, so proxying that hop is the same fake-
+ * anonymity footgun as proxying a loopback TCP baseUrl: webveil would route a
+ * pointless local call through the proxy while the backend (SearXNG) crawls the
+ * public web from the real IP, OUTSIDE webveil's egress. Refuse it and point at
+ * the real fix.
+ *
+ * OVERLAP SEAM (recorded): this is the loopback false-confidence family. The
+ * sibling task `fail-loud-on-proxied-loopback-backend` adds the broader guard
+ * for loopback TCP baseUrls (127.0.0.0/8, ::1, localhost). When it lands, fold
+ * THIS `unix:`-is-loopback-equivalent case into that single guard instead of
+ * keeping a parallel check here.
+ */
+export declare function assertEgressAllowsBaseUrl(cfg: Config): void;
 /**
  * Build the undici Dispatcher for the config's egress mode:
  *   - direct → undefined (undici uses its default, un-proxied transport)

package/dist/core/egress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"egress.d.ts","sourceRoot":"","sources":["../../src/core/egress.ts"],"names":[],"mappings":"AAQA,OAAO,EAAC,KAAK,EAAE,KAAK,UAAU,EAAE,UAAU,EAAuB,MAAM,QAAQ,CAAC;AAEhF,OAAO,KAAK,EAAC,MAAM,EAAS,MAAM,aAAa,CAAC;AAEhD,8EAA8E;AAC9E,qBAAa,WAAY,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAIxD;AAqBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAiCnE;AAED,uEAAuE;AACvE,MAAM,MAAM,WAAW,GAAG,OAAO,UAAU,CAAC,KAAK,CAAC;AAElD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAU1D;AAED,YAAY,EAAC,UAAU,EAAC,CAAC;AACzB,OAAO,EAAC,KAAK,EAAE,UAAU,EAAC,CAAC"}
+{"version":3,"file":"egress.d.ts","sourceRoot":"","sources":["../../src/core/egress.ts"],"names":[],"mappings":"AAQA,OAAO,EAAC,KAAK,EAAE,KAAK,UAAU,EAAE,UAAU,EAAuB,MAAM,QAAQ,CAAC;AAEhF,OAAO,KAAK,EAAC,MAAM,EAAS,MAAM,aAAa,CAAC;AAGhD,8EAA8E;AAC9E,qBAAa,WAAY,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAIxD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU3D;AAqBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAiCnE;AAED,uEAAuE;AACvE,MAAM,MAAM,WAAW,GAAG,OAAO,UAAU,CAAC,KAAK,CAAC;AAElD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAU1D;AAED,YAAY,EAAC,UAAU,EAAC,CAAC;AACzB,OAAO,EAAC,KAAK,EAAE,UAAU,EAAC,CAAC"}

package/dist/core/egress.js

@@ -7,6 +7,7 @@
 // fall back to un-proxied (direct) transport.
 import { Agent, ProxyAgent, fetch as undiciFetch } from 'undici';
 import { socksDispatcher } from 'fetch-socks';
+import { isUnixBaseUrl } from './baseurl.js';
 /** Thrown when a configured egress proxy cannot be built. Never swallowed. */
 export class EgressError extends Error {
     constructor(message, options) {
@@ -14,6 +15,31 @@ export class EgressError extends Error {
         this.name = 'EgressError';
     }
 }
+/**
+ * Fail-loud guard for the false-confidence combo: a `unix:` (local-socket)
+ * backend `baseUrl` configured with a NON-direct egress (`http`/`socks5`). A
+ * Unix socket is inherently local, so proxying that hop is the same fake-
+ * anonymity footgun as proxying a loopback TCP baseUrl: webveil would route a
+ * pointless local call through the proxy while the backend (SearXNG) crawls the
+ * public web from the real IP, OUTSIDE webveil's egress. Refuse it and point at
+ * the real fix.
+ *
+ * OVERLAP SEAM (recorded): this is the loopback false-confidence family. The
+ * sibling task `fail-loud-on-proxied-loopback-backend` adds the broader guard
+ * for loopback TCP baseUrls (127.0.0.0/8, ::1, localhost). When it lands, fold
+ * THIS `unix:`-is-loopback-equivalent case into that single guard instead of
+ * keeping a parallel check here.
+ */
+export function assertEgressAllowsBaseUrl(cfg) {
+    if (cfg.egress.mode === 'direct')
+        return;
+    if (isUnixBaseUrl(cfg.baseUrl))
+        throw new EgressError(`egress ${cfg.egress.mode}: a unix: (local socket) baseUrl cannot be ` +
+            `proxied — it is inherently local, so proxying it gives fake ` +
+            `anonymity (SearXNG still crawls the web from your real IP). Set ` +
+            `egress=direct and proxy the backend itself (SearXNG's ` +
+            `outgoing.proxies), or use a remote backend.`);
+}
 function socksFromUrl(raw) {
     const url = new URL(raw); // throws on a malformed proxy URL → fail loud
     const protocol = url.protocol.replace(':', '');

package/dist/core/egress.js.map

@@ -1 +1 @@
-{"version":3,"file":"egress.js","sourceRoot":"","sources":["../../src/core/egress.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,EAAE;AACF,uEAAuE;AACvE,4EAA4E;AAC5E,8CAA8C;AAE9C,OAAO,EAAC,KAAK,EAAmB,UAAU,EAAE,KAAK,IAAI,WAAW,EAAC,MAAM,QAAQ,CAAC;AAChF,OAAO,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AAG5C,8EAA8E;AAC9E,MAAM,OAAO,WAAY,SAAQ,KAAK;IACrC,YAAY,OAAe,EAAE,OAA2B;QACvD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC3B,CAAC;CACD;AAED,SAAS,YAAY,CAAC,GAAW;IAChC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,8CAA8C;IACxE,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC/C,IAAI,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,SAAS;QAC1E,MAAM,IAAI,WAAW,CACpB,sDAAsD,GAAG,EAAE,CAC3D,CAAC;IACH,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC;QACxD,MAAM,IAAI,WAAW,CAAC,uCAAuC,GAAG,EAAE,CAAC,CAAC;IACrE,OAAO,eAAe,CAAC;QACtB,IAAI,EAAE,CAAC;QACP,IAAI,EAAE,GAAG,CAAC,QAAQ;QAClB,IAAI;QACJ,MAAM,EAAE,GAAG,CAAC,QAAQ,IAAI,SAAS;QACjC,QAAQ,EAAE,GAAG,CAAC,QAAQ,IAAI,SAAS;KACnC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IAC1C,MAAM,MAAM,GAAW,GAAG,CAAC,MAAM,CAAC;IAClC,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,QAAQ;YACZ,OAAO,SAAS,CAAC;QAClB,KAAK,MAAM;YACV,IAAI,CAAC;gBACJ,IAAI,CAAC,MAAM,CAAC,GAAG;oBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;gBACtD,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACnC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,MAAM,IAAI,WAAW,CACpB,0CAA0C,MAAM,CAAC,GAAG,EAAE,EACtD,EAAC,KAAK,EAAC,CACP,CAAC;YACH,CAAC;QACF,KAAK,QAAQ;YACZ,IAAI,CAAC;gBACJ,IAAI,CAAC,MAAM,CAAC,GAAG;oBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;gBACtD,OAAO,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,IAAI,KAAK,YAAY,WAAW;oBAAE,MAAM,KAAK,CAAC;gBAC9C,MAAM,IAAI,WAAW,CACpB,4CAA4C,MAAM,CAAC,GAAG,EAAE,EACxD,EAAC,KAAK,EAAC,CACP,CAAC;YACH,CAAC;QACF,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,UAAU,GAAU,MAAM,CAAC;YACjC,MAAM,IAAI,WAAW,CACpB,wBAAwB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CACpD,CAAC;QACH,CAAC;IACF,CAAC;AACF,CAAC;AAKD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC5C,MAAM,UAAU,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACxC,OAAO,CAAC,CAAC,KAAwB,EAAE,IAAkB,EAAE,EAAE,CACxD,WAAW,CACV,KAAc,EACd;QACC,GAAI,CAAC,IAAI,IAAI,EAAE,CAA6B;QAC5C,UAAU;KACD,CACV,CAAgB,CAAC;AACpB,CAAC;AAGD,OAAO,EAAC,KAAK,EAAE,UAAU,EAAC,CAAC"}
+{"version":3,"file":"egress.js","sourceRoot":"","sources":["../../src/core/egress.ts"],"names":[],"mappings":"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"}

package/dist/core/search.d.ts

@@ -1,5 +1,6 @@
 import type { Config, ResolveOptions } from './config.js';
 import type { Dispatcher } from './egress.js';
+import type { BackendTransport } from './baseurl.js';
 import type { Http, SearchOptions, SearchResult } from './backends/types.js';
 /**
  * Collaborators, seamed so the core is testable WITHOUT real config files,
@@ -11,6 +12,8 @@ import type { Http, SearchOptions, SearchResult } from './backends/types.js';
 export interface SearchDeps {
     resolveConfig?: (options?: ResolveOptions) => Config;
     buildDispatcher?: (config: Config) => Dispatcher | undefined;
+    assertEgressAllowsBaseUrl?: (config: Config) => void;
+    resolveBackendTransport?: (baseUrl: string) => BackendTransport;
     createHttp?: (dispatcher: Dispatcher | undefined) => Http;
     getBackend?: (name: string, config: Config) => {
         search: (query: string, http: Http, options?: SearchOptions) => Promise<SearchResult[]>;

package/dist/core/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/core/search.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAC,MAAM,EAAE,cAAc,EAAC,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,aAAa,CAAC;AAG5C,OAAO,KAAK,EAAC,IAAI,EAAE,aAAa,EAAE,YAAY,EAAC,MAAM,qBAAqB,CAAC;AAU3E;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IAC1B,aAAa,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,cAAc,KAAK,MAAM,CAAC;IACrD,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,CAAC;IAC7D,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,KAAK,IAAI,CAAC;IAC1D,UAAU,CAAC,EAAE,CACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,KACV;QACJ,MAAM,EAAE,CACP,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,aAAa,KACnB,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;KAC7B,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,WAAW,iBAAkB,SAAQ,aAAa,EAAE,cAAc;CAAG;AAc3E;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,iBAAsB,EAC/B,IAAI,GAAE,UAAe,GACnB,OAAO,CAAC,YAAY,EAAE,CAAC,CAwBzB"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/core/search.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAC,MAAM,EAAE,cAAc,EAAC,MAAM,aAAa,CAAC;AAKxD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,cAAc,CAAC;AAGnD,OAAO,KAAK,EAAC,IAAI,EAAE,aAAa,EAAE,YAAY,EAAC,MAAM,qBAAqB,CAAC;AAU3E;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IAC1B,aAAa,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,cAAc,KAAK,MAAM,CAAC;IACrD,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,CAAC;IAC7D,yBAAyB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACrD,uBAAuB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,gBAAgB,CAAC;IAChE,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,KAAK,IAAI,CAAC;IAC1D,UAAU,CAAC,EAAE,CACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,KACV;QACJ,MAAM,EAAE,CACP,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,aAAa,KACnB,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;KAC7B,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,WAAW,iBAAkB,SAAQ,aAAa,EAAE,cAAc;CAAG;AAc3E;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,iBAAsB,EAC/B,IAAI,GAAE,UAAe,GACnB,OAAO,CAAC,YAAY,EAAE,CAAC,CAqDzB"}

package/dist/core/search.js

@@ -11,7 +11,8 @@
 // and bypass the configured egress. A configured-but-unbuildable proxy throws at
 // buildDispatcher (fail-loud), never silently un-proxied.
 import { resolveConfig as defaultResolveConfig } from './config.js';
-import { buildDispatcher as defaultBuildDispatcher } from './egress.js';
+import { buildDispatcher as defaultBuildDispatcher, assertEgressAllowsBaseUrl as defaultAssertEgressAllowsBaseUrl, } from './egress.js';
+import { resolveBackendTransport as defaultResolveBackendTransport } from './baseurl.js';
 import { createHttp as defaultCreateHttp } from './http.js';
 import { getBackend as defaultGetBackend } from './backends/registry.js';
 /**
@@ -44,6 +45,8 @@ function dedup(results) {
 export async function search(query, options = {}, deps = {}) {
     const resolveConfig = deps.resolveConfig ?? defaultResolveConfig;
     const buildDispatcher = deps.buildDispatcher ?? defaultBuildDispatcher;
+    const assertEgressAllowsBaseUrl = deps.assertEgressAllowsBaseUrl ?? defaultAssertEgressAllowsBaseUrl;
+    const resolveBackendTransport = deps.resolveBackendTransport ?? defaultResolveBackendTransport;
     const createHttp = deps.createHttp ?? defaultCreateHttp;
     const getBackend = deps.getBackend ?? defaultGetBackend;
     const config = resolveConfig({
@@ -51,14 +54,38 @@ export async function search(query, options = {}, deps = {}) {
         env: options.env,
         globalPath: options.globalPath,
     });
-    // Build the dispatcher FIRST: a configured-but-unbuildable proxy throws here,
-    // before any network access (never an un-proxied request).
-    const dispatcher = buildDispatcher(config);
+    // Fail loud on the false-confidence combo (a local `unix:` socket baseUrl
+    // behind a proxy egress) BEFORE any transport is built.
+    assertEgressAllowsBaseUrl(config);
+    // Resolve the BACKEND-hop transport. For a normal TCP baseUrl this is a no-op
+    // (no per-hop dispatcher); for a `unix:` baseUrl it yields a socket-bound
+    // `Agent` and a synthetic `http://localhost…` base the backend builds on. The
+    // socket transport is scoped to THIS hop only and is NEVER bound into the
+    // shared config-wide egress dispatcher, so `web_fetch` egress is unaffected.
+    const transport = resolveBackendTransport(config.baseUrl);
+    // Build the egress dispatcher FIRST: a configured-but-unbuildable proxy throws
+    // here, before any network access (never an un-proxied request). For a socket
+    // baseUrl the per-hop socket dispatcher overrides the (direct/undefined) one.
+    const dispatcher = transport.dispatcher ?? buildDispatcher(config);
     const http = createHttp(dispatcher);
-    const backend = getBackend(config.backend, config);
+    // The backend stays transport-unaware: it receives a config whose baseUrl is
+    // always a real `http(s):` base (the `unix:` form is rewritten away here).
+    const backendConfig = transport.baseUrl === config.baseUrl
+        ? config
+        : { ...config, baseUrl: transport.baseUrl };
+    const backend = getBackend(backendConfig.backend, backendConfig);
     // Hand the backend ONLY the proxied helper (no maxResults: dedup happens
     // here, over the full set, so the clamp below is over UNIQUE results).
-    const raw = await backend.search(query, http, { signal: options.signal });
+    let raw;
+    try {
+        raw = await backend.search(query, http, { signal: options.signal });
+    }
+    finally {
+        // Best-effort close of the per-hop socket Agent (the shared egress
+        // dispatcher, owned by config, is NOT touched here).
+        if (transport.dispatcher)
+            void transport.dispatcher.close();
+    }
     const maxResults = options.maxResults ?? DEFAULT_MAX_RESULTS;
     return dedup(raw).slice(0, maxResults);
 }

package/dist/core/search.js.map

@@ -1 +1 @@
-{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/core/search.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,uEAAuE;AACvE,8EAA8E;AAC9E,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,2EAA2E;AAC3E,EAAE;AACF,uEAAuE;AACvE,+EAA+E;AAC/E,iFAAiF;AACjF,0DAA0D;AAE1D,OAAO,EAAC,aAAa,IAAI,oBAAoB,EAAC,MAAM,aAAa,CAAC;AAElE,OAAO,EAAC,eAAe,IAAI,sBAAsB,EAAC,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAC,UAAU,IAAI,iBAAiB,EAAC,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAC,UAAU,IAAI,iBAAiB,EAAC,MAAM,wBAAwB,CAAC;AAGvE;;;;;GAKG;AACH,MAAM,mBAAmB,GAAG,EAAE,CAAC;AA4B/B,sEAAsE;AACtE,SAAS,KAAK,CAAC,OAAuB;IACrC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;YAAE,SAAS;QAC9B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAChB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACb,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC3B,KAAa,EACb,UAA6B,EAAE,EAC/B,OAAmB,EAAE;IAErB,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,oBAAoB,CAAC;IACjE,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,sBAAsB,CAAC;IACvE,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,iBAAiB,CAAC;IACxD,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,iBAAiB,CAAC;IAExD,MAAM,MAAM,GAAG,aAAa,CAAC;QAC5B,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,UAAU,EAAE,OAAO,CAAC,UAAU;KAC9B,CAAC,CAAC;IAEH,8EAA8E;IAC9E,2DAA2D;IAC3D,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IAEpC,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACnD,yEAAyE;IACzE,uEAAuE;IACvE,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,EAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAC,CAAC,CAAC;IAExE,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;IAC7D,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;AACxC,CAAC"}
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/core/search.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webveil",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Anonymous-capable, self-hosted, account-free web search and fetch for agents. CLI + MCP (built on incur), pi-agnostic. Swappable backend and egress (direct, http proxy, socks5/Tor).",
   "license": "AGPL-3.0-or-later",
   "keywords": [

package/src/core/baseurl.ts

@@ -0,0 +1,104 @@
+// baseUrl transport parsing — the small, transport-AWARE helper that classifies
+// a resolved `baseUrl` into either a normal TCP HTTP base or a Unix-domain-socket
+// form, and (for the socket form) rewrites it into a synthetic `http://localhost`
+// base that the transport-UNAWARE backends can build their request URL on top of.
+//
+// WHY THIS LIVES HERE (and not in egress.ts): the egress dispatcher
+// (`buildDispatcher`) is built ONCE from config and SHARED by both the backend
+// hop (search.ts) AND the arbitrary-public-URL fetch (fetch.ts). Binding a socket
+// `Agent` into that shared dispatcher would route every `web_fetch` into the
+// SearXNG socket. So the socket transport is scoped to the BACKEND `baseUrl` hop
+// only: search.ts asks this helper to translate the baseUrl, gets back a real
+// `http://localhost…` base (which the searxng backend's `new URL('search', base)`
+// still works on, unchanged) plus the per-hop socket `Agent`, and leaves the
+// fetch/SSRF egress path untouched.
+//
+// GRAMMAR (recorded decision, see the task's done record):
+//   unix:<socketPath>[:<httpPath>]
+//     - `<socketPath>`: the absolute path to the uWSGI Unix domain socket
+//       (e.g. /usr/local/searxng/run/socket). Must not contain a `:` (the parse
+//       splits on the FIRST `:` after the `unix:` scheme; conventional socket
+//       paths never contain a colon).
+//     - `<httpPath>`: OPTIONAL base path the SearXNG app is mounted under,
+//       defaulting to `/`. It is the SAME thing the TCP `baseUrl` encodes as its
+//       path: the backend appends `search` to it (`new URL('search', base + '/')`),
+//       so the install default is just `unix:/usr/local/searxng/run/socket` (the
+//       backend then requests `/search`). A non-root mount is `…/socket:/searxng`.
+//   A raw `unix:…` string is NOT a valid base for `new URL('search', …)`, so this
+//   translation MUST run BEFORE the backend builds its URL.
+
+import {Agent, type Dispatcher} from 'undici';
+
+/** The `unix:` scheme prefix this helper recognizes on a `baseUrl`. */
+const UNIX_PREFIX = 'unix:';
+
+/** A parsed Unix-socket baseUrl: the socket file path + the app's base path. */
+export interface UnixBaseUrl {
+	socketPath: string;
+	/** The app's base path (mount point); the backend appends `search` to it. */
+	httpPath: string;
+}
+
+/** Is this resolved `baseUrl` a Unix-domain-socket form (`unix:…`)? */
+export function isUnixBaseUrl(baseUrl: string): boolean {
+	return baseUrl.startsWith(UNIX_PREFIX);
+}
+
+/**
+ * Parse a `unix:<socketPath>[:<httpPath>]` baseUrl into `{socketPath, httpPath}`.
+ * Splits on the FIRST `:` after the `unix:` scheme (socket paths conventionally
+ * carry no colon); an absent/empty `<httpPath>` defaults to `/`.
+ *
+ * Throws if the socket path is empty (there is nothing to connect to).
+ */
+export function parseUnixBaseUrl(baseUrl: string): UnixBaseUrl {
+	const rest = baseUrl.slice(UNIX_PREFIX.length);
+	const sep = rest.indexOf(':');
+	const socketPath = sep === -1 ? rest : rest.slice(0, sep);
+	const rawHttpPath = sep === -1 ? '' : rest.slice(sep + 1);
+	if (!socketPath)
+		throw new Error(
+			`webveil: malformed unix baseUrl ${JSON.stringify(baseUrl)} — ` +
+				`expected unix:<socketPath>[:<httpPath>] with a non-empty socket path`,
+		);
+	const httpPath = rawHttpPath
+		? rawHttpPath.startsWith('/')
+			? rawHttpPath
+			: '/' + rawHttpPath
+		: '/';
+	return {socketPath, httpPath};
+}
+
+/**
+ * The result of resolving a `baseUrl` for the BACKEND hop: the (possibly
+ * rewritten) HTTP base the backend builds its request URL on, plus an OPTIONAL
+ * undici `Dispatcher` to carry that hop. For a normal TCP baseUrl the dispatcher
+ * is `undefined` (the caller uses the config-wide egress dispatcher); for a
+ * `unix:` baseUrl it is a socket-bound `Agent` and the base is a synthetic
+ * `http://localhost<httpPath>`.
+ */
+export interface BackendTransport {
+	baseUrl: string;
+	dispatcher?: Dispatcher;
+}
+
+/**
+ * Resolve a `baseUrl` into a backend-hop transport. For a `unix:` baseUrl this
+ * builds a socket-bound `Agent({connect:{socketPath}})` and a synthetic
+ * `http://localhost<httpPath>` base (the URL host is irrelevant to routing — the
+ * socket decides — and only becomes the `Host` header). For any other baseUrl it
+ * returns the baseUrl unchanged with NO dispatcher (the caller keeps using the
+ * shared config-wide egress dispatcher).
+ *
+ * NOTE: this is the BACKEND-hop transport only. It is never bound into the
+ * shared egress dispatcher, so `web_fetch`/SSRF egress is unaffected.
+ */
+export function resolveBackendTransport(baseUrl: string): BackendTransport {
+	if (!isUnixBaseUrl(baseUrl)) return {baseUrl};
+	const {socketPath, httpPath} = parseUnixBaseUrl(baseUrl);
+	const dispatcher = new Agent({connect: {socketPath}});
+	return {
+		baseUrl: `http://localhost${httpPath === '/' ? '' : httpPath}`,
+		dispatcher,
+	};
+}

package/src/core/config.ts

@@ -1,8 +1,12 @@
 // config seam — per-folder resolution. Precedence (highest wins):
-//   env > nearest .pi/webveil.json (walking up from cwd) > global
-//   ~/.pi/agent/webveil.json > defaults.
+//   env > nearest webveil.json (walking up from cwd) > global
+//   $XDG_CONFIG_HOME/webveil/config.json (~/.config/webveil/config.json) >
+//   defaults.
 // "Per folder = per account/egress." Each layer is a partial; later (lower)
-// layers fill gaps the higher layers leave.
+// layers fill gaps the higher layers leave. The project file is a
+// frontend-neutral `webveil.json` (no `.pi/`): both the pi-agnostic CLI and the
+// pi extension resolve the same name, so a project is configured the same way
+// regardless of which frontend reads it. See docs/adr/0002.
 
 import {readFileSync} from 'node:fs';
 import {homedir} from 'node:os';
@@ -34,9 +38,14 @@ export interface ResolveOptions {
 	cwd?: string;
 	/** Environment to read overrides from. Defaults to process.env. */
 	env?: Record<string, string | undefined>;
+	/** Home directory for the XDG fallback. Defaults to os.homedir(). */
+	homeDir?: string;
 	/**
-	 * Path to the global config file. Defaults to ~/.pi/agent/webveil.json.
-	 * Tests point this at a temp dir to isolate the real home directory.
+	 * Path to the global config file. When given it WINS outright and the XDG
+	 * resolution is skipped. Tests point this at a temp dir to isolate the real
+	 * home directory. When absent, the global file resolves to
+	 * $XDG_CONFIG_HOME/webveil/config.json, falling back to
+	 * <homeDir>/.config/webveil/config.json.
 	 */
 	globalPath?: string;
 }
@@ -48,7 +57,7 @@ const DEFAULTS: Config = {
 	fetchSize: 'm',
 };
 
-const PROJECT_FILE = join('.pi', 'webveil.json');
+const PROJECT_FILE = 'webveil.json';
 
 function readJson(path: string): PartialConfig | undefined {
 	let text: string;
@@ -60,7 +69,7 @@ function readJson(path: string): PartialConfig | undefined {
 	return JSON.parse(text) as PartialConfig;
 }
 
-/** The nearest `.pi/webveil.json` walking up from `cwd` (first found wins). */
+/** The nearest `webveil.json` walking up from `cwd` (first found wins). */
 function readProjectChain(cwd: string): PartialConfig | undefined {
 	let dir = cwd;
 	const {root} = parse(dir);
@@ -86,6 +95,19 @@ function readEnv(env: Record<string, string | undefined>): PartialConfig {
 	return layer;
 }
 
+/**
+ * The global config path, XDG-style: `$XDG_CONFIG_HOME/webveil/config.json`,
+ * falling back to `<homeDir>/.config/webveil/config.json` when XDG_CONFIG_HOME
+ * is unset. (`options.globalPath`, when given, bypasses this entirely.)
+ */
+function resolveGlobalPath(
+	env: Record<string, string | undefined>,
+	homeDir = homedir(),
+): string {
+	const base = env.XDG_CONFIG_HOME || join(homeDir, '.config');
+	return join(base, 'webveil', 'config.json');
+}
+
 /**
  * Resolve the effective config. Higher-precedence layers override lower ones,
  * key by key: env > project chain > global file > defaults.
@@ -94,7 +116,7 @@ export function resolveConfig(options: ResolveOptions = {}): Config {
 	const cwd = options.cwd ?? process.cwd();
 	const env = options.env ?? process.env;
 	const globalPath =
-		options.globalPath ?? join(homedir(), '.pi', 'agent', 'webveil.json');
+		options.globalPath ?? resolveGlobalPath(env, options.homeDir);
 
 	const layers: PartialConfig[] = [
 		DEFAULTS,

package/src/core/egress.ts

@@ -9,6 +9,7 @@
 import {Agent, type Dispatcher, ProxyAgent, fetch as undiciFetch} from 'undici';
 import {socksDispatcher} from 'fetch-socks';
 import type {Config, Egress} from './config.js';
+import {isUnixBaseUrl} from './baseurl.js';
 
 /** Thrown when a configured egress proxy cannot be built. Never swallowed. */
 export class EgressError extends Error {
@@ -18,6 +19,33 @@ export class EgressError extends Error {
 	}
 }
 
+/**
+ * Fail-loud guard for the false-confidence combo: a `unix:` (local-socket)
+ * backend `baseUrl` configured with a NON-direct egress (`http`/`socks5`). A
+ * Unix socket is inherently local, so proxying that hop is the same fake-
+ * anonymity footgun as proxying a loopback TCP baseUrl: webveil would route a
+ * pointless local call through the proxy while the backend (SearXNG) crawls the
+ * public web from the real IP, OUTSIDE webveil's egress. Refuse it and point at
+ * the real fix.
+ *
+ * OVERLAP SEAM (recorded): this is the loopback false-confidence family. The
+ * sibling task `fail-loud-on-proxied-loopback-backend` adds the broader guard
+ * for loopback TCP baseUrls (127.0.0.0/8, ::1, localhost). When it lands, fold
+ * THIS `unix:`-is-loopback-equivalent case into that single guard instead of
+ * keeping a parallel check here.
+ */
+export function assertEgressAllowsBaseUrl(cfg: Config): void {
+	if (cfg.egress.mode === 'direct') return;
+	if (isUnixBaseUrl(cfg.baseUrl))
+		throw new EgressError(
+			`egress ${cfg.egress.mode}: a unix: (local socket) baseUrl cannot be ` +
+				`proxied — it is inherently local, so proxying it gives fake ` +
+				`anonymity (SearXNG still crawls the web from your real IP). Set ` +
+				`egress=direct and proxy the backend itself (SearXNG's ` +
+				`outgoing.proxies), or use a remote backend.`,
+		);
+}
+
 function socksFromUrl(raw: string): Dispatcher {
 	const url = new URL(raw); // throws on a malformed proxy URL → fail loud
 	const protocol = url.protocol.replace(':', '');

package/src/core/search.ts

@@ -13,8 +13,13 @@
 
 import {resolveConfig as defaultResolveConfig} from './config.js';
 import type {Config, ResolveOptions} from './config.js';
-import {buildDispatcher as defaultBuildDispatcher} from './egress.js';
+import {
+	buildDispatcher as defaultBuildDispatcher,
+	assertEgressAllowsBaseUrl as defaultAssertEgressAllowsBaseUrl,
+} from './egress.js';
 import type {Dispatcher} from './egress.js';
+import {resolveBackendTransport as defaultResolveBackendTransport} from './baseurl.js';
+import type {BackendTransport} from './baseurl.js';
 import {createHttp as defaultCreateHttp} from './http.js';
 import {getBackend as defaultGetBackend} from './backends/registry.js';
 import type {Http, SearchOptions, SearchResult} from './backends/types.js';
@@ -37,6 +42,8 @@ const DEFAULT_MAX_RESULTS = 10;
 export interface SearchDeps {
 	resolveConfig?: (options?: ResolveOptions) => Config;
 	buildDispatcher?: (config: Config) => Dispatcher | undefined;
+	assertEgressAllowsBaseUrl?: (config: Config) => void;
+	resolveBackendTransport?: (baseUrl: string) => BackendTransport;
 	createHttp?: (dispatcher: Dispatcher | undefined) => Http;
 	getBackend?: (
 		name: string,
@@ -80,6 +87,10 @@ export async function search(
 ): Promise<SearchResult[]> {
 	const resolveConfig = deps.resolveConfig ?? defaultResolveConfig;
 	const buildDispatcher = deps.buildDispatcher ?? defaultBuildDispatcher;
+	const assertEgressAllowsBaseUrl =
+		deps.assertEgressAllowsBaseUrl ?? defaultAssertEgressAllowsBaseUrl;
+	const resolveBackendTransport =
+		deps.resolveBackendTransport ?? defaultResolveBackendTransport;
 	const createHttp = deps.createHttp ?? defaultCreateHttp;
 	const getBackend = deps.getBackend ?? defaultGetBackend;
 
@@ -89,15 +100,40 @@ export async function search(
 		globalPath: options.globalPath,
 	});
 
-	// Build the dispatcher FIRST: a configured-but-unbuildable proxy throws here,
-	// before any network access (never an un-proxied request).
-	const dispatcher = buildDispatcher(config);
+	// Fail loud on the false-confidence combo (a local `unix:` socket baseUrl
+	// behind a proxy egress) BEFORE any transport is built.
+	assertEgressAllowsBaseUrl(config);
+
+	// Resolve the BACKEND-hop transport. For a normal TCP baseUrl this is a no-op
+	// (no per-hop dispatcher); for a `unix:` baseUrl it yields a socket-bound
+	// `Agent` and a synthetic `http://localhost…` base the backend builds on. The
+	// socket transport is scoped to THIS hop only and is NEVER bound into the
+	// shared config-wide egress dispatcher, so `web_fetch` egress is unaffected.
+	const transport = resolveBackendTransport(config.baseUrl);
+
+	// Build the egress dispatcher FIRST: a configured-but-unbuildable proxy throws
+	// here, before any network access (never an un-proxied request). For a socket
+	// baseUrl the per-hop socket dispatcher overrides the (direct/undefined) one.
+	const dispatcher = transport.dispatcher ?? buildDispatcher(config);
 	const http = createHttp(dispatcher);
 
-	const backend = getBackend(config.backend, config);
+	// The backend stays transport-unaware: it receives a config whose baseUrl is
+	// always a real `http(s):` base (the `unix:` form is rewritten away here).
+	const backendConfig: Config =
+		transport.baseUrl === config.baseUrl
+			? config
+			: {...config, baseUrl: transport.baseUrl};
+	const backend = getBackend(backendConfig.backend, backendConfig);
 	// Hand the backend ONLY the proxied helper (no maxResults: dedup happens
 	// here, over the full set, so the clamp below is over UNIQUE results).
-	const raw = await backend.search(query, http, {signal: options.signal});
+	let raw: SearchResult[];
+	try {
+		raw = await backend.search(query, http, {signal: options.signal});
+	} finally {
+		// Best-effort close of the per-hop socket Agent (the shared egress
+		// dispatcher, owned by config, is NOT touched here).
+		if (transport.dispatcher) void transport.dispatcher.close();
+	}
 
 	const maxResults = options.maxResults ?? DEFAULT_MAX_RESULTS;
 	return dedup(raw).slice(0, maxResults);