swarph-cli 0.48.2__tar.gz → 0.49.1__tar.gz

{swarph_cli-0.48.2/src/swarph_cli.egg-info → swarph_cli-0.49.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.48.2
+Version: 0.49.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`, per-invocation `gh` identity routing, a silent DM-wake hook, session `import`, and a stranded-session `watchdog`.
 Author: Pierre Samson, Claude Opus
 License: MIT
@@ -29,7 +29,7 @@ Requires-Dist: PyYAML>=6.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.0; extra == "mcp"
+Requires-Dist: mcp<2,>=1.0; extra == "mcp"
 Provides-Extra: bench
 Requires-Dist: google-genai>=0.3; extra == "bench"
 Provides-Extra: mistral
@@ -356,7 +356,7 @@ The load-bearing piece is **billing-scrub**: the subprocess env has every known
 
 ### `swarph channel` / `swarph schedule` / `swarph lane`
 
-The gateway's **automation control plane** — channels (pub/sub), scheduled events, and the $0-lane orchestration — as first-class client verbs. They share `mesh`'s auth: identity is `--as` / `SWARPH_SELF`, the bearer is `--token-file` / `MESH_GATEWAY_TOKEN` / the peer-token file, and `--gateway` (default `http://localhost:8788`) points at the hub.
+The gateway's **automation control plane** — channels (pub/sub), scheduled events, and the $0-lane orchestration — as first-class client verbs. They share `mesh`'s auth: identity is `--as` / `SWARPH_SELF`, the bearer is `--token-file` / `MESH_GATEWAY_TOKEN` / the peer-token file, and `--gateway` / `MESH_GATEWAY_URL` points at the hub. **There is no default host** — swarph ships none, and an unconfigured call refuses with an actionable message rather than dialling somewhere (#578).
 
 ```bash
 # channels — converge work into pub/sub rooms

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/README.md

@@ -308,7 +308,7 @@ The load-bearing piece is **billing-scrub**: the subprocess env has every known
 
 ### `swarph channel` / `swarph schedule` / `swarph lane`
 
-The gateway's **automation control plane** — channels (pub/sub), scheduled events, and the $0-lane orchestration — as first-class client verbs. They share `mesh`'s auth: identity is `--as` / `SWARPH_SELF`, the bearer is `--token-file` / `MESH_GATEWAY_TOKEN` / the peer-token file, and `--gateway` (default `http://localhost:8788`) points at the hub.
+The gateway's **automation control plane** — channels (pub/sub), scheduled events, and the $0-lane orchestration — as first-class client verbs. They share `mesh`'s auth: identity is `--as` / `SWARPH_SELF`, the bearer is `--token-file` / `MESH_GATEWAY_TOKEN` / the peer-token file, and `--gateway` / `MESH_GATEWAY_URL` points at the hub. **There is no default host** — swarph ships none, and an unconfigured call refuses with an actionable message rather than dialling somewhere (#578).
 
 ```bash
 # channels — converge work into pub/sub rooms

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.48.2"
+version = "0.49.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`, per-invocation `gh` identity routing, a silent DM-wake hook, session `import`, and a stranded-session `watchdog`."
 readme = "README.md"
 license = { text = "MIT" }
@@ -65,7 +65,9 @@ dev = ["pytest>=7.0"]
 # toolbelt (swarph_search/add/describe) to any MCP host. The SDK is an extra
 # so the core one-shot/mesh paths don't pull it in; `swarph mcp-server`
 # prints a `pip install swarph-cli[mcp]` hint when it's absent.
-mcp = ["mcp>=1.0"]
+# mcp 2.0 removed mcp.server.fastmcp (FastMCP left the SDK package); the
+# mcp-server command is written against the 1.x API — pin below 2.
+mcp = ["mcp>=1.0,<2"]
 # `swarph bench run` (metered backend) calls the google-genai Developer API
 # directly. The dependency is an extra so `bench`'s pack loader/validate/
 # distance-engine paths (and every other swarph-cli verb) stay usable without
@@ -121,7 +123,8 @@ where = ["src"]
 # tree and fails on every installed wheel -- the 0.39.3 bug above, again.
 swarph_cli = ["systemd/*.service", "systemd/*.timer", "systemd/*.default",
               "scripts/*.sh", "scripts/*.ps1", "guide/*.md",
-              "payloads/postcompact/*.sh", "payloads/postcompact/*.cmd"]
+              "payloads/postcompact/*.sh", "payloads/postcompact/*.cmd",
+    "skills/*/SKILL.md", "skills/*/LICENSE"]
 # v0.15: ship the bundled mesh-gateway schema so `swarph gateway serve`
 # can apply it at startup via MESH_SCHEMA_PATH (defaults next to server.py).
 "swarph_cli.gateway" = ["*.sql"]

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/src/swarph_cli/__init__.py

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

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/src/swarph_cli/commands/add.py

@@ -672,19 +672,79 @@ BUILTIN_SKILLS: dict = {
 }
 
 
+#: Skills shipped as PACKAGE DATA rather than as a Python string constant.
+#:
+#: `swarph-intro` is a ~10-line str literal and that is fine. A 176-line skill
+#: embedded in source is not: it cannot be diffed against its upstream, and the
+#: two copies drift silently — which is the same failure `i-have-adhd`'s own
+#: upstream guards against with a CI check that the `.cursor/` mirror matches.
+#:
+#: Maps skill name -> (description, files-under-src/swarph_cli/skills/<name>/).
+_PACKAGED_SKILLS: dict = {
+    "i-have-adhd": (
+        "Shape output for a reader with ADHD: lead with the next action, number "
+        "multi-step work, restate state across turns, suppress tangents, make "
+        "wins visible. Vendored from ayghri/i-have-adhd (MIT) with swarph's "
+        "rule 0 (act, do not announce). Invoke with /i-have-adhd.",
+        ("SKILL.md", "LICENSE"),
+    ),
+}
+
+#: Where packaged skill files live inside the installed package.
+_PACKAGED_SKILLS_DIR = Path(__file__).resolve().parent.parent / "skills"
+
+
+def _resolve_packaged_skill(name: str) -> SkillBundle:
+    """Build a :class:`SkillBundle` by READING the packaged files.
+
+    >>> READ AT RESOLVE TIME, NOT AT IMPORT. <<< A module-level constant is
+    evaluated when the package is imported, so a missing or unreadable data file
+    would make `swarph --help` fail rather than `swarph add` fail. #578 is the
+    same lesson from the other direction: nothing that can fail belongs at import.
+
+    Raises :class:`FileNotFoundError` naming the absent file — which is the
+    honest error for a wheel that did not ship its own package data, a failure
+    this repo has had before (see the release checklist: a new module silently
+    does not ship).
+    """
+    description, filenames = _PACKAGED_SKILLS[name]
+    files = []
+    for relpath in filenames:
+        src = _PACKAGED_SKILLS_DIR / name / relpath
+        if not src.is_file():
+            raise FileNotFoundError(
+                f"packaged skill {name!r} is missing {relpath!r} at {src} — the "
+                f"wheel did not ship its package data; this is a packaging bug, "
+                f"not a user error"
+            )
+        files.append((relpath, src.read_text(encoding="utf-8")))
+    return SkillBundle(
+        name=name,
+        description=description,
+        publisher=_BUILTIN_PUBLISHER,
+        trust="builtin",
+        files=tuple(files),
+    )
+
+
 def resolve_builtin_skill(name: str) -> SkillBundle:
     """Return the bundled :class:`SkillBundle` named ``name``.
 
+    Two sources, one namespace: :data:`BUILTIN_SKILLS` (string constants) and
+    :data:`_PACKAGED_SKILLS` (files shipped as package data). A caller cannot
+    tell them apart and should not need to.
+
     Raises :class:`ValueError` (listing the available names) for an unknown
     name — propagated to the CLI layer, which surfaces it; nothing installed.
     """
-    try:
+    if name in BUILTIN_SKILLS:
         return BUILTIN_SKILLS[name]
-    except KeyError:
-        available = ", ".join(sorted(BUILTIN_SKILLS))
-        raise ValueError(
-            f"unknown builtin skill {name!r}; available: {available}"
-        ) from None
+    if name in _PACKAGED_SKILLS:
+        return _resolve_packaged_skill(name)
+    available = ", ".join(sorted({*BUILTIN_SKILLS, *_PACKAGED_SKILLS}))
+    raise ValueError(
+        f"unknown builtin skill {name!r}; available: {available}"
+    ) from None
 
 
 def _install_skill_files(skills_home, name: str, files) -> None:

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/src/swarph_cli/commands/brain_ask.py

@@ -10,7 +10,7 @@ verb so any cell can search the swarm's shared memory the same way. Two modes:
 Stdlib-only. Config from the environment, mirroring ``swarph mesh``'s token model:
 
   GBRAIN_MCP_URL        gbrain MCP endpoint; falls back to SWARPH_BRAIN_MCP, else
-    / SWARPH_BRAIN_MCP   http://100.107.222.72:8792/mcp (tailnet IP — gbrain
+    / SWARPH_BRAIN_MCP   http://<gbrain-host>:8792/mcp (no default — gbrain
                           binds no loopback; measured 2026-08-23, card #548)
   GBRAIN_TOKEN          read token; falls back to SWARPH_BRAIN_TOKEN, then to the
     / SWARPH_BRAIN_TOKEN  mesh per-peer token (~/.config/swarph/<self>.peer_token).
@@ -35,23 +35,34 @@ from swarph_cli import tokens
 from pathlib import Path
 from typing import Optional
 
-# TAILNET IP, NOT loopback (card #548): measured 2026-08-23, gbrain binds
-# 100.107.222.72:8792 ONLY — 127.0.0.1:8792 refuses on the gateway box itself.
-# A loopback default is deaf everywhere, including on the box running gbrain.
-_DEFAULT_GBRAIN = "http://100.107.222.72:8792/mcp"
+# NO MODULE-LEVEL ENDPOINT CONSTANT, ON PURPOSE. gbrain binds its tailnet IP
+# only (127.0.0.1:8792 refuses even on gbrain's own box), so SWARPH_BRAIN_MCP must
+# be set explicitly and no host ships as a default (#548 -> #578).
+# `_DEFAULT_GBRAIN = os.environ.get("SWARPH_BRAIN_MCP")` used to live here and was
+# read at IMPORT time, which froze the developer's shell into the module:
+# MEASURED in seat-A review of PR #318 — with SWARPH_BRAIN_MCP exported,
+# test_resolve_endpoint_refuses_rather_than_guessing_a_host FAILED, because the
+# test can delenv the two call-time operands but not a value already captured.
+# The env is read at CALL time in _resolve_endpoint below, and nowhere else.
 _DEFAULT_TOPK = 6
 
 
-def _resolve_endpoint() -> str:
-    """Endpoint precedence: GBRAIN_MCP_URL > SWARPH_BRAIN_MCP > tailnet default.
+def _resolve_endpoint(explicit: str | None = None) -> str:
+    """Endpoint precedence: GBRAIN_MCP_URL > SWARPH_BRAIN_MCP. No host default (#578).
 
     The SWARPH_BRAIN_MCP fallback keeps the verb config-compatible with the
     standalone ``swarph-brain-ask`` script (which reads SWARPH_BRAIN_*), so one
     env config works with both.
     """
-    return (os.environ.get("GBRAIN_MCP_URL")
-            or os.environ.get("SWARPH_BRAIN_MCP")
-            or _DEFAULT_GBRAIN)
+    from swarph_cli.gateway_default import require_gateway
+
+    return require_gateway(
+        explicit
+        or os.environ.get("GBRAIN_MCP_URL")
+        or os.environ.get("SWARPH_BRAIN_MCP"),
+        env="SWARPH_BRAIN_MCP",
+        what="gbrain MCP",
+    )
 
 
 def _build_query_request(question: str, limit: int = _DEFAULT_TOPK) -> dict:
@@ -237,10 +248,15 @@ def run_brain_ask(argv: list) -> int:
                         help="top-k chunks to retrieve (default 6)")
     parser.add_argument("--no-synth", action="store_true",
                         help="retrieval only — print raw chunks, skip prose synthesis")
-    parser.add_argument("--gateway", default=_resolve_endpoint(),
+    parser.add_argument("--gateway", default=None,
                         help="gbrain MCP endpoint (env: GBRAIN_MCP_URL or SWARPH_BRAIN_MCP)")
     parser.add_argument("--token-file", default=None, help="explicit read-token file")
     args = parser.parse_args(argv)
+    # #578/#318-review: resolve the endpoint HERE, not as an argparse default.
+    # Evaluating it at parser-BUILD time made `--help` die and made the
+    # `--gateway` the error message tells you to pass unreachable, because the
+    # parser never got as far as parsing it. Same pattern as ratify:173.
+    args.gateway = _resolve_endpoint(args.gateway)
     question = " ".join(args.question)
 
     gw = os.environ.get("SWARPH_BRAIN_GATEWAY")

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/src/swarph_cli/commands/cell_selfcheck.py

@@ -290,14 +290,20 @@ def unit_is_relevant(name: str, text: str) -> bool:
 # cost of the circularity break, stated here rather than discovered.
 
 # TAILNET IP, NOT localhost and NOT a MagicDNS name (commander, 2026-08-21).
-# The mesh-gateway binds HOST=100.107.222.72 ONLY; localhost has never been bound.
+# The mesh-gateway binds a tailnet IP ONLY; localhost has never been bound.
 # MESH_GATEWAY_URL overrides — the escape hatch for anyone outside this mesh.
-_RESOLVER_DEFAULT_GATEWAY = os.environ.get("MESH_GATEWAY_URL", "http://100.107.222.72:8788")
+# Inlined, NOT imported from swarph_cli.gateway_default: this module is
+# deliberately stdlib-only so it can run as a bare file in isolated mode
+# (test_module_imports_are_stdlib_only). Same policy as #578, no import.
+# NO import-time capture of os.environ here either: `_RESOLVER_DEFAULT_GATEWAY =
+# os.environ.get("MESH_GATEWAY_URL")` used to back this resolver, which made the
+# answer depend on the shell that IMPORTED the module rather than the env passed
+# in. The env is the ARGUMENT — see #578's "model the environment as data".
 
 
 def resolver_gateway(env: dict) -> str:
-    """What the CLI would use: $MESH_GATEWAY_URL, else the localhost default."""
-    return (env.get("MESH_GATEWAY_URL") or "").strip() or _RESOLVER_DEFAULT_GATEWAY
+    """What the CLI would use: $MESH_GATEWAY_URL, else "" — no host ships (#578)."""
+    return (env.get("MESH_GATEWAY_URL") or "").strip()
 
 
 def resolver_token(self_name: str, env: dict, home: Path) -> tuple[Optional[str], str]:

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/src/swarph_cli/commands/codegraph.py

@@ -245,8 +245,8 @@ def _resolve_gateway(arg) -> str:
 
         SWARPH_CODEGRAPH_GATEWAY   <unset>
         SWARPH_GATEWAY             <unset>
-        SWARPH_BRAIN_GATEWAY       http://100.107.222.72:8788   <- brain-NAMED, MESH value
-        MESH_GATEWAY_URL           http://100.107.222.72:8788   <- correct, and NOT consulted
+        SWARPH_BRAIN_GATEWAY       http://<host>:8788   <- brain-NAMED, MESH value
+        MESH_GATEWAY_URL           http://<host>:8788   <- correct, and NOT consulted
 
     The relay worked ONLY because a brain-named variable was mis-set to the mesh
     gateway's address. Every link that resolved was unset or wrong-by-name, and the

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/src/swarph_cli/commands/codegraph_hook.py

@@ -36,8 +36,8 @@ import urllib.error
 import urllib.request
 from pathlib import Path
 from typing import Optional
+from swarph_cli.gateway_default import env_gateway
 
-DEFAULT_GATEWAY = os.environ.get("MESH_GATEWAY_URL", "http://100.107.222.72:8788")
 TIMEOUT_S = 6
 MAX_ROWS = 6
 
@@ -131,6 +131,14 @@ def query_gateway(term: str, gateway: str, token: str, limit: int = MAX_ROWS) ->
     >>> AN UNREACHABLE OR REFUSING BACKEND IS AN ERROR, NOT AN EMPTY RESULT. <<<
     Collapsing them is the defect this hook exists to avoid teaching.
     """
+    # #578: with no baked-in host, `gateway` can be "". Request() rejects a
+    # relative URL at CONSTRUCTION (below, outside the try), so an unconfigured
+    # backend would raise ValueError and take the whole turn down — against this
+    # entry point's "ALWAYS exits 0, must never fail a turn" contract.
+    # UNCONFIGURED is the same class as UNREACHABLE: an error, not empty.
+    if not (gateway or "").strip():
+        return {"error": "MESH_GATEWAY_URL is not set and swarph ships no default "
+                         "gateway host (#578) — the graph was never asked"}
     req = urllib.request.Request(
         f"{gateway.rstrip('/')}/codegraph",
         data=json.dumps({"query": term, "limit": limit}).encode(),
@@ -228,7 +236,7 @@ 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
+    gateway = env_gateway()
     for i, a in enumerate(argv):
         if a == "--as" and i + 1 < len(argv):
             self_name = argv[i + 1]

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/src/swarph_cli/commands/daemon.py

@@ -52,6 +52,7 @@ from typing import Optional
 from swarph_cli import session_bridge, stall_alert
 from swarph_cli.console_safe import print_safe
 from swarph_cli.delivery_queue import DeliveryQueue
+from swarph_cli.gateway_default import env_gateway, require_gateway
 
 
 _DEFAULT_POLL_S = 30
@@ -85,7 +86,7 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     p.add_argument(
         "--gateway",
-        default=os.environ.get("MESH_GATEWAY_URL", "http://100.107.222.72:8788"),
+        default=env_gateway(),
         help="mesh-gateway base URL.",
     )
     p.add_argument(
@@ -564,6 +565,10 @@ def run_daemon(argv: list[str]) -> int:
     state_dir.mkdir(parents=True, exist_ok=True)
     # Announce ownership of this state dir BEFORE any cursor work, so a
     # concurrently-starting `swarph monitor` sees it and refuses (PR #139).
+    # #578: identity is resolved above first, so a missing --self reports THAT,
+    # not a missing env var. The gateway is only needed for the requests below.
+    args.gateway = require_gateway(getattr(args, "gateway", ""))
+
     _write_daemon_pidfile(state_dir)
     token = _resolve_token(args.token_file)
     if not token:

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/src/swarph_cli/commands/event.py

@@ -67,9 +67,12 @@ def _post_channel(
     """
     name = resolve_self_name(self_name)
     token = resolve_token(name, token_file)
-    from .mesh import _DEFAULT_GATEWAY
+    from swarph_cli.gateway_default import env_gateway
 
-    base = (gateway or _DEFAULT_GATEWAY).rstrip("/")
+    # "" when unconfigured — post_json IS mesh._post_json, whose
+    # _require_absolute_gateway_url then refuses by name rather than raising
+    # `ValueError: unknown url type` from Request(). Checked in review of #318.
+    base = (gateway or env_gateway()).rstrip("/")
     ev: dict = {"event": event, "payload": payload}
     if chain_token is not None:  # carry an explicit "" through; only omit when unset
         ev["chain_token"] = chain_token

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/src/swarph_cli/commands/init.py

@@ -22,8 +22,8 @@ import yaml
 
 from swarph_shared.cell import PEER_NAME_RE, parse_cell_dict
 from swarph_cli.cell import CLI_ENABLED_PROVIDERS, CellError, cells_dir
+from swarph_cli.gateway_default import env_gateway
 
-_DEFAULT_GATEWAY = os.environ.get("MESH_GATEWAY_URL", "http://100.107.222.72:8788")
 _CODEX_SANDBOX_DEFAULT = "workspace-write"
 _CODEX_SANDBOX_VALUES = ("workspace-write", "read-only")
 
@@ -128,7 +128,7 @@ def _build_parser() -> argparse.ArgumentParser:
     p.add_argument("--tmux", default=None)
     p.add_argument("--cursor", default=None)
     p.add_argument("--sandbox", default=None)
-    p.add_argument("--gateway", default=_DEFAULT_GATEWAY)
+    p.add_argument("--gateway", default=env_gateway())
     p.add_argument("--assisted-memory", dest="assisted_memory", default=None, metavar="REPO",
                    help="enable git-backed memory at REPO (SSH→HTTPS normalized)")
     p.add_argument("--starter", default=None)
@@ -197,8 +197,11 @@ def run_init(argv: list[str]) -> int:
         "cwd": str(cwd),
         "tmux_session": tmux,
         "cursor_path": cursor,
-        "mesh": {"gateway": args.gateway},
     }
+    # Only when one was actually chosen: with the env unset args.gateway is ""
+    # (#578 ships no host), and writing that records a decision nobody made.
+    if args.gateway:
+        cell["mesh"] = {"gateway": args.gateway}
     if sandbox is not None:
         cell["sandbox"] = sandbox
     if args.starter:

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/src/swarph_cli/commands/mesh.py

@@ -39,6 +39,7 @@ from typing import Optional
 from .. import tokens
 from ._content import ContentError, add_content_args, resolve_content
 from ._display import sanitize_terminal
+from swarph_cli.gateway_default import GatewayNotConfigured, env_gateway
 
 
 def _format_inbox_line(dm: dict) -> str:
@@ -51,17 +52,13 @@ def _format_inbox_line(dm: dict) -> str:
     return f"id={dm.get('id')} {read} from={who} kind={kind} {content}"
 
 
-# TAILNET IP, NOT localhost and NOT a MagicDNS name (commander, 2026-08-21).
-# The mesh-gateway binds HOST=100.107.222.72 ONLY — localhost has never been bound, so this
-# default failed as a bare "Connection refused" with no cause named. It cost 792 silent
-# card-export failures over 8 days, and it turned a WORKING hand-started monitor into a
-# DEAF SUPERVISED one the moment it was moved to a systemd unit (the unit passes no
-# --gateway, so it fell through to this constant).
-# An IP over MagicDNS on purpose: a name needs MagicDNS enabled, the right search domain,
-# and no local collision; the IP needs only that tailscale is up, which is the real
-# precondition anyway. MESH_GATEWAY_URL overrides it — that env var is the escape hatch
-# for anyone outside this mesh, and optional inside it.
-_DEFAULT_GATEWAY = os.environ.get("MESH_GATEWAY_URL", "http://100.107.222.72:8788")
+# NO MODULE-LEVEL GATEWAY CONSTANT (#578). #546 put the gateway's tailnet IP here,
+# correctly at the time; that box was retired 2026-08-25 and the literal expired.
+# The constant is gone rather than emptied: read at IMPORT time it captured whatever
+# the packaging/importing shell exported, and MEASURED in seat-A review of PR #318 it
+# still returned that value after the environment was cleared — the one channel by
+# which a test could depend on a developer's shell. env_gateway() is called at
+# parser-BUILD time instead (parsers are built per invocation).
 _DEFAULT_POLL_S = 30
 _BACKOFF_EMPTY_THRESHOLD = 5
 _BACKOFF_EMPTY_SECONDS = 60
@@ -170,7 +167,7 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     peers.add_argument(
         "--gateway",
-        default=os.environ.get("MESH_GATEWAY_URL", _DEFAULT_GATEWAY),
+        default=env_gateway(),
         help="mesh-gateway base URL",
     )
     peers.add_argument("--token-file", default=None, help="explicit bearer token file")
@@ -200,7 +197,7 @@ def _add_common(p: argparse.ArgumentParser) -> None:
     )
     p.add_argument(
         "--gateway",
-        default=os.environ.get("MESH_GATEWAY_URL", _DEFAULT_GATEWAY),
+        default=env_gateway(),
         help="mesh-gateway base URL",
     )
     p.add_argument("--token-file", default=None, help="explicit bearer token file")
@@ -313,12 +310,69 @@ def _resolve_token(
     )
     if res is not None:
         return res.token
+    # #579: the old message named the very file `register` exists to MINT, which
+    # reads as a chicken-and-egg to anyone bootstrapping a NEW peer (droplet hit
+    # exactly this onboarding friendly-coder, 2026-08-25). `swarph onboard`
+    # already explains the operator path; this now says the same thing.
+    #
+    # >>> THE BOOTSTRAP PARAGRAPH BELONGS TO `register` ALONE. <<< It first shipped
+    # unconditionally, so `mesh send`/`reply`/`inbox`/`sidecar` — which all reach here
+    # with the default allow_peer_token=True — told a user with a missing token that
+    # "minting it is what this command does", which is FALSE for send. Measured in
+    # seat-A review of PR #318. allow_peer_token=False is exactly the register path
+    # (:848 is its only caller), so it is the condition, not a new flag.
+    bootstrap = (
+        f"\n"
+        f"  If you are BOOTSTRAPPING {self_name!r}, that token does not exist yet:\n"
+        f"  minting it is what this command does, so it cannot also be the way in.\n"
+        f"  Registering a peer that is not yourself is an OPERATOR action. Where the\n"
+        f"  gateway enforces caller binding (MESH_CALLER_BINDING_ENFORCE=1, as this\n"
+        f"  mesh's does) another cell's per-peer token 403s; where it does not, it is\n"
+        f"  simply the wrong credential. `swarph gateway serve` does NOT enforce it by\n"
+        f"  default — do not read the 403 as a guarantee.\n"
+        f"      swarph mesh register --as {self_name} --token-file <operator-token>\n"
+        f"      MESH_GATEWAY_TOKEN=<operator-token> swarph mesh register --as {self_name}"
+    ) if not allow_peer_token else (
+        f"\n"
+        f"  If it does not exist yet, {self_name!r} has no credential on this mesh —\n"
+        f"  `swarph mesh register` (an OPERATOR action) is what mints one."
+    )
     raise RuntimeError(
-        "cannot resolve mesh token; set MESH_GATEWAY_TOKEN or create "
-        f"{_peer_token_path(self_name)}"
+        f"cannot resolve a mesh credential for {self_name!r}.\n"
+        f"\n"
+        f"  looked for:  ${{MESH_GATEWAY_TOKEN}}\n"
+        f"               {_peer_token_path(self_name)}\n"
+        f"\n"
+        f"  If {self_name!r} ALREADY EXISTS, its per-peer token is the right\n"
+        f"  credential — place it at the path above (mode 600) and re-run.\n"
+        + bootstrap
     )
 
 
+
+def _require_absolute_gateway_url(url: str) -> None:
+    """#578: no gateway host ships as a default.
+
+    Guarding here rather than at the dispatcher is deliberate: the gateway is
+    needed only when a REQUEST is made. A dispatcher-level check also fired for
+    paths that never touch the network (sidecar target validation, --json shape
+    tests) and turned 10 failures into 26. The observable that means
+    "unconfigured" is a url that is not absolute — `/peers` instead of
+    `http://host:8788/peers` — so key on that.
+    """
+    if not str(url).startswith(("http://", "https://")):
+        # GatewayNotConfigured (a RuntimeError) rather than a bare RuntimeError:
+        # cli used to carry TWO refusal shapes for one variable and one remedy —
+        # require_gateway at dispatch and this one at request time — so the package
+        # disagreed with itself about what "no gateway" raises. One family now.
+        raise GatewayNotConfigured(
+            "MESH_GATEWAY_URL is not set, and swarph ships no default gateway host.\n"
+            "  A baked-in address expires the day that box is retired "
+            "(card #578; it happened on 2026-08-25).\n"
+            "  Set MESH_GATEWAY_URL=http://<host>:<port>, or pass --gateway.\n"
+            f"  (tried to request {url!r})"
+        )
+
 def _post_json(
     url: str,
     body: dict,
@@ -326,6 +380,7 @@ def _post_json(
     *,
     timeout: float = 10.0,
 ) -> tuple[int, dict]:
+    _require_absolute_gateway_url(url)
     data = json.dumps(body).encode("utf-8")
     req = urllib.request.Request(
         url,
@@ -355,6 +410,7 @@ def _http_get_json(
     *,
     timeout: float = 10.0,
 ) -> tuple[int, dict]:
+    _require_absolute_gateway_url(url)
     req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
     try:
         with urllib.request.urlopen(req, timeout=timeout) as resp:

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/src/swarph_cli/commands/monitor.py

@@ -43,6 +43,8 @@ import sys
 import time
 from pathlib import Path
 
+from swarph_cli.gateway_default import env_gateway
+
 from . import mesh
 
 
@@ -122,7 +124,7 @@ def _add_common(p: argparse.ArgumentParser) -> None:
     p.add_argument("--state-dir", default=None, help="state directory")
     p.add_argument(
         "--gateway",
-        default=os.environ.get("MESH_GATEWAY_URL", mesh._DEFAULT_GATEWAY),
+        default=env_gateway(),
         help="mesh-gateway base URL",
     )
     p.add_argument("--token-file", default=None, help="explicit bearer token file")

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/src/swarph_cli/commands/onboard.py

@@ -35,6 +35,7 @@ from pathlib import Path
 from typing import Optional
 from swarph_cli import tokens
 from swarph_cli.console_safe import print_safe
+from swarph_cli.gateway_default import env_gateway, require_gateway
 
 
 _HANDSHAKE_TEMPLATE = """\
@@ -111,8 +112,8 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     p.add_argument(
         "--gateway",
-        default=os.environ.get("MESH_GATEWAY_URL", "http://100.107.222.72:8788"),
-        help="mesh-gateway base URL (default: $MESH_GATEWAY_URL or http://100.107.222.72:8788)",
+        default=env_gateway(),
+        help="mesh-gateway base URL (default: $MESH_GATEWAY_URL; no host is shipped)",
     )
     p.add_argument(
         "--token-file",
@@ -824,6 +825,9 @@ def run_onboard(argv: list[str]) -> int:
 
     # ── Step 4: POST /peers/register ─────────────────────────────────
     peer_url = args.url or f"http://{canonical}:8787"
+    # #578: the gateway is needed only for the REQUEST. Validate args first so a
+    # typo'd name reports the typo, not a missing env var.
+    args.gateway = require_gateway(getattr(args, "gateway", ""))
     print_safe(f"[4/6] POST {args.gateway}/peers/register")
     # >>> #124's GUARD, MET CLIENT-SIDE — #294's PATTERN, THE MISSING HALF. <<<
     # The gateway 409s a re-register whose payload would DROP stored

{swarph_cli-0.48.2 → swarph_cli-0.49.1}/src/swarph_cli/commands/ratify.py

@@ -26,6 +26,7 @@ import urllib.error
 import urllib.request
 from pathlib import Path
 from typing import Optional
+from swarph_cli.gateway_default import env_gateway, require_gateway
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -57,7 +58,7 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     p.add_argument(
         "--gateway",
-        default=os.environ.get("MESH_GATEWAY_URL", "http://100.107.222.72:8788"),
+        default=env_gateway(),
         help="mesh-gateway base URL.",
     )
     p.add_argument(
@@ -167,6 +168,9 @@ def run_ratify(argv: list[str]) -> int:
         return 1
 
     # ── Step 2: caller-side gate (witness must itself be ratified) ───
+    # #578: the gateway is needed only for the REQUEST. Arg validation above runs
+    # first, so a bad name reports the bad name, not a missing env var.
+    args.gateway = require_gateway(getattr(args, "gateway", ""))
     print(f"[2/6] verify witness {witness!r} is ratified")
     status, witness_body = _http_json(
         f"{args.gateway}/peers/{witness}", token=token