swarph-cli 0.40.3__tar.gz → 0.41.1__tar.gz

{swarph_cli-0.40.3/src/swarph_cli.egg-info → swarph_cli-0.41.1}/PKG-INFO

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.40.3
+Version: 0.41.1
 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
 Project-URL: Homepage, https://github.com/BrainSurfing-tech/swarph-cli
 Project-URL: Source, https://github.com/BrainSurfing-tech/swarph-cli
 Project-URL: Substrate, https://github.com/BrainSurfing-tech/swarph-mesh
-Project-URL: Spec, https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md
 Keywords: swarph,llm,cli,mesh,gemini,claude,deepseek
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
@@ -467,13 +466,41 @@ swarph watchdog --check --peer researcher --gateway http://localhost:8788 --dm-w
 Installs Claude Code hooks as **content** wired into `~/.claude/settings.json` — a hook becomes an installable artifact (a script + its event/matcher bindings merged into your settings) with no swarph-cli version bump per hook, the same way `watchdog --install-service` ships systemd units as bundled data.
 
 ```bash
-swarph hooks init                 # install the recommended bundled set (cell-resilience)
-swarph hooks add cell-resilience  # install one builtin by name
-swarph hooks add ./my-hook        # install a local bundle dir (hook.json + script)
-swarph hooks list                 # builtins + install status (installed|available)
+swarph hooks init                    # install the recommended bundled set
+swarph hooks add codegraph-on-grep   # structural search alongside grep (see below)
+swarph hooks add cell-resilience     # install one builtin by name
+swarph hooks add ./my-hook           # install a local bundle dir (hook.json + script)
+swarph hooks list                    # builtins + install status (installed|available)
 swarph hooks remove cell-resilience
 ```
 
+**Bundled `codegraph-on-grep`** *(0.41.0)*. Binds `PostToolUse`/`Bash`. When a `grep`/`rg` searches
+**code**, it also queries the mesh gateway's structural codegraph and hands back the symbol-level
+answer — definitions, `file:line`, and **caller counts, which grep structurally cannot see**:
+
+```
+CODEGRAPH (structural, index 2.1h old) for 'def _board_grant' — grep found text; this is
+the symbol graph, incl. CALLER COUNTS grep cannot see:
+  mesh-gateway/server.py:1352  function _board_grant  callers=11
+```
+
+The point is **context cost**: a grep returning 200 matching lines is far more expensive than the
+handful of symbols that answer *"where is this defined and who calls it"*.
+
+- **It supplements grep; it never blocks it.** grep stays correct for config, logs and string
+  literals — the codegraph indexes *symbols*.
+- **An unavailable index is reported loudly, never as "no matches."** A failed lookup rendered as a
+  real negative teaches exactly the wrong thing, so the hook says so and marks the answer
+  unverified. A genuinely empty result from a *working* index says `a REAL negative` explicitly, and
+  a stale index reports its age.
+- **No local index required.** It asks the gateway, which scopes both rows and caller counts to your
+  visibility — resolved from your **bearer token**, never from a field you send, so it cannot be
+  self-asserted.
+
+Needs `SWARPH_SELF` (or `--as`), your peer token at `~/.config/swarph/<cell>.peer_token`, and a
+reachable gateway. Do not run a hand-rolled copy alongside it: two hooks per `Bash` call means two
+lookups, doubling the cost the hook exists to cut.
+
 **Trust model.** Three tiers: `builtin` (trusted, bundled with swarph-cli — installs without a prompt), `local` (a bundle dir you point at — shown then confirmed before any write), and `published`/`@cell/name` (**fails closed in v1** — never installs another cell's unreviewed code). Signed-publisher identity plus a publish-time security gate is the v2 model.
 
 **Bundled `cell-resilience`.** Binds `StopFailure`/`rate_limit` + `Stop`/`(all)` to a script that writes `$XDG_STATE_HOME/swarph/idle_since.json` (`{"session","reason","hook_event","ts"}`, `reason=throttle|normal`) — the push-side throttle detector the watchdog's `--dm-wake` can read instead of polling. Observational only: it never blocks the session and always exits 0 (jq if present, printf/sed fallback otherwise).
@@ -655,7 +682,7 @@ Dry-run is the default — nothing mutates without `--apply`. Cron-friendly exit
 | `8` | refused — not idempotent (second pass kept cutting; signal-eating alarm) |
 
 Design spec: `docs/superpowers/specs/2026-06-11-swarph-context-compressor-design.md`
-(in the hedge-fund-mcp repo).
+(in a private design repo; not published).
 
 ### `--json` mode semantics
 

{swarph_cli-0.40.3 → swarph_cli-0.41.1}/README.md

@@ -420,13 +420,41 @@ swarph watchdog --check --peer researcher --gateway http://localhost:8788 --dm-w
 Installs Claude Code hooks as **content** wired into `~/.claude/settings.json` — a hook becomes an installable artifact (a script + its event/matcher bindings merged into your settings) with no swarph-cli version bump per hook, the same way `watchdog --install-service` ships systemd units as bundled data.
 
 ```bash
-swarph hooks init                 # install the recommended bundled set (cell-resilience)
-swarph hooks add cell-resilience  # install one builtin by name
-swarph hooks add ./my-hook        # install a local bundle dir (hook.json + script)
-swarph hooks list                 # builtins + install status (installed|available)
+swarph hooks init                    # install the recommended bundled set
+swarph hooks add codegraph-on-grep   # structural search alongside grep (see below)
+swarph hooks add cell-resilience     # install one builtin by name
+swarph hooks add ./my-hook           # install a local bundle dir (hook.json + script)
+swarph hooks list                    # builtins + install status (installed|available)
 swarph hooks remove cell-resilience
 ```
 
+**Bundled `codegraph-on-grep`** *(0.41.0)*. Binds `PostToolUse`/`Bash`. When a `grep`/`rg` searches
+**code**, it also queries the mesh gateway's structural codegraph and hands back the symbol-level
+answer — definitions, `file:line`, and **caller counts, which grep structurally cannot see**:
+
+```
+CODEGRAPH (structural, index 2.1h old) for 'def _board_grant' — grep found text; this is
+the symbol graph, incl. CALLER COUNTS grep cannot see:
+  mesh-gateway/server.py:1352  function _board_grant  callers=11
+```
+
+The point is **context cost**: a grep returning 200 matching lines is far more expensive than the
+handful of symbols that answer *"where is this defined and who calls it"*.
+
+- **It supplements grep; it never blocks it.** grep stays correct for config, logs and string
+  literals — the codegraph indexes *symbols*.
+- **An unavailable index is reported loudly, never as "no matches."** A failed lookup rendered as a
+  real negative teaches exactly the wrong thing, so the hook says so and marks the answer
+  unverified. A genuinely empty result from a *working* index says `a REAL negative` explicitly, and
+  a stale index reports its age.
+- **No local index required.** It asks the gateway, which scopes both rows and caller counts to your
+  visibility — resolved from your **bearer token**, never from a field you send, so it cannot be
+  self-asserted.
+
+Needs `SWARPH_SELF` (or `--as`), your peer token at `~/.config/swarph/<cell>.peer_token`, and a
+reachable gateway. Do not run a hand-rolled copy alongside it: two hooks per `Bash` call means two
+lookups, doubling the cost the hook exists to cut.
+
 **Trust model.** Three tiers: `builtin` (trusted, bundled with swarph-cli — installs without a prompt), `local` (a bundle dir you point at — shown then confirmed before any write), and `published`/`@cell/name` (**fails closed in v1** — never installs another cell's unreviewed code). Signed-publisher identity plus a publish-time security gate is the v2 model.
 
 **Bundled `cell-resilience`.** Binds `StopFailure`/`rate_limit` + `Stop`/`(all)` to a script that writes `$XDG_STATE_HOME/swarph/idle_since.json` (`{"session","reason","hook_event","ts"}`, `reason=throttle|normal`) — the push-side throttle detector the watchdog's `--dm-wake` can read instead of polling. Observational only: it never blocks the session and always exits 0 (jq if present, printf/sed fallback otherwise).
@@ -608,7 +636,7 @@ Dry-run is the default — nothing mutates without `--apply`. Cron-friendly exit
 | `8` | refused — not idempotent (second pass kept cutting; signal-eating alarm) |
 
 Design spec: `docs/superpowers/specs/2026-06-11-swarph-context-compressor-design.md`
-(in the hedge-fund-mcp repo).
+(in a private design repo; not published).
 
 ### `--json` mode semantics
 

{swarph_cli-0.40.3 → swarph_cli-0.41.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.40.3"
+version = "0.41.1"
 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" }
@@ -51,7 +51,6 @@ dependencies = [
 Homepage = "https://github.com/BrainSurfing-tech/swarph-cli"
 Source = "https://github.com/BrainSurfing-tech/swarph-cli"
 Substrate = "https://github.com/BrainSurfing-tech/swarph-mesh"
-Spec = "https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md"
 
 [project.optional-dependencies]
 dev = ["pytest>=7.0"]
@@ -111,4 +110,11 @@ swarph_cli = ["systemd/*.service", "systemd/*.timer", "systemd/*.default",
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+# The tree must win over any installed copy. Without this, `pip install swarph-cli`
+# on the same box shadows src/ and the suite silently tests the PUBLISHED wheel
+# instead of your edits — every local change reads green whether or not it works.
+# Measured 2026-08-01: 1689 passed against site-packages vs 1690 against the tree;
+# the only test that noticed was a brand-new one, because the tree and 0.41.0 were
+# nearly identical. That agreement is a polluted baseline, not isolation.
+pythonpath = ["src"]
 addopts = "-v --tb=short"

{swarph_cli-0.40.3 → swarph_cli-0.41.1}/src/swarph_cli/__init__.py

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

{swarph_cli-0.40.3 → swarph_cli-0.41.1}/src/swarph_cli/commands/codegraph.py

@@ -145,8 +145,27 @@ def structural_query(term, *, index_path, caller_cell, limit=8, allowlist=None)
             # verbatim edge kinds (contains/imports/decorates/references/calls/...), and counting
             # all of them would pollute the blast-radius number. 'calls' (plural) is CodeGraph's
             # actual call-edge kind.
+            #
+            # >>> CARD #194 — THE COUNT IS SCOPED TO THE CALLER-VISIBLE REPOS, exactly
+            # like the rows above. <<< This was an unscoped COUNT(*) while `s.repo IN
+            # (allowed)` gated the rows, so a caller who could NOT see a private repo
+            # still received a caller count that INCLUDED its callers.
+            #
+            # drop-on-meta-edge, seat-A: "a count that sums callers living in a private
+            # repo LEAKS THE EXISTENCE AND SIZE of those private callers — the exact
+            # payload #44's transport refuses, delivered as an integer instead of a
+            # path." Measured 2026-07-31: cross-visibility `calls` edges were 0 on the
+            # live index, so the leak was LATENT — but this is the blast-radius number
+            # the feature exists to serve, and the gateway proxy would have exposed it
+            # to every remote peer.
+            #
+            # The unifying rule: EVERY OBSERVABLE — rows, counts, scores, freshness —
+            # must be a function of only the caller-visible subset, never the full
+            # index. Gating the rows is ONE INSTANCE of it, not the whole of it.
             callers = con.execute(
-                "SELECT COUNT(*) FROM edges WHERE dst_symbol=? AND edge_type='calls'", (sid,)
+                f"SELECT COUNT(*) FROM edges e JOIN symbols src ON src.id = e.src_symbol "
+                f"WHERE e.dst_symbol=? AND e.edge_type='calls' AND src.repo IN ({qmarks})",
+                (sid, *sorted(allowed))
             ).fetchone()[0]
             out.append({"repo": repo, "name": name, "kind": kind,
                         "file_path": fp, "start_line": line, "callers": callers, "score": score,

swarph_cli-0.41.1/src/swarph_cli/commands/codegraph_hook.py

@@ -0,0 +1,272 @@
+"""``swarph codegraph-hook`` — PostToolUse(Bash) structural-search companion.
+
+WHEN A grep/rg SEARCHES CODE, ALSO ASK THE CODEGRAPH, and hand the structural
+answer back as context. Card #194.
+
+WHY IT EXISTS. Agents reach for grep where the symbol graph is the right
+instrument — lab-ovh was corrected three times in one session for exactly that,
+and the third correction landed INSIDE the fix for the first two. Instructions
+demonstrably do not hold at the moment of typing, so this is mechanical rather
+than a reminder. The token argument is the commander's: a grep that returns 200
+matching lines costs far more context than the six symbols that actually answer
+"where is this defined and who calls it".
+
+>>> IT SUPPLEMENTS, IT NEVER BLOCKS. <<< grep is genuinely correct for config,
+logs, /etc and string literals; the codegraph indexes SYMBOLS. The failure this
+guards is "I only ever saw grep's answer", not "grep was used".
+
+>>> AND IT MUST NEVER DEGRADE SILENTLY. <<< A missing index makes a structural
+query return `[]` — indistinguishable from a real negative, which is the exact
+shape of the (gbrain unreachable) incident and of card #200's drain. So an
+unavailable backend is reported LOUDLY as an incident, never as "no matches".
+
+PEER MODE. Unlike lab-ovh's original local hook, a peer has no local index — it
+asks the gateway's ``POST /codegraph`` proxy, which applies the A8 visibility
+gate to rows AND to caller counts (swarph-cli PR #165). The caller identity comes
+from the bearer token, never from a field, so it cannot be self-asserted.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_GATEWAY = os.environ.get("MESH_GATEWAY_URL", "http://localhost:8788")
+TIMEOUT_S = 6
+MAX_ROWS = 6
+
+# ── trigger heuristics ────────────────────────────────────────────────────
+# Ported from the hook that ran on lab-ovh for a day. Every one of these three
+# patterns exists because a LOOSER version misfired in production.
+
+# 1. grep/rg must be at COMMAND POSITION — line start, or right after a pipe /
+#    ; / && / $( . Matching "grep" after arbitrary whitespace fires on any command
+#    whose text merely MENTIONS the word, including a heredoc body: the first live
+#    firing did exactly that and extracted the heredoc delimiter as the search term.
+_AT_COMMAND_POS = re.compile(r"(?:^|[|;&]|\$\()\s*(?:sudo\s+)?(?:grep|rg)\s")
+
+# 2. A heredoc means most of the command is DATA, not shell — too noisy to parse.
+_HEREDOC = re.compile(r"<<-?['\"]?\w*(?:EOF|PY)")
+
+# 3. It should look like a CODE search, not a config/log one.
+_CODEISH = re.compile(
+    r"\.(?:py|ts|tsx|js|jsx|go|rs|java|rb|c|h|cpp)\b|--include|(?:^|\s)-r\s|src/"
+)
+
+
+def _looks_like_code_search(cmd: str) -> bool:
+    if not _AT_COMMAND_POS.search(cmd):
+        return False
+    if _HEREDOC.search(cmd):
+        return False
+    return bool(_CODEISH.search(cmd))
+
+
+def extract_term(cmd: str) -> Optional[str]:
+    """The search term ADJACENT to grep — not the first quoted string anywhere.
+
+    A `gh pr close --comment "...'dead'..." && grep foo bar` fired a query for
+    'dead', lifted out of unrelated prose. So the scan starts AT the grep token.
+    """
+    m = _AT_COMMAND_POS.search(cmd)
+    if not m:
+        return None
+    tail = cmd[m.end():]
+    # Skip flags (-n, -R, --include=*.py, …) to reach the pattern itself.
+    for tok in _tokenize(tail):
+        if tok.startswith("-"):
+            continue
+        term = tok.strip("'\"")
+        # A regex-metachar soup is not a useful symbol query.
+        cleaned = re.sub(r"[^\w\s.]", " ", term).strip()
+        return cleaned or None
+    return None
+
+
+def _tokenize(s: str) -> list:
+    """Shell-ish split that keeps quoted strings together.
+
+    NOTE: no early break. An earlier version stopped after the FIRST completed
+    token, so a command whose first argument is a flag (`grep -rn 'pat' src/`)
+    yielded only `-rn`, the caller skipped it as a flag, and extraction returned
+    None — the hook silently never fired on the most common grep shape there is.
+    Caught by test_skips_flags_to_reach_the_pattern.
+    """
+    out, cur, quote, started = [], "", None, False
+    for ch in s:
+        if quote:
+            if ch == quote:
+                quote = None
+            else:
+                cur += ch
+        elif ch in "'\"":
+            quote, started = ch, True
+        elif ch.isspace():
+            if cur or started:
+                out.append(cur)
+                cur, started = "", False
+        else:
+            cur += ch
+            started = True
+    if cur or started:
+        out.append(cur)
+    return out
+
+
+# ── gateway query ─────────────────────────────────────────────────────────
+
+def _token_path(self_name: str) -> Path:
+    return Path.home() / ".config" / "swarph" / f"{self_name}.peer_token"
+
+
+def query_gateway(term: str, gateway: str, token: str, limit: int = MAX_ROWS) -> dict:
+    """POST /codegraph. Returns the envelope, or {"error": "..."} — NEVER {}.
+
+    >>> AN UNREACHABLE OR REFUSING BACKEND IS AN ERROR, NOT AN EMPTY RESULT. <<<
+    Collapsing them is the defect this hook exists to avoid teaching.
+    """
+    req = urllib.request.Request(
+        f"{gateway.rstrip('/')}/codegraph",
+        data=json.dumps({"query": term, "limit": limit}).encode(),
+        headers={"Authorization": f"Bearer {token}",
+                 "Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=TIMEOUT_S) as r:
+            return json.loads(r.read().decode())
+    except urllib.error.HTTPError as e:
+        detail = ""
+        try:
+            detail = json.loads(e.read().decode()).get("detail", "")
+        except Exception:  # noqa: BLE001
+            pass
+        return {"error": f"HTTP {e.code}: {detail or e.reason}"}
+    except Exception as e:  # noqa: BLE001 — transport/parse
+        return {"error": f"{type(e).__name__}: {e}"}
+
+
+def _match_quality(term: str, rows: list) -> tuple:
+    """Did the results actually match what was ASKED, or only a common token?
+
+    >>> THE EMPTY ANSWER WAS MADE HONEST; THE NON-EMPTY ONE WAS NOT. <<<
+    (Reported first-hand by a peer, 2026-08-01.) The index's query sanitiser
+    OR-JOINS tokens, so `def command_beta_executor` matches anything containing
+    "command". He grepped a private-repo file and got six confident-looking
+    swarph-cli symbols WITH CALLER COUNTS — plausible structure from the wrong
+    repository, and caller counts make it read authoritative. His words: "the
+    failure mode you engineered out of the empty case walked back in through the
+    non-empty one."
+
+    So: find the query's DISTINCTIVE token — the longest content token, which is
+    the one carrying the intent (`command_beta_executor`, not `def`) — and check
+    whether ANY returned symbol name actually contains it. If none does, every
+    row is a common-token coincidence and must be labelled as such rather than
+    served as an answer.
+
+    Returns (distinctive_token, n_rows_matching_it).
+    """
+    toks = [t for t in re.findall(r"[A-Za-z0-9_]+", (term or "").lower())
+            if len(t) > 2 and t not in {"def", "class", "async", "the", "for"}]
+    if not toks:
+        return ("", len(rows))
+    key = max(toks, key=len)
+    hits = sum(1 for r in rows if key in str(r.get("name", "")).lower())
+    return (key, hits)
+
+
+def render(term: str, env: dict) -> str:
+    """Format the envelope for injection. Errors are LOUD and named."""
+    if "error" in env:
+        return (f"CODEGRAPH UNAVAILABLE for '{term}' — {env['error']}\n"
+                f"  >>> THIS IS NOT 'no matches'. The structural index could not be "
+                f"consulted, so grep's answer is the ONLY answer you have. Treat "
+                f"definitions/callers as UNVERIFIED.")
+
+    rows = env.get("results") or []
+    fresh = env.get("freshness") or []
+    stale = [f for f in fresh if f.get("stale")]
+    age = ""
+    if fresh:
+        hrs = max((f.get("index_age_hours") or 0) for f in fresh)
+        age = f", index {hrs:.1f}h old"
+        if stale:
+            age += " ⚠ STALE — verify line numbers against the file"
+
+    if not rows:
+        body = ("  no structural matches (the index IS present and answered — "
+                "a REAL negative)")
+    else:
+        body = "\n".join(
+            f"  {r.get('repo')}/{r.get('file_path')}:{r.get('start_line')}  "
+            f"{r.get('kind')} {r.get('name')}  callers={r.get('callers')}"
+            for r in rows[:MAX_ROWS]
+        )
+    warn = ""
+    if rows:
+        key, hits = _match_quality(term, rows)
+        if key and hits == 0:
+            repos = sorted({str(r.get("repo")) for r in rows})
+            warn = (f"\n  >>> FUZZY MATCH — NOT AN ANSWER TO YOUR QUERY. No returned symbol's "
+                    f"name contains {key!r}. These matched a COMMON TOKEN only"
+                    + (f", and all are from: {', '.join(repos)}" if repos else "")
+                    + f". Treat them as unrelated: the symbol you grepped for is NOT in "
+                    f"what this index can see. <<<")
+    return (f"CODEGRAPH (structural{age}) for '{term}' — grep found text; this is "
+            f"the symbol graph, incl. CALLER COUNTS grep cannot see:\n{body}{warn}\n\n"
+            f"Use this for definitions/callers/blast-radius. grep remains correct "
+            f"for config, logs and string literals the codegraph does not index.")
+
+
+def run_codegraph_hook(argv: Optional[list] = None) -> int:
+    """PostToolUse(Bash) entry point. ALWAYS exits 0 — it must never fail a turn."""
+    argv = list(argv or [])
+    self_name = os.environ.get("SWARPH_SELF", "").strip()
+    gateway = DEFAULT_GATEWAY
+    for i, a in enumerate(argv):
+        if a == "--as" and i + 1 < len(argv):
+            self_name = argv[i + 1]
+        elif a == "--gateway" and i + 1 < len(argv):
+            gateway = argv[i + 1]
+
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except Exception:  # noqa: BLE001
+        return 0
+    cmd = ((payload.get("tool_input") or {}).get("command") or "").strip()
+    if not cmd or not _looks_like_code_search(cmd):
+        return 0
+    term = extract_term(cmd)
+    if not term:
+        return 0
+
+    if not self_name:
+        _emit(f"CODEGRAPH SKIPPED for '{term}' — no cell identity (set SWARPH_SELF "
+              f"or pass --as). Not a negative result: the graph was never asked.")
+        return 0
+    tp = _token_path(self_name)
+    try:
+        token = tp.read_text().strip()
+    except OSError as e:
+        _emit(f"CODEGRAPH UNAVAILABLE for '{term}' — peer token unreadable at {tp}: "
+              f"{e}. Not a negative result: the graph was never asked.")
+        return 0
+
+    _emit(render(term, query_gateway(term, gateway, token)))
+    return 0
+
+
+def _emit(text: str) -> None:
+    """Hand context back to the model via the documented hook JSON shape."""
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PostToolUse",
+            "additionalContext": text,
+        }
+    }))

{swarph_cli-0.40.3 → swarph_cli-0.41.1}/src/swarph_cli/commands/hooks.py

@@ -155,7 +155,43 @@ exit 0
 """
 
 
+# The bundled codegraph-on-grep script (card #194). Deliberately a THIN WRAPPER
+# around `swarph codegraph-hook` rather than fat inline shell: the trigger
+# heuristics are the hard-won part — each guard in that module exists because a
+# LOOSER version misfired in production (a heredoc delimiter extracted as the
+# search term; a quoted string lifted out of unrelated prose) — and heuristics
+# that specific must be unit-testable, which inline sh is not. Same pattern as
+# `install-hook`, which points at `swarph hook-output`.
+#
+# `exec` so the hook process IS the handler, and the verb always exits 0: a
+# PostToolUse hook must never fail a turn.
+_CODEGRAPH_ON_GREP_SH = r"""#!/bin/sh
+# codegraph-on-grep.sh — swarph bundled Claude Code hook (PostToolUse/Bash).
+#
+# When a grep/rg searches CODE, also ask the gateway's structural codegraph and
+# hand the symbol-level answer back as context. Supplements grep, never blocks it.
+# All logic lives in `swarph codegraph-hook` so it can be tested; see that module
+# for why each trigger guard exists.
+exec swarph codegraph-hook "$@"
+"""
+
 BUILTIN_HOOKS: dict = {
+    "codegraph-on-grep": HookBundle(
+        name="codegraph-on-grep",
+        description=(
+            "When a grep/rg searches code, also queries the gateway's structural "
+            "codegraph and injects the symbol-level answer (definitions, file:line, "
+            "caller counts) as context. Supplements grep; never blocks it. Reports "
+            "an unavailable index LOUDLY rather than as 'no matches'."
+        ),
+        publisher="swarph-builtin",
+        trust="builtin",
+        script_name="codegraph-on-grep.sh",
+        script_body=_CODEGRAPH_ON_GREP_SH,
+        bindings=(
+            HookBinding("PostToolUse", "Bash"),
+        ),
+    ),
     "cell-resilience": HookBundle(
         name="cell-resilience",
         description=(

{swarph_cli-0.40.3 → swarph_cli-0.41.1}/src/swarph_cli/commands/mesh.py

@@ -1045,16 +1045,93 @@ def _proc_cmdline(pid: int) -> Optional[str]:
     return raw.replace(b"\x00", b" ").decode("utf-8", "replace").strip() or None
 
 
-def _process_alive(pid: int) -> bool:
+# Liveness is TRI-STATE. "I could not determine" is not "dead" — see _process_liveness.
+LIVENESS_ALIVE = "alive"
+LIVENESS_DEAD = "dead"
+LIVENESS_UNKNOWN = "unknown"
+
+
+def _windows_liveness(pid: int) -> str:
+    """Ask Windows directly, via OpenProcess — never via os.kill.
+
+    PROCESS_QUERY_LIMITED_INFORMATION (0x1000) is the minimum right that answers
+    "does this pid exist", and it is grantable across sessions where the rights
+    os.kill needs are not. ERROR_ACCESS_DENIED means the process EXISTS and we may
+    not inspect it — that is ALIVE, not dead. ERROR_INVALID_PARAMETER means no such
+    pid. Anything else is UNKNOWN, never dead.
+    """
+    try:
+        import ctypes
+        from ctypes import wintypes
+    except Exception:                                  # noqa: BLE001
+        return LIVENESS_UNKNOWN
+    ERROR_ACCESS_DENIED, ERROR_INVALID_PARAMETER, STILL_ACTIVE = 5, 87, 259
+    try:
+        k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        handle = k32.OpenProcess(0x1000, False, pid)
+        if not handle:
+            err = ctypes.get_last_error()
+            if err == ERROR_ACCESS_DENIED:
+                return LIVENESS_ALIVE                  # exists; we just cannot look
+            if err == ERROR_INVALID_PARAMETER:
+                return LIVENESS_DEAD                   # no such pid
+            return LIVENESS_UNKNOWN
+        try:
+            code = wintypes.DWORD()
+            if not k32.GetExitCodeProcess(handle, ctypes.byref(code)):
+                return LIVENESS_UNKNOWN
+            return LIVENESS_ALIVE if code.value == STILL_ACTIVE else LIVENESS_DEAD
+        finally:
+            k32.CloseHandle(handle)
+    except Exception:                                  # noqa: BLE001
+        return LIVENESS_UNKNOWN
+
+
+def _process_liveness(pid: int) -> str:
+    """'alive' | 'dead' | 'unknown'.
+
+    >>> CARD #195 — `os.kill(pid, 0)` IS NOT A LIVENESS PROBE ON WINDOWS, AND ITS
+    FAILURE WAS BEING SWALLOWED INTO "DEAD". <<< Measured by workstation-lc against
+    a monitor that was demonstrably draining:
+
+        pid 6120 alive per Windows ................. True
+        os.kill(6120, 0) from another process ...... OSError [WinError 87]
+                                                     -> `except OSError: return False`
+        pid 6120 after the probe ................... STILL ALIVE
+
+    The error appears when probing a process the caller did NOT spawn — the worker
+    is a grandchild of a detached cmd.exe, a different session/handle-rights context.
+    His first throwaway test passed because he probed his own CHILD: a child-process
+    control cannot surface this, which is why it read safe.
+
+    ONE LINE PRODUCED BOTH SYMPTOMS: `monitor status` reported "not running" about
+    every healthy monitor, AND the single-instance guard believed nothing was
+    running, so it never blocked a second start. False negative and duplicate
+    spawning from the same swallow.
+
+    >>> THE RULE: "COULD NOT DETERMINE" MUST NEVER BE REPORTED AS "DEAD" BY A GUARD
+    WHOSE JOB IS TO PREVENT A SECOND START. <<< A blocked start is visible and
+    recoverable; a duplicate is silent and produces two writers over one cursor.
+    So callers treat UNKNOWN as occupied, and `status` says so rather than claiming
+    the process is running.
+    """
+    if sys.platform == "win32":
+        return _windows_liveness(pid)
     try:
         os.kill(pid, 0)
     except ProcessLookupError:
-        return False
+        return LIVENESS_DEAD
     except PermissionError:
-        return True            # exists, owned by another user
+        return LIVENESS_ALIVE       # exists, owned by another user
     except OSError:
-        return False
-    return True
+        return LIVENESS_UNKNOWN     # NOT dead — we simply could not tell
+    return LIVENESS_ALIVE
+
+
+def _process_alive(pid: int) -> bool:
+    """Back-compat bool. UNKNOWN counts as alive — see _process_liveness for why
+    treating an undetermined answer as "dead" is the failure mode, not the safe one."""
+    return _process_liveness(pid) in (LIVENESS_ALIVE, LIVENESS_UNKNOWN)
 
 
 def _terminate(pid: int) -> None:

{swarph_cli-0.40.3 → swarph_cli-0.41.1}/src/swarph_cli/gateway/server.py

@@ -76,7 +76,12 @@ 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")
+# No default host. This shipped for 79 releases with a hardcoded PRIVATE TAILNET address as
+# its fallback, so every public install pointed at one operator's box unless the deployer
+# happened to set the variable. Unroutable from outside, so never an access hole — but it
+# disclosed topology, and a default that silently targets someone else's host is wrong even
+# when it cannot be reached. Unset now means UNCONFIGURED, which is the honest state.
+GATEWAY_GBRAIN_URL = os.environ.get("GATEWAY_GBRAIN_URL", "")
 GATEWAY_GBRAIN_TOKEN = os.environ.get("GATEWAY_GBRAIN_TOKEN", "")
 
 # B1 Meta-Edge identity (META_EDGE_IDENTITY_CONTRACT.md). Meta-Edge SSO ISSUES
@@ -4219,6 +4224,15 @@ 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)."""
+    if not GATEWAY_GBRAIN_URL:
+        # Named, not incidental. Removing the hardcoded default turned "unconfigured"
+        # into a reachable state for the first time, and an empty URL would otherwise
+        # surface as a urllib ValueError — a transport error for a CONFIGURATION fault,
+        # which sends the reader looking at the network instead of their env.
+        raise RuntimeError(
+            "GATEWAY_GBRAIN_URL is not set — the brain proxy is UNCONFIGURED, not "
+            "unreachable. Set it to your gbrain MCP endpoint. (Releases up to 0.41.0 "
+            "silently defaulted to one operator's private host; that default is gone.)")
     body = {"jsonrpc": "2.0", "id": 1, "method": "tools/call",
             "params": {"name": "query",
                        "arguments": {"query": question, "limit": limit, "expand": False}}}

{swarph_cli-0.40.3 → swarph_cli-0.41.1}/src/swarph_cli/main.py

@@ -84,6 +84,7 @@ _VERB_HANDLERS: dict[str, str] = {
     "spawn": "swarph_cli.commands.spawn.run_spawn",
     "install-hook": "swarph_cli.commands.install_hook.run_install_hook",
     "hook-output": "swarph_cli.commands.hook_output.run_hook_output",
+    "codegraph-hook": "swarph_cli.commands.codegraph_hook.run_codegraph_hook",
     "watchdog": "swarph_cli.commands.watchdog.run_watchdog",
     "hooks": "swarph_cli.commands.hooks.run_hooks",
     "protocol-handler": "swarph_cli.commands.protocol_handler.run_protocol_handler",