swarph-cli 0.24.0__tar.gz → 0.26.0__tar.gz

{swarph_cli-0.24.0/src/swarph_cli.egg-info → swarph_cli-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.24.0
+Version: 0.26.0
 Summary: The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, session `import`, and a stranded-session `watchdog`.
 Author: Pierre Samson, Claude Opus
 License: MIT

{swarph_cli-0.24.0 → swarph_cli-0.26.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.24.0"
+version = "0.26.0"
 description = "The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, session `import`, and a stranded-session `watchdog`."
 readme = "README.md"
 license = { text = "MIT" }

{swarph_cli-0.24.0 → swarph_cli-0.26.0}/src/swarph_cli/__init__.py

@@ -16,6 +16,6 @@ The architecture splits CLI from substrate so:
 
 from __future__ import annotations
 
-__version__ = "0.24.0"
+__version__ = "0.26.0"
 
 __all__ = ["__version__"]

{swarph_cli-0.24.0 → swarph_cli-0.26.0}/src/swarph_cli/commands/brain_ask.py

@@ -15,6 +15,9 @@ Stdlib-only. Config from the environment, mirroring ``swarph mesh``'s token mode
     / SWARPH_BRAIN_TOKEN  mesh per-peer token (~/.config/swarph/<self>.peer_token).
     / peer-token file     Once gbrain accepts mesh peer tokens, the peer token IS
                           the read token — no separate secret to provision.
+  SWARPH_BRAIN_GATEWAY  when set, query the brain via the mesh gateway's
+                        /brain/query proxy using the cell's mesh peer token
+                        (no per-cell gbrain_ token). Unset = direct :8792.
   SWARPH_FACADE         optional synthesis endpoint (claude-service chat-completions)
   SWARPH_FACADE_TOKEN   bearer for the facade
 """
@@ -127,6 +130,15 @@ def _mcp_query(url: str, token: str, question: str, limit: int) -> list:
     return _parse_query_response(raw)
 
 
+def _gateway_query(gw_base: str, peer_token: str, question: str, limit: int) -> list:
+    """Query the brain via the mesh gateway's /brain/query proxy, authenticating
+    with the cell's MESH peer token. The gateway holds the gbrain token; we never do."""
+    url = gw_base.rstrip("/") + "/brain/query"
+    raw = _http_post(url, {"query": question, "limit": limit}, peer_token,
+                     accept="application/json")
+    return json.loads(raw).get("chunks", [])
+
+
 def _synthesize(facade_url: str, facade_token: str, question: str, chunks: list) -> str:
     """Ask the $0 facade to answer ONLY from the retrieved chunks, citing slugs."""
     context = _format_chunks(chunks)
@@ -158,19 +170,36 @@ def run_brain_ask(argv: list) -> int:
     args = parser.parse_args(argv)
     question = " ".join(args.question)
 
-    token = _resolve_token(args.token_file, _self_name())
-    if not token:
-        sys.stderr.write(
-            "swarph brain-ask: no gbrain read token "
-            "(set GBRAIN_TOKEN / SWARPH_BRAIN_TOKEN, pass --token-file, or place a "
-            "mesh peer token at ~/.config/swarph/<self>.peer_token)\n")
-        return 2
-
-    try:
-        chunks = _mcp_query(args.gateway, token, question, args.limit)
-    except Exception as exc:  # noqa: BLE001 — surface any transport/parse failure cleanly
-        sys.stderr.write(f"swarph brain-ask: gbrain query failed: {exc}\n")
-        return 1
+    gw = os.environ.get("SWARPH_BRAIN_GATEWAY")
+    if gw:
+        self_name = _self_name()
+        try:
+            peer_token = _peer_token_path(self_name).read_text(encoding="utf-8").strip()
+        except OSError:
+            peer_token = ""
+        if not peer_token:
+            sys.stderr.write(
+                f"swarph brain-ask: SWARPH_BRAIN_GATEWAY set but no mesh peer token at "
+                f"~/.config/swarph/{self_name}.peer_token\n")
+            return 2
+        try:
+            chunks = _gateway_query(gw, peer_token, question, args.limit)
+        except Exception as e:  # noqa: BLE001 — surface, don't swallow
+            sys.stderr.write(f"swarph brain-ask: gateway brain query failed: {e}\n")
+            return 1
+    else:
+        token = _resolve_token(args.token_file, _self_name())
+        if not token:
+            sys.stderr.write(
+                "swarph brain-ask: no gbrain read token "
+                "(set GBRAIN_TOKEN / SWARPH_BRAIN_TOKEN, pass --token-file, or place a "
+                "mesh peer token at ~/.config/swarph/<self>.peer_token)\n")
+            return 2
+        try:
+            chunks = _mcp_query(args.gateway, token, question, args.limit)
+        except Exception as exc:  # noqa: BLE001 — surface any transport/parse failure cleanly
+            sys.stderr.write(f"swarph brain-ask: gbrain query failed: {exc}\n")
+            return 1
 
     facade = os.environ.get("SWARPH_FACADE")
     if args.no_synth or not facade:

{swarph_cli-0.24.0 → swarph_cli-0.26.0}/src/swarph_cli/commands/watchdog.py

@@ -580,14 +580,15 @@ def _pid_under(pid: int, ancestors: set, _max_depth: int = 40) -> bool:
     return cur in ancestors
 
 
-def _process_alive(tmux_session: str) -> bool:
-    """Detect if a claude process is running INSIDE the named tmux session.
-
-    Scopes to the session's pane PIDs (and their descendants) rather than a
-    host-wide ``pgrep claude``: on a multi-session host, an unrelated cell's
-    claude would otherwise mask THIS session's death and suppress the A2 alert
-    (adversarial-sweep MED). Best-effort; falls back to True (assume alive) on
-    detection error so a broken detector never false-fires A2.
+def _process_alive(tmux_session: str, process_name: str = "claude") -> bool:
+    """Detect if a `process_name` process is running INSIDE the named tmux session.
+
+    `process_name` (default "claude") is the command the cell's agent runs —
+    node/codex cells pass "node", grok cells pass "grok". Scopes to the
+    session's pane PIDs (and descendants) rather than a host-wide pgrep: on a
+    multi-session host, an unrelated cell's process would otherwise mask THIS
+    session's death and suppress the A2 alert. Best-effort; falls back to True
+    (assume alive) on detection error so a broken detector never false-fires A2.
     """
     try:
         panes = subprocess.run(
@@ -615,18 +616,34 @@ def _process_alive(tmux_session: str) -> bool:
             return True  # ambiguous (session with no pane pids) → don't false-fire
 
         pg = subprocess.run(
-            ["pgrep", "-f", "claude"],
+            ["pgrep", "-f", process_name],
             capture_output=True, text=True, timeout=5,
         )
         if pg.returncode != 0:
-            return False  # no claude process anywhere on the host
-        claude_pids = [int(p) for p in pg.stdout.split() if p.strip().isdigit()]
-        # Alive only if a claude process is a descendant of THIS session's panes.
-        return any(_pid_under(cpid, pane_pids) for cpid in claude_pids)
+            return False  # no matching process anywhere on the host
+        matched_pids = [int(p) for p in pg.stdout.split() if p.strip().isdigit()]
+        # Alive only if a matching process is a descendant of THIS session's panes.
+        return any(_pid_under(cpid, pane_pids) for cpid in matched_pids)
     except (subprocess.TimeoutExpired, FileNotFoundError, OSError, ValueError):
         return True  # assume alive on detection error
 
 
+def _liveness_via_cmd(cmd: str) -> bool:
+    """Escape-hatch liveness probe: run `cmd`; exit 0 = alive, non-zero = dead.
+
+    For cells whose liveness a process name can't express. Bounded timeout;
+    on timeout / OSError assume ALIVE — a broken or slow probe must never
+    false-fire the destructive A2 respawn (same fail-safe as _process_alive).
+    """
+    try:
+        result = subprocess.run(
+            cmd, shell=True, capture_output=True, timeout=5,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return True
+
+
 def _tmux_session_exists(name: str) -> bool:
     try:
         result = subprocess.run(
@@ -638,15 +655,15 @@ def _tmux_session_exists(name: str) -> bool:
         return False
 
 
-def _resolve_send_target(name: str) -> str:
-    """Resolve a session name to the pane actually running the claude TUI.
+def _resolve_send_target(name: str, process_name: str = "claude") -> str:
+    """Resolve a session name to the pane actually running the cell's agent.
 
     `send-keys -t <session>` lands on the session's ACTIVE pane — on a
-    multi-pane cell that can be a bash/log pane, where an injected
-    `/model ...` would execute as a SHELL command (drop seat-A N3). Prefer
-    the pane whose current command looks like the claude CLI (node/claude);
-    fall back to the session name unchanged when tmux is unavailable, the
-    listing fails, or no pane matches.
+    multi-pane cell that can be a bash/log pane, where an injected wake would
+    execute as a SHELL command. Prefer the pane whose current command matches
+    the cell's `process_name`; then fall back to the claude-CLI heuristic
+    (claude runs under node); then to the session name unchanged when tmux is
+    unavailable, the listing fails, or no pane matches.
     """
     try:
         result = subprocess.run(
@@ -656,8 +673,11 @@ def _resolve_send_target(name: str) -> str:
         )
         if result.returncode != 0:
             return name
-        for line in result.stdout.splitlines():
-            parts = line.split()
+        panes = [ln.split() for ln in result.stdout.splitlines()]
+        for parts in panes:                       # exact process_name match wins
+            if len(parts) >= 2 and parts[1] == process_name:
+                return parts[0]
+        for parts in panes:                       # claude-CLI fallback (node)
             if len(parts) >= 2 and parts[1] in ("claude", "node"):
                 return parts[0]
     except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
@@ -665,7 +685,9 @@ def _resolve_send_target(name: str) -> str:
     return name
 
 
-def _tmux_send_keys(name: str, text: str, clear_input: bool = False) -> bool:
+def _tmux_send_keys(
+    name: str, text: str, clear_input: bool = False, process_name: str = "claude"
+) -> bool:
     """Send `text` + Enter to a tmux target.
 
     The target is resolved to the claude-TUI pane first (_resolve_send_target,
@@ -677,7 +699,7 @@ def _tmux_send_keys(name: str, text: str, clear_input: bool = False) -> bool:
     text is noise, but `/model ...` merging into typed text submits a
     corrupted command.
     """
-    target = _resolve_send_target(name)
+    target = _resolve_send_target(name, process_name)
     keys = ["C-u", text, "Enter"] if clear_input else [text, "Enter"]
     try:
         result = subprocess.run(
@@ -1269,7 +1291,10 @@ def _run_local_check(args: argparse.Namespace) -> int:
             return 0
 
     # FALLBACK signal: pgrep claude (per mother #1021 AND-gate)
-    process_alive = _process_alive(tmux_session)
+    if args.liveness_cmd:
+        process_alive = _liveness_via_cmd(args.liveness_cmd)
+    else:
+        process_alive = _process_alive(tmux_session, args.process_name)
     diag["process_alive"] = process_alive
 
     # Check unread DM queue at gateway. If no unread DMs, no need to wake.
@@ -1444,7 +1469,8 @@ def _run_local_check(args: argparse.Namespace) -> int:
                 f"{model_text} into {tmux_session}",
                 file=sys.stderr,
             )
-            sent = _tmux_send_keys(tmux_session, model_text, clear_input=True)
+            sent = _tmux_send_keys(tmux_session, model_text, clear_input=True,
+                                   process_name=args.process_name)
             diag["send_keys_ok"] = sent
             if not sent:
                 # BLOCK-1 fix: a FAILED inject (wedged / timing-out pane) is
@@ -1487,7 +1513,7 @@ def _run_local_check(args: argparse.Namespace) -> int:
         f"watchdog wake — cursor stale {cursor_age}s, "
         f"unread={unread}; please drain inbox"
     )
-    sent = _tmux_send_keys(tmux_session, wake_text)
+    sent = _tmux_send_keys(tmux_session, wake_text, process_name=args.process_name)
     diag["send_keys_ok"] = sent
     if sent:
         _record_a1_fired(marker, cursor_mtime)
@@ -1722,6 +1748,22 @@ def _build_parser() -> argparse.ArgumentParser:
     p.add_argument("--gateway", default=_DEFAULT_GATEWAY_URL)
     p.add_argument("--tmux-session", default=None)
     p.add_argument("--peer", default=None)
+    liveness_group = p.add_mutually_exclusive_group()
+    liveness_group.add_argument(
+        "--process-name", default="claude",
+        help="Process the cell's agent runs, used by the liveness gate's "
+             "`pgrep -f` (scoped to the session's panes). Default 'claude'; "
+             "pass 'node' for a codex cell, 'grok' for a grok cell so a "
+             "non-Claude cell isn't mis-read as dead. Mutually exclusive with "
+             "--liveness-cmd.",
+    )
+    liveness_group.add_argument(
+        "--liveness-cmd", default=None,
+        help="Escape hatch: shell command whose exit status is the liveness "
+             "verdict (0 = alive, non-zero = dead) instead of the pgrep gate. "
+             "On timeout/error the cell is assumed ALIVE (never false-fire the "
+             "destructive A2 respawn). Mutually exclusive with --process-name.",
+    )
     p.add_argument("--no-respawn", action="store_true")
     p.add_argument(
         "--a15-max-swaps", type=int, default=_DEFAULT_A15_MAX_SWAPS,

{swarph_cli-0.24.0 → swarph_cli-0.26.0}/src/swarph_cli/gateway/server.py

@@ -41,6 +41,7 @@ import sqlite3
 import sys
 import time
 import unicodedata
+import urllib.request
 import uuid
 from contextlib import contextmanager
 from datetime import datetime, timedelta, timezone
@@ -52,6 +53,7 @@ from fastapi import FastAPI, Header, HTTPException, Query, Request
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse, Response
 from pydantic import BaseModel, Field
+from starlette.concurrency import run_in_threadpool
 
 from .feature_registry import aggregate_features, apply_allowlist, apply_caps
 
@@ -71,6 +73,12 @@ SCHEMA_PATH = os.environ.get(
 )
 PORT = int(os.environ.get("PORT", "8788"))
 
+# Gateway-held gbrain proxy token (POST /brain/query). Cells authenticate to
+# THIS gateway with their mesh token; the gateway then presents ITS OWN
+# gbrain token upstream so cells never need a separate gbrain_ credential.
+GATEWAY_GBRAIN_URL = os.environ.get("GATEWAY_GBRAIN_URL", "http://100.107.222.72:8792/mcp")
+GATEWAY_GBRAIN_TOKEN = os.environ.get("GATEWAY_GBRAIN_TOKEN", "")
+
 # B1 Meta-Edge identity (META_EDGE_IDENTITY_CONTRACT.md). Meta-Edge SSO ISSUES
 # RS256 JWTs; the gateway only ever TRUSTS them with Meta-Edge's PUBLIC key (it
 # can never forge one — the identity↔relay asymmetry). All three are read at
@@ -4196,6 +4204,59 @@ async def council_reclaim_stuck(req: CouncilReclaimStuckRequest,
     }
 
 
+# =====================================================================
+# BRAIN PROXY (POST /brain/query)
+# =====================================================================
+
+def _brain_query_upstream(question: str, limit: int) -> list:
+    """Proxy a READ-ONLY gbrain query. Builds the MCP `query` call itself (never
+    write/admin), POSTs to GATEWAY_GBRAIN_URL with the gateway-held token, returns
+    the chunk array. Raises on any upstream/parse failure (caller maps to 502)."""
+    body = {"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+            "params": {"name": "query",
+                       "arguments": {"query": question, "limit": limit, "expand": False}}}
+    req = urllib.request.Request(
+        GATEWAY_GBRAIN_URL, data=json.dumps(body).encode("utf-8"), method="POST")
+    req.add_header("Content-Type", "application/json")
+    req.add_header("Accept", "application/json, text/event-stream")
+    req.add_header("Authorization", f"Bearer {GATEWAY_GBRAIN_TOKEN}")
+    with urllib.request.urlopen(req, timeout=30) as resp:  # noqa: S310 — fixed tailnet URL
+        raw = resp.read().decode("utf-8")
+    payload = raw
+    if "data:" in raw:
+        for line in raw.splitlines():
+            s = line.strip()
+            if s.startswith("data:"):
+                payload = s[len("data:"):].strip()
+                break
+    doc = json.loads(payload)
+    parsed = json.loads(doc["result"]["content"][0]["text"])
+    return parsed if isinstance(parsed, list) else []
+
+
+class BrainQueryRequest(BaseModel):
+    query: str
+    limit: int = 8
+
+
+@app.post("/brain/query")
+async def brain_query(req: BrainQueryRequest,
+                      authorization: Optional[str] = Header(None)) -> dict:
+    auth = _authorize(authorization)                      # 401 on bad mesh token
+    if not GATEWAY_GBRAIN_TOKEN:
+        raise HTTPException(503, "brain proxy not configured")
+    if not req.query.strip():
+        raise HTTPException(400, "query is required")
+    try:
+        chunks = await run_in_threadpool(_brain_query_upstream, req.query, req.limit)
+    except Exception as e:  # fail loud — never a swallowed empty result
+        log.warning("brain proxy upstream error for peer=%s: %s", auth.peer, e)
+        raise HTTPException(502, "brain upstream error")
+    log.info("brain query peer=%s regime=%s limit=%d chunks=%d",
+             auth.peer, auth.regime, req.limit, len(chunks))
+    return {"chunks": chunks}
+
+
 # =====================================================================
 # STARTUP
 # =====================================================================

{swarph_cli-0.24.0 → swarph_cli-0.26.0/src/swarph_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.24.0
+Version: 0.26.0
 Summary: The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, session `import`, and a stranded-session `watchdog`.
 Author: Pierre Samson, Claude Opus
 License: MIT

{swarph_cli-0.24.0 → swarph_cli-0.26.0}/src/swarph_cli.egg-info/SOURCES.txt

@@ -105,6 +105,7 @@ tests/test_compress_verify.py
 tests/test_daemon_command.py
 tests/test_event_emit.py
 tests/test_feature_to_uri.py
+tests/test_gateway_brain.py
 tests/test_gateway_client.py
 tests/test_gateway_command.py
 tests/test_highlight_command.py

{swarph_cli-0.24.0 → swarph_cli-0.26.0}/tests/test_brain_ask_command.py

@@ -13,6 +13,13 @@ from unittest.mock import patch
 from swarph_cli.commands import brain_ask as ba
 
 
+# --- version ---------------------------------------------------------------
+
+def test_version_is_0_26_0():
+    import swarph_cli
+    assert swarph_cli.__version__ == "0.26.0"
+
+
 # --- request / response plumbing -------------------------------------------
 
 def test_build_query_request_shape():
@@ -122,3 +129,55 @@ def test_resolve_endpoint_default_is_localhost(monkeypatch):
     monkeypatch.delenv("GBRAIN_MCP_URL", raising=False)
     monkeypatch.delenv("SWARPH_BRAIN_MCP", raising=False)
     assert ba._resolve_endpoint() == "http://127.0.0.1:8792/mcp"
+
+
+# --- SWARPH_BRAIN_GATEWAY client path (Task 2) ------------------------------
+
+def test_gateway_query_posts_brain_query_with_peer_token(monkeypatch, tmp_path):
+    from swarph_cli.commands import brain_ask
+    captured = {}
+    def fake_http_post(url, body, token, accept="application/json, text/event-stream", timeout=30):
+        captured.update(url=url, body=body, token=token)
+        import json as _j
+        return _j.dumps({"chunks": [{"slug": "s1", "chunk_text": "x"}]})
+    monkeypatch.setattr(brain_ask, "_http_post", fake_http_post)
+    out = brain_ask._gateway_query("http://gw:8788", "peer_tok_123", "hello", 5)
+    assert out == [{"slug": "s1", "chunk_text": "x"}]
+    assert captured["url"] == "http://gw:8788/brain/query"
+    assert captured["body"] == {"query": "hello", "limit": 5}
+    assert captured["token"] == "peer_tok_123"
+
+
+def test_run_brain_ask_uses_gateway_when_env_set(monkeypatch, tmp_path, capsys):
+    from swarph_cli.commands import brain_ask
+    # peer token on disk for _self_name()
+    cfg = tmp_path / ".config" / "swarph"
+    cfg.mkdir(parents=True)
+    (cfg / "wlc.peer_token").write_text("peer_tok_xyz", encoding="utf-8")
+    monkeypatch.setattr(brain_ask.Path, "home", classmethod(lambda cls: tmp_path))
+    monkeypatch.setenv("SWARPH_SELF", "wlc")
+    monkeypatch.setenv("SWARPH_BRAIN_GATEWAY", "http://gw:8788")
+    seen = {}
+    def fake_gateway_query(gw, tok, q, n):
+        seen.update(gw=gw, tok=tok, q=q)
+        return [{"slug": "s1", "chunk_text": "hit"}]
+    monkeypatch.setattr(brain_ask, "_gateway_query", fake_gateway_query)
+    rc = brain_ask.run_brain_ask(["--no-synth", "what", "is", "up"])
+    assert rc == 0
+    assert seen["gw"] == "http://gw:8788" and seen["tok"] == "peer_tok_xyz"
+    assert "s1" in capsys.readouterr().out
+
+
+def test_run_brain_ask_direct_path_unchanged_when_gateway_unset(monkeypatch, capsys):
+    from swarph_cli.commands import brain_ask
+    monkeypatch.delenv("SWARPH_BRAIN_GATEWAY", raising=False)
+    monkeypatch.setenv("GBRAIN_TOKEN", "gbrain_direct")
+    called = {}
+    def fake_mcp(url, tok, q, n):
+        called["hit"] = (url, tok)
+        return [{"slug": "d"}]
+    monkeypatch.setattr(brain_ask, "_mcp_query", fake_mcp)
+    rc = brain_ask.run_brain_ask(["--no-synth", "hello"])
+    assert rc == 0
+    assert called["hit"][1] == "gbrain_direct"     # direct path used the gbrain token
+    assert "d" in capsys.readouterr().out

swarph_cli-0.26.0/tests/test_gateway_brain.py

@@ -0,0 +1,104 @@
+import json
+import os
+import importlib
+import tempfile
+import pytest
+from types import SimpleNamespace
+
+# The gateway server stack is an optional extra ([gateway]); its module top
+# does `import jwt` (PyJWT) + fastapi. Skip the whole file when those aren't
+# installed (e.g. Windows CI, which doesn't install the gateway extra) — same
+# guard the sibling gateway test tests/test_meta_edge_identity.py uses.
+pytest.importorskip("fastapi")
+pytest.importorskip("jwt")
+
+
+def _load_app(monkeypatch, *, gbrain_token="gbrain_hostheld", auth="tok_shared"):
+    monkeypatch.setenv("MESH_GATEWAY_TOKEN", auth)
+    monkeypatch.setenv("GATEWAY_GBRAIN_TOKEN", gbrain_token)
+    monkeypatch.setenv("GATEWAY_GBRAIN_URL", "http://127.0.0.1:8792/mcp")
+    # NOTE: ":memory:" (as written in the task brief) is incompatible with this
+    # module's _conn()/_init_db(), which open a FRESH sqlite3.connect() per call
+    # with no shared cache — each ":memory:" connection is an independent,
+    # isolated DB, so the schema built by _init_db()'s first connection is gone
+    # by its second. That fails at import time, before any endpoint code runs,
+    # for every one of the 6 tests here — not the brief's expected 404/
+    # AttributeError RED. Using a real temp-file path (matching the existing
+    # pattern in tests/test_meta_edge_identity.py) fixes the scaffold without
+    # touching production DB code, and restores the brief's intended RED.
+    monkeypatch.setenv("MESH_DB_PATH", os.path.join(tempfile.mkdtemp(), "mesh.db"))
+    from swarph_cli.gateway import server
+    importlib.reload(server)          # re-read module-top env config
+    return server
+
+
+def _sse(chunks):
+    inner = json.dumps(chunks)
+    env = {"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": inner}]}}
+    return "event: message\ndata: " + json.dumps(env) + "\n\n"
+
+
+def _client(server):
+    from fastapi.testclient import TestClient
+    return TestClient(server.app)
+
+
+def test_brain_query_authenticates_and_returns_chunks(monkeypatch):
+    server = _load_app(monkeypatch)
+    chunks = [{"slug": "s1", "title": "T", "chunk_text": "hello", "score": 0.9}]
+    monkeypatch.setattr(server, "_brain_query_upstream", lambda q, n: chunks)
+    r = _client(server).post("/brain/query", json={"query": "hi", "limit": 5},
+                             headers={"Authorization": "Bearer tok_shared"})
+    assert r.status_code == 200
+    assert r.json() == {"chunks": chunks}
+
+
+def test_brain_query_bad_token_401(monkeypatch):
+    server = _load_app(monkeypatch)
+    monkeypatch.setattr(server, "_brain_query_upstream", lambda q, n: [])
+    r = _client(server).post("/brain/query", json={"query": "hi"},
+                             headers={"Authorization": "Bearer wrong"})
+    assert r.status_code == 401
+
+
+def test_brain_query_unconfigured_503(monkeypatch):
+    server = _load_app(monkeypatch, gbrain_token="")   # GATEWAY_GBRAIN_TOKEN unset
+    r = _client(server).post("/brain/query", json={"query": "hi"},
+                             headers={"Authorization": "Bearer tok_shared"})
+    assert r.status_code == 503
+
+
+def test_brain_query_empty_query_400(monkeypatch):
+    server = _load_app(monkeypatch)
+    monkeypatch.setattr(server, "_brain_query_upstream", lambda q, n: [])
+    r = _client(server).post("/brain/query", json={"query": "   "},
+                             headers={"Authorization": "Bearer tok_shared"})
+    assert r.status_code == 400
+
+
+def test_brain_query_upstream_error_502(monkeypatch):
+    server = _load_app(monkeypatch)
+    def boom(q, n): raise RuntimeError("gbrain down")
+    monkeypatch.setattr(server, "_brain_query_upstream", boom)
+    r = _client(server).post("/brain/query", json={"query": "hi"},
+                             headers={"Authorization": "Bearer tok_shared"})
+    assert r.status_code == 502
+
+
+def test_upstream_helper_is_read_only_by_construction(monkeypatch):
+    """The MCP body the proxy sends upstream ALWAYS has params.name == 'query'."""
+    server = _load_app(monkeypatch)
+    captured = {}
+    class FakeResp:
+        def read(self): return _sse([{"slug": "s"}]).encode()
+        def __enter__(self): return self
+        def __exit__(self, *a): return False
+    def fake_urlopen(req, timeout=None):
+        captured["body"] = json.loads(req.data.decode())
+        captured["auth"] = req.get_header("Authorization")
+        return FakeResp()
+    monkeypatch.setattr(server.urllib.request, "urlopen", fake_urlopen)
+    out = server._brain_query_upstream("anything", 8)
+    assert out == [{"slug": "s"}]
+    assert captured["body"]["params"]["name"] == "query"          # read-only lock
+    assert captured["auth"] == "Bearer gbrain_hostheld"           # gateway's held token