swarph-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{swarph_cli-0.4.0/src/swarph_cli.egg-info → swarph_cli-0.5.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.4.0
-Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.4.0 ships Phase 5.5 `swarph onboard` + `swarph ratify` on top of Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL (PLAN.md §13 / §15).
+Version: 0.5.0
+Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.5.0 ships Phase 5.6 `swarph daemon` (foreground inbox drain — retires the orphaned-tail-F class) on top of Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify (PLAN.md §13 / §16).
 Author: Pierre Samson, Claude Opus
 License: MIT
 Project-URL: Homepage, https://github.com/darw007d/swarph-cli
@@ -49,15 +49,38 @@ This is one of three repos in the v0.3.x architecture:
 
 ## Status
 
-**v0.4.0 — Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify.** Five verbs ship:
+**v0.5.0 — Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify + Phase 5.6 daemon.** Six verbs ship:
 
 1. `swarph "prompt"` — Phase 2 one-shot mode (any of five providers)
 2. `swarph chat` — Phase 5 interactive REPL with multi-turn history + slash commands
 3. `swarph import <path>` — Phase 2.5 session import (Claude JSONL → swarph-native, with `--report-only` for honest pre-commit inspection)
-4. `swarph onboard <peer-name>` — **NEW** Phase 5.5 mechanics-phase onboarding (PLAN.md §15.4)
-5. `swarph ratify <peer-name>` — **NEW** Phase 5.5 witness ratification (PLAN.md §15.4a)
+4. `swarph onboard <peer-name>` — Phase 5.5 mechanics-phase onboarding (PLAN.md §15.4)
+5. `swarph ratify <peer-name>` — Phase 5.5 witness ratification (PLAN.md §15.4a)
+6. `swarph daemon` — **NEW** Phase 5.6 foreground inbox drain loop (PLAN.md §16); structurally retires the orphaned-tail-F class
 
-Subsequent phases extend the CLI surface (`--ask <peer>`, daemon).
+Subsequent phases extend the CLI surface (`--ask <peer>`, REPL drain coroutine + `/inbox` + `/reply` slash commands in 5.6b).
+
+### `swarph daemon` (Phase 5.6)
+
+Replaces the 4-layer `tail -F | grep | Monitor | systemd | cron poll` stack with one foreground process. Liveness check collapses to:
+
+```bash
+ps aux | grep '[s]warph daemon'   # zero output = monitoring is down
+```
+
+```bash
+$ swarph daemon --state-dir ~/swarph_state/lab-ovh --self lab-ovh
+[swarph-daemon] starting: self=lab-ovh gateway=http://localhost:8788 poll=30s ...
+[2026-05-08T21:00:30Z] id=728 from=droplet kind=answer → 'Drop review on Phase 5.5 PRs A+B...'
+[2026-05-08T21:01:10Z] id=729 from=droplet kind=fyi → 'Both Phase 5.5 PRs merged...'
+^C
+[swarph-daemon] signal 2 received — draining + flushing cursor
+[swarph-daemon] shutdown: iterations=12 dms_seen=2 cursor.last_msg_id=729
+```
+
+Loud-on-down (PLAN §16.5): never silently exits. Cursor writes are atomic (write-and-rename — corrupted mid-flush leaves the previous cursor intact). Backoff: 60s after 5 consecutive empty polls; 300s after 5 min of consecutive 5xx. SIGINT/SIGTERM trigger clean drain + flush.
+
+`--auto-act` flag is documented for v0.5.1+ when handler registration via `@swarph.on_dm(...)` lands; v0.5.0 ships surface-only mode (DMs printed + JSONL-logged to `inbox.log`, no automatic replies).
 
 ### `swarph onboard` + `swarph ratify` (Phase 5.5)
 
@@ -191,9 +214,10 @@ Pong!
 | **2** (v0.1.0) | One-shot mode: `swarph "hello" --provider gemini` |
 | **2.5** (v0.2.0) | `swarph import` — Claude JSONL → swarph-native session format |
 | **5** (v0.3.0) | `swarph chat` interactive REPL — multi-turn against any of five adapters + slash commands |
-| **5.5** (v0.4.0 — this release) | **`swarph onboard <peer-name>` + `swarph ratify <peer-name>`** — six mechanics steps + handshake template + witness flip (PLAN.md §15) |
+| **5.5** (v0.4.0) | `swarph onboard` + `swarph ratify` — six mechanics steps + handshake template + witness flip (PLAN.md §15) |
+| **5.6** (v0.5.0 — this release) | **`swarph daemon`** — foreground inbox drain loop with atomic cursor writes; retires the orphaned-tail-F class (PLAN.md §16) |
+| **5.6b** | REPL drain coroutine + `/inbox`/`/reply` slash commands + `@swarph.on_dm()` handler registration (mesh + cli) |
 | **3** | `--ask <peer>` mesh-aware one-shot via MeshClient |
-| **5.6** | `swarph daemon` foreground drain loop + REPL drain coroutine + `/inbox`, `/reply` (PLAN.md §16) |
 | **6** | (already done) PyPI publish |
 
 ## Why split CLI from substrate

{swarph_cli-0.4.0 → swarph_cli-0.5.0}/README.md

@@ -17,15 +17,38 @@ This is one of three repos in the v0.3.x architecture:
 
 ## Status
 
-**v0.4.0 — Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify.** Five verbs ship:
+**v0.5.0 — Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify + Phase 5.6 daemon.** Six verbs ship:
 
 1. `swarph "prompt"` — Phase 2 one-shot mode (any of five providers)
 2. `swarph chat` — Phase 5 interactive REPL with multi-turn history + slash commands
 3. `swarph import <path>` — Phase 2.5 session import (Claude JSONL → swarph-native, with `--report-only` for honest pre-commit inspection)
-4. `swarph onboard <peer-name>` — **NEW** Phase 5.5 mechanics-phase onboarding (PLAN.md §15.4)
-5. `swarph ratify <peer-name>` — **NEW** Phase 5.5 witness ratification (PLAN.md §15.4a)
+4. `swarph onboard <peer-name>` — Phase 5.5 mechanics-phase onboarding (PLAN.md §15.4)
+5. `swarph ratify <peer-name>` — Phase 5.5 witness ratification (PLAN.md §15.4a)
+6. `swarph daemon` — **NEW** Phase 5.6 foreground inbox drain loop (PLAN.md §16); structurally retires the orphaned-tail-F class
 
-Subsequent phases extend the CLI surface (`--ask <peer>`, daemon).
+Subsequent phases extend the CLI surface (`--ask <peer>`, REPL drain coroutine + `/inbox` + `/reply` slash commands in 5.6b).
+
+### `swarph daemon` (Phase 5.6)
+
+Replaces the 4-layer `tail -F | grep | Monitor | systemd | cron poll` stack with one foreground process. Liveness check collapses to:
+
+```bash
+ps aux | grep '[s]warph daemon'   # zero output = monitoring is down
+```
+
+```bash
+$ swarph daemon --state-dir ~/swarph_state/lab-ovh --self lab-ovh
+[swarph-daemon] starting: self=lab-ovh gateway=http://localhost:8788 poll=30s ...
+[2026-05-08T21:00:30Z] id=728 from=droplet kind=answer → 'Drop review on Phase 5.5 PRs A+B...'
+[2026-05-08T21:01:10Z] id=729 from=droplet kind=fyi → 'Both Phase 5.5 PRs merged...'
+^C
+[swarph-daemon] signal 2 received — draining + flushing cursor
+[swarph-daemon] shutdown: iterations=12 dms_seen=2 cursor.last_msg_id=729
+```
+
+Loud-on-down (PLAN §16.5): never silently exits. Cursor writes are atomic (write-and-rename — corrupted mid-flush leaves the previous cursor intact). Backoff: 60s after 5 consecutive empty polls; 300s after 5 min of consecutive 5xx. SIGINT/SIGTERM trigger clean drain + flush.
+
+`--auto-act` flag is documented for v0.5.1+ when handler registration via `@swarph.on_dm(...)` lands; v0.5.0 ships surface-only mode (DMs printed + JSONL-logged to `inbox.log`, no automatic replies).
 
 ### `swarph onboard` + `swarph ratify` (Phase 5.5)
 
@@ -159,9 +182,10 @@ Pong!
 | **2** (v0.1.0) | One-shot mode: `swarph "hello" --provider gemini` |
 | **2.5** (v0.2.0) | `swarph import` — Claude JSONL → swarph-native session format |
 | **5** (v0.3.0) | `swarph chat` interactive REPL — multi-turn against any of five adapters + slash commands |
-| **5.5** (v0.4.0 — this release) | **`swarph onboard <peer-name>` + `swarph ratify <peer-name>`** — six mechanics steps + handshake template + witness flip (PLAN.md §15) |
+| **5.5** (v0.4.0) | `swarph onboard` + `swarph ratify` — six mechanics steps + handshake template + witness flip (PLAN.md §15) |
+| **5.6** (v0.5.0 — this release) | **`swarph daemon`** — foreground inbox drain loop with atomic cursor writes; retires the orphaned-tail-F class (PLAN.md §16) |
+| **5.6b** | REPL drain coroutine + `/inbox`/`/reply` slash commands + `@swarph.on_dm()` handler registration (mesh + cli) |
 | **3** | `--ask <peer>` mesh-aware one-shot via MeshClient |
-| **5.6** | `swarph daemon` foreground drain loop + REPL drain coroutine + `/inbox`, `/reply` (PLAN.md §16) |
 | **6** | (already done) PyPI publish |
 
 ## Why split CLI from substrate

{swarph_cli-0.4.0 → swarph_cli-0.5.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.4.0"
-description = "The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.4.0 ships Phase 5.5 `swarph onboard` + `swarph ratify` on top of Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL (PLAN.md §13 / §15)."
+version = "0.5.0"
+description = "The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.5.0 ships Phase 5.6 `swarph daemon` (foreground inbox drain — retires the orphaned-tail-F class) on top of Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify (PLAN.md §13 / §16)."
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.10"

{swarph_cli-0.4.0 → swarph_cli-0.5.0}/src/swarph_cli/__init__.py

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

swarph_cli-0.5.0/src/swarph_cli/commands/daemon.py

@@ -0,0 +1,438 @@
+"""``swarph daemon`` — Phase 5.6 foreground drain loop per PLAN.md §16.
+
+The structural retirement of the orphaned-tail-F class. Replaces the
+4-layer ``tail -F | grep | Monitor | systemd | cron poll`` stack with
+one foreground process that polls the gateway directly and writes
+the cursor transactionally (write-and-rename, no half-flushed state).
+
+Liveness check collapses to::
+
+    ps aux | grep '[s]warph daemon'
+
+— zero output = monitoring is down.
+
+Default mode is **surface-only** (DMs printed + logged, never auto-replied).
+``--auto-act`` flips on the AI-to-AI default per CLAUDE.md DM SEMANTICS,
+routing incoming DMs to handlers registered via ``@swarph.on_dm(...)``.
+v0.5.0 ships the daemon + cursor + signals + backoff; handler registration
++ ``MeshClient.watch()`` event stream + REPL drain coroutine + capability
+advert + heartbeat self-reporting land in v0.5.1+ per PLAN §16.4 / §16.4a /
+§16.4b.
+
+Loud-on-down discipline (PLAN §16.5): the daemon never silently exits.
+SIGINT / SIGTERM trigger a clean drain + cursor flush + non-zero shell
+liveness signal; uncaught exceptions land on stderr loudly. ``ps aux``
+is the only thing that needs to be checked.
+
+Open question §16.7 #2 resolution: ``--auto-act`` default OFF (lab read +
+drop's standing-auth lane discretion). Daemon-launchers in §15.4 step 6
+include ``--auto-act`` explicitly so AI peers opt in at provisioning time.
+
+Open question §16.7 #3 resolution: cursor format stays single-row JSON
+with write-and-rename atomic semantics. If flush fails mid-write the
+rename never happens and the previous cursor stands — no append-only
+log needed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import signal
+import sys
+import time
+import urllib.error
+import urllib.request
+from contextlib import suppress
+from pathlib import Path
+from typing import Optional
+
+
+_DEFAULT_POLL_S = 30
+_BACKOFF_EMPTY_THRESHOLD = 5  # consecutive empty polls before backing off
+_BACKOFF_EMPTY_SECONDS = 60
+_BACKOFF_5XX_THRESHOLD_SECONDS = 300  # 5 min of consecutive 5xx
+_BACKOFF_5XX_SECONDS = 300
+_LOUD_DISCONNECT_SECONDS = 600  # emit loud line every minute past this
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="swarph daemon",
+        description=(
+            "Phase 5.6 mesh inbox drain daemon per PLAN.md §16. "
+            "Foreground process; loud-on-down; transactional cursor."
+        ),
+    )
+    p.add_argument(
+        "--state-dir",
+        default=None,
+        help="state directory containing cursor.json + inbox.log "
+        "(default: ~/swarph_state/<self>/).",
+    )
+    p.add_argument(
+        "--self",
+        dest="self_name",
+        default=None,
+        help="canonical name of this peer (default: $SWARPH_SELF or "
+        "the directory name of --state-dir).",
+    )
+    p.add_argument(
+        "--gateway",
+        default=os.environ.get("MESH_GATEWAY_URL", "http://localhost:8788"),
+        help="mesh-gateway base URL.",
+    )
+    p.add_argument(
+        "--token-file",
+        default=None,
+        help="optional secrets file path (mode 0600 expected).",
+    )
+    p.add_argument(
+        "--poll-seconds",
+        type=int,
+        default=_DEFAULT_POLL_S,
+        help=f"base poll cadence in seconds (default: {_DEFAULT_POLL_S}).",
+    )
+    p.add_argument(
+        "--auto-act",
+        action="store_true",
+        help="route DMs to registered @swarph.on_dm handlers (v0.5.1+ — "
+        "in v0.5.0 this is a documentation flag; surface-only mode runs "
+        "regardless).",
+    )
+    p.add_argument(
+        "--once",
+        action="store_true",
+        help="run a single poll iteration then exit (test mode).",
+    )
+    return p
+
+
+def _resolve_self_name(arg: Optional[str], state_dir: Path) -> str:
+    if arg:
+        return arg
+    env = os.environ.get("SWARPH_SELF")
+    if env:
+        return env
+    return state_dir.name
+
+
+def _resolve_state_dir(arg: Optional[str], self_name_arg: Optional[str]) -> Path:
+    if arg:
+        return Path(arg).expanduser()
+    self_name = self_name_arg or os.environ.get("SWARPH_SELF")
+    if self_name:
+        return Path.home() / "swarph_state" / self_name
+    # Last resort — a self_name is needed to disambiguate; surface error.
+    raise SystemExit(
+        "swarph daemon: cannot resolve state directory. "
+        "Pass --state-dir <path> or set $SWARPH_SELF."
+    )
+
+
+def _resolve_token(token_file_arg: Optional[str]) -> str:
+    """Mirror onboard's resolution. env → secrets.toml mode 0600 → prompt."""
+    from swarph_cli.commands.onboard import _resolve_token as _onboard_resolve
+
+    return _onboard_resolve(token_file_arg)
+
+
+# ---------------------------------------------------------------------------
+# Cursor — single-row JSON with write-and-rename atomic semantics
+# ---------------------------------------------------------------------------
+
+
+def _read_cursor(path: Path) -> dict:
+    if not path.exists():
+        return {"last_msg_id": 0, "tasks_snapshot": {}}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        # Loud — corrupted cursor needs operator attention, not silent reset.
+        print(
+            f"[swarph-daemon] CORRUPTED cursor at {path}: {exc}. "
+            f"Refusing to overwrite. Inspect manually.",
+            file=sys.stderr,
+            flush=True,
+        )
+        raise
+
+
+def _write_cursor_atomic(path: Path, cursor: dict) -> None:
+    """Write-and-rename: write to a tmp file in the same dir, then atomic
+    rename over the target. Failed mid-write leaves the previous cursor
+    intact — open question §16.7 #3 resolution."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + f".tmp.{os.getpid()}")
+    tmp.write_text(json.dumps(cursor, indent=2, sort_keys=True), encoding="utf-8")
+    os.replace(tmp, path)  # atomic on POSIX + Windows ≥3.3
+
+
+# ---------------------------------------------------------------------------
+# HTTP — stdlib only, no httpx
+# ---------------------------------------------------------------------------
+
+
+def _http_get(url: str, *, token: str, timeout: float = 10.0) -> tuple[int, dict]:
+    req = urllib.request.Request(
+        url, headers={"Authorization": f"Bearer {token}"}
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.status, json.loads(resp.read().decode("utf-8") or "{}")
+    except urllib.error.HTTPError as exc:
+        try:
+            body = json.loads(exc.read().decode("utf-8") or "{}")
+        except Exception:
+            body = {"detail": str(exc)}
+        return exc.code, body
+    except urllib.error.URLError as exc:
+        # Network-level failure — gateway down, DNS, etc.
+        return 0, {"detail": str(exc)}
+
+
+# ---------------------------------------------------------------------------
+# Daemon state + loop
+# ---------------------------------------------------------------------------
+
+
+class DaemonState:
+    """Mutable state held by the drain loop. Surfaced as a class so tests
+    can inspect post-run."""
+
+    def __init__(self, *, self_name: str, state_dir: Path, gateway: str,
+                 token: str, poll_s: int, auto_act: bool):
+        self.self_name = self_name
+        self.state_dir = state_dir
+        self.gateway = gateway
+        self.token = token
+        self.poll_s = poll_s
+        self.auto_act = auto_act
+        self.cursor_path = state_dir / "cursor.json"
+        self.inbox_log_path = state_dir / "inbox.log"
+        self.cursor = _read_cursor(self.cursor_path)
+        self.consecutive_empty = 0
+        self.disconnect_since: Optional[float] = None
+        self.iterations = 0
+        self.dms_seen = 0
+        self.shutdown_requested = False
+
+
+def _log_dm(state: DaemonState, dm: dict) -> None:
+    """Both stdout (visible to operator + journald) AND inbox.log (cursor
+    audit trail). Inbox.log is append-only structured JSONL."""
+    line = (
+        f"[{dm.get('created_at', '?')}] "
+        f"id={dm['id']} from={dm.get('from_node')} kind={dm.get('kind')} "
+        f"→ {dm['content'][:120]!r}"
+    )
+    print(line, flush=True)
+    state.inbox_log_path.parent.mkdir(parents=True, exist_ok=True)
+    with state.inbox_log_path.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(dm) + "\n")
+
+
+def _route_to_handler(state: DaemonState, dm: dict) -> None:
+    """v0.5.0 stub. v0.5.1+ wires this through @swarph.on_dm() registrations
+    on the swarph-mesh side. For now, --auto-act prints a placeholder."""
+    if state.auto_act:
+        print(
+            f"  [auto-act] handler dispatch deferred to v0.5.1 "
+            f"(@swarph.on_dm + MeshClient.watch); surfacing only.",
+            flush=True,
+        )
+
+
+def _select_next_poll_seconds(state: DaemonState) -> int:
+    """Backoff per §16.2: empty-poll backoff after 5 consecutive empties,
+    5xx backoff after 5 min of consecutive failures."""
+    if state.disconnect_since is not None:
+        if (time.time() - state.disconnect_since) > _BACKOFF_5XX_THRESHOLD_SECONDS:
+            return _BACKOFF_5XX_SECONDS
+    if state.consecutive_empty >= _BACKOFF_EMPTY_THRESHOLD:
+        return _BACKOFF_EMPTY_SECONDS
+    return state.poll_s
+
+
+async def _drain_iteration(state: DaemonState) -> None:
+    """One poll → handle → cursor-write cycle. Errors logged loud; never
+    raises out of the loop."""
+    state.iterations += 1
+    last_id = state.cursor.get("last_msg_id", 0)
+    # Note: gateway query param is `to=` (NOT `to_node=`). The latter is
+    # silently ignored — bit the entire session's drain code which had
+    # python-side filters masking the issue. Defense-in-depth: also
+    # filter from_node != self_name client-side in case any future
+    # gateway quirk re-introduces outbound bleed-through.
+    url = (
+        f"{state.gateway}/messages?to={state.self_name}"
+        f"&limit=50"
+    )
+    status, body = _http_get(url, token=state.token)
+
+    if status == 0:
+        # Network-level failure
+        if state.disconnect_since is None:
+            state.disconnect_since = time.time()
+        elapsed = time.time() - state.disconnect_since
+        if elapsed > _LOUD_DISCONNECT_SECONDS:
+            print(
+                f"[swarph-daemon] LOUD: gateway unreachable for "
+                f"{elapsed:.0f}s — {body.get('detail', '?')}",
+                file=sys.stderr,
+                flush=True,
+            )
+        return
+    if status >= 500:
+        if state.disconnect_since is None:
+            state.disconnect_since = time.time()
+        print(
+            f"[swarph-daemon] gateway 5xx {status}: {body.get('detail', '?')}",
+            file=sys.stderr,
+            flush=True,
+        )
+        return
+    if status >= 400:
+        print(
+            f"[swarph-daemon] gateway {status}: {body.get('detail', '?')}",
+            file=sys.stderr,
+            flush=True,
+        )
+        return
+
+    # Success — clear disconnect tracking
+    state.disconnect_since = None
+
+    messages = [
+        m
+        for m in body.get("messages", [])
+        if m["id"] > last_id and m.get("from_node") != state.self_name
+    ]
+    if not messages:
+        state.consecutive_empty += 1
+        return
+
+    # Process oldest-first so cursor monotonically advances
+    messages.sort(key=lambda m: m["id"])
+    state.consecutive_empty = 0
+    new_last_id = last_id
+    for dm in messages:
+        _log_dm(state, dm)
+        _route_to_handler(state, dm)
+        state.dms_seen += 1
+        new_last_id = max(new_last_id, dm["id"])
+
+    state.cursor["last_msg_id"] = new_last_id
+    _write_cursor_atomic(state.cursor_path, state.cursor)
+
+
+async def _drain_loop(state: DaemonState) -> None:
+    """Main loop. Returns on shutdown_requested. Exceptions in
+    _drain_iteration are caught + logged + retried; only signal handlers
+    set shutdown_requested."""
+    print(
+        f"[swarph-daemon] starting: self={state.self_name} "
+        f"gateway={state.gateway} poll={state.poll_s}s "
+        f"state={state.state_dir} auto_act={state.auto_act} "
+        f"cursor.last_msg_id={state.cursor.get('last_msg_id', 0)}",
+        flush=True,
+    )
+
+    while not state.shutdown_requested:
+        try:
+            await _drain_iteration(state)
+        except Exception as exc:  # noqa: BLE001 — loud-on-error per §16.4
+            print(
+                f"[swarph-daemon] iteration error (continuing): "
+                f"{type(exc).__name__}: {exc}",
+                file=sys.stderr,
+                flush=True,
+            )
+
+        delay = _select_next_poll_seconds(state)
+        # Sleep in 1-second chunks so SIGINT/SIGTERM can interrupt promptly
+        for _ in range(delay):
+            if state.shutdown_requested:
+                break
+            await asyncio.sleep(1)
+
+    print(
+        f"[swarph-daemon] shutdown: iterations={state.iterations} "
+        f"dms_seen={state.dms_seen} cursor.last_msg_id={state.cursor.get('last_msg_id', 0)}",
+        flush=True,
+    )
+
+
+def _install_signal_handlers(loop: asyncio.AbstractEventLoop, state: DaemonState) -> None:
+    """SIGINT + SIGTERM → set shutdown_requested. The loop drains cleanly
+    on the next sleep boundary (≤1s)."""
+
+    def _handler(signum, frame):  # noqa: ARG001
+        if not state.shutdown_requested:
+            print(
+                f"[swarph-daemon] signal {signum} received — draining + flushing cursor",
+                flush=True,
+            )
+        state.shutdown_requested = True
+
+    # Use the signal module directly rather than loop.add_signal_handler so
+    # this works inside test harnesses where the loop's default policy may
+    # block signal-handler installation.
+    signal.signal(signal.SIGINT, _handler)
+    signal.signal(signal.SIGTERM, _handler)
+
+
+def run_daemon(argv: list[str]) -> int:
+    """Entry point invoked by ``swarph_cli.main`` verb dispatch."""
+    args = _build_parser().parse_args(argv)
+
+    # Resolve identity + state path
+    self_name = args.self_name or os.environ.get("SWARPH_SELF")
+    if args.state_dir:
+        state_dir = Path(args.state_dir).expanduser()
+        if not self_name:
+            self_name = state_dir.name
+    elif self_name:
+        state_dir = Path.home() / "swarph_state" / self_name
+    else:
+        print(
+            "swarph daemon: cannot resolve identity. Pass --self <name> or "
+            "--state-dir <path> or set $SWARPH_SELF.",
+            file=sys.stderr,
+            flush=True,
+        )
+        return 2
+
+    state_dir.mkdir(parents=True, exist_ok=True)
+    token = _resolve_token(args.token_file)
+    if not token:
+        print("swarph daemon: empty MESH_GATEWAY_TOKEN", file=sys.stderr)
+        return 2
+
+    state = DaemonState(
+        self_name=self_name,
+        state_dir=state_dir,
+        gateway=args.gateway,
+        token=token,
+        poll_s=args.poll_seconds,
+        auto_act=args.auto_act,
+    )
+
+    if args.once:
+        # Test mode — single iteration, no signal handlers, no loop
+        asyncio.run(_drain_iteration(state))
+        return 0
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    _install_signal_handlers(loop, state)
+    try:
+        loop.run_until_complete(_drain_loop(state))
+    finally:
+        # Final cursor flush in case shutdown happened mid-iteration
+        with suppress(Exception):
+            _write_cursor_atomic(state.cursor_path, state.cursor)
+        loop.close()
+    return 0

{swarph_cli-0.4.0 → swarph_cli-0.5.0}/src/swarph_cli/main.py

@@ -40,6 +40,7 @@ Usage:
   swarph import <path-to-source-session> [--report-only] [--target-session NAME]
   swarph onboard <peer-name> [--gateway URL]
   swarph ratify <peer-name> [--reason "<text>"] [--witness-name <self>]
+  swarph daemon [--state-dir DIR] [--self NAME] [--poll-seconds N]
 
 Examples:
   swarph "explain Hawkes process briefly"
@@ -50,8 +51,9 @@ Examples:
   swarph ratify new-peer-name --reason "handshake covers four invariants"
 
 Status: Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL +
-Phase 5.5 onboard/ratify ready. --ask <peer> (Phase 3), daemon
-(Phase 5.6) ship in subsequent releases.
+Phase 5.5 onboard/ratify + Phase 5.6 daemon ready.
+--ask <peer> (Phase 3), REPL drain coroutine + /inbox /reply
+slash commands (Phase 5.6b) ship in subsequent releases.
 
 Spec: https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md
 """
@@ -64,7 +66,8 @@ _VERB_HANDLERS: dict[str, str] = {
     "chat": "swarph_cli.commands.chat.run_chat",
     "onboard": "swarph_cli.commands.onboard.run_onboard",
     "ratify": "swarph_cli.commands.ratify.run_ratify",
-    # Future: "daemon", "list-peers", "list-adapters", etc.
+    "daemon": "swarph_cli.commands.daemon.run_daemon",
+    # Future: "list-peers", "list-adapters", etc.
 }
 
 

{swarph_cli-0.4.0 → swarph_cli-0.5.0/src/swarph_cli.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.4.0
-Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.4.0 ships Phase 5.5 `swarph onboard` + `swarph ratify` on top of Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL (PLAN.md §13 / §15).
+Version: 0.5.0
+Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.5.0 ships Phase 5.6 `swarph daemon` (foreground inbox drain — retires the orphaned-tail-F class) on top of Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify (PLAN.md §13 / §16).
 Author: Pierre Samson, Claude Opus
 License: MIT
 Project-URL: Homepage, https://github.com/darw007d/swarph-cli
@@ -49,15 +49,38 @@ This is one of three repos in the v0.3.x architecture:
 
 ## Status
 
-**v0.4.0 — Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify.** Five verbs ship:
+**v0.5.0 — Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL + Phase 5.5 onboard/ratify + Phase 5.6 daemon.** Six verbs ship:
 
 1. `swarph "prompt"` — Phase 2 one-shot mode (any of five providers)
 2. `swarph chat` — Phase 5 interactive REPL with multi-turn history + slash commands
 3. `swarph import <path>` — Phase 2.5 session import (Claude JSONL → swarph-native, with `--report-only` for honest pre-commit inspection)
-4. `swarph onboard <peer-name>` — **NEW** Phase 5.5 mechanics-phase onboarding (PLAN.md §15.4)
-5. `swarph ratify <peer-name>` — **NEW** Phase 5.5 witness ratification (PLAN.md §15.4a)
+4. `swarph onboard <peer-name>` — Phase 5.5 mechanics-phase onboarding (PLAN.md §15.4)
+5. `swarph ratify <peer-name>` — Phase 5.5 witness ratification (PLAN.md §15.4a)
+6. `swarph daemon` — **NEW** Phase 5.6 foreground inbox drain loop (PLAN.md §16); structurally retires the orphaned-tail-F class
 
-Subsequent phases extend the CLI surface (`--ask <peer>`, daemon).
+Subsequent phases extend the CLI surface (`--ask <peer>`, REPL drain coroutine + `/inbox` + `/reply` slash commands in 5.6b).
+
+### `swarph daemon` (Phase 5.6)
+
+Replaces the 4-layer `tail -F | grep | Monitor | systemd | cron poll` stack with one foreground process. Liveness check collapses to:
+
+```bash
+ps aux | grep '[s]warph daemon'   # zero output = monitoring is down
+```
+
+```bash
+$ swarph daemon --state-dir ~/swarph_state/lab-ovh --self lab-ovh
+[swarph-daemon] starting: self=lab-ovh gateway=http://localhost:8788 poll=30s ...
+[2026-05-08T21:00:30Z] id=728 from=droplet kind=answer → 'Drop review on Phase 5.5 PRs A+B...'
+[2026-05-08T21:01:10Z] id=729 from=droplet kind=fyi → 'Both Phase 5.5 PRs merged...'
+^C
+[swarph-daemon] signal 2 received — draining + flushing cursor
+[swarph-daemon] shutdown: iterations=12 dms_seen=2 cursor.last_msg_id=729
+```
+
+Loud-on-down (PLAN §16.5): never silently exits. Cursor writes are atomic (write-and-rename — corrupted mid-flush leaves the previous cursor intact). Backoff: 60s after 5 consecutive empty polls; 300s after 5 min of consecutive 5xx. SIGINT/SIGTERM trigger clean drain + flush.
+
+`--auto-act` flag is documented for v0.5.1+ when handler registration via `@swarph.on_dm(...)` lands; v0.5.0 ships surface-only mode (DMs printed + JSONL-logged to `inbox.log`, no automatic replies).
 
 ### `swarph onboard` + `swarph ratify` (Phase 5.5)
 
@@ -191,9 +214,10 @@ Pong!
 | **2** (v0.1.0) | One-shot mode: `swarph "hello" --provider gemini` |
 | **2.5** (v0.2.0) | `swarph import` — Claude JSONL → swarph-native session format |
 | **5** (v0.3.0) | `swarph chat` interactive REPL — multi-turn against any of five adapters + slash commands |
-| **5.5** (v0.4.0 — this release) | **`swarph onboard <peer-name>` + `swarph ratify <peer-name>`** — six mechanics steps + handshake template + witness flip (PLAN.md §15) |
+| **5.5** (v0.4.0) | `swarph onboard` + `swarph ratify` — six mechanics steps + handshake template + witness flip (PLAN.md §15) |
+| **5.6** (v0.5.0 — this release) | **`swarph daemon`** — foreground inbox drain loop with atomic cursor writes; retires the orphaned-tail-F class (PLAN.md §16) |
+| **5.6b** | REPL drain coroutine + `/inbox`/`/reply` slash commands + `@swarph.on_dm()` handler registration (mesh + cli) |
 | **3** | `--ask <peer>` mesh-aware one-shot via MeshClient |
-| **5.6** | `swarph daemon` foreground drain loop + REPL drain coroutine + `/inbox`, `/reply` (PLAN.md §16) |
 | **6** | (already done) PyPI publish |
 
 ## Why split CLI from substrate

{swarph_cli-0.4.0 → swarph_cli-0.5.0}/src/swarph_cli.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ src/swarph_cli.egg-info/requires.txt
 src/swarph_cli.egg-info/top_level.txt
 src/swarph_cli/commands/__init__.py
 src/swarph_cli/commands/chat.py
+src/swarph_cli/commands/daemon.py
 src/swarph_cli/commands/import_session.py
 src/swarph_cli/commands/onboard.py
 src/swarph_cli/commands/ratify.py
@@ -19,6 +20,7 @@ src/swarph_cli/parsers/__init__.py
 src/swarph_cli/parsers/claude.py
 tests/test_chat_command.py
 tests/test_claude_parser.py
+tests/test_daemon_command.py
 tests/test_import_command.py
 tests/test_main.py
 tests/test_onboard_command.py

swarph_cli-0.5.0/tests/test_daemon_command.py

@@ -0,0 +1,356 @@
+"""Tests for ``swarph daemon`` — mocks HTTP + filesystem.
+
+The daemon's structural value is replacing the orphaned-tail-F class
+with one foreground process. Tests cover: cursor read/write atomicity,
+backoff selection, single iteration end-to-end (via --once), gateway
+failure modes (5xx, network unreachable), signal-driven shutdown,
+verb dispatch.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import time
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from swarph_cli.commands import daemon as daemon_cmd
+from swarph_cli.commands.daemon import (
+    DaemonState,
+    _BACKOFF_5XX_SECONDS,
+    _BACKOFF_5XX_THRESHOLD_SECONDS,
+    _BACKOFF_EMPTY_SECONDS,
+    _BACKOFF_EMPTY_THRESHOLD,
+    _drain_iteration,
+    _read_cursor,
+    _select_next_poll_seconds,
+    _write_cursor_atomic,
+)
+
+
+# ---------------------------------------------------------------------------
+# Cursor — read/write/atomicity
+# ---------------------------------------------------------------------------
+
+
+def test_read_cursor_returns_default_on_missing(tmp_path):
+    cursor = _read_cursor(tmp_path / "no-such.json")
+    assert cursor == {"last_msg_id": 0, "tasks_snapshot": {}}
+
+
+def test_read_cursor_loads_existing(tmp_path):
+    p = tmp_path / "cursor.json"
+    p.write_text(json.dumps({"last_msg_id": 42, "tasks_snapshot": {"a": 1}}))
+    cursor = _read_cursor(p)
+    assert cursor["last_msg_id"] == 42
+    assert cursor["tasks_snapshot"] == {"a": 1}
+
+
+def test_read_cursor_raises_on_corrupted_file(tmp_path, capsys):
+    p = tmp_path / "cursor.json"
+    p.write_text("not json {{{")
+    with pytest.raises(json.JSONDecodeError):
+        _read_cursor(p)
+    err = capsys.readouterr().err
+    assert "CORRUPTED" in err
+    assert "Refusing to overwrite" in err
+
+
+def test_write_cursor_atomic_uses_rename(tmp_path):
+    p = tmp_path / "cursor.json"
+    _write_cursor_atomic(p, {"last_msg_id": 7})
+    assert p.exists()
+    assert json.loads(p.read_text())["last_msg_id"] == 7
+    # No leftover .tmp files
+    tmps = list(tmp_path.glob("cursor.json.tmp.*"))
+    assert tmps == []
+
+
+def test_write_cursor_atomic_creates_parent_dir(tmp_path):
+    nested = tmp_path / "a" / "b" / "cursor.json"
+    _write_cursor_atomic(nested, {"last_msg_id": 1})
+    assert nested.exists()
+
+
+def test_write_cursor_atomic_overwrites_cleanly(tmp_path):
+    p = tmp_path / "cursor.json"
+    _write_cursor_atomic(p, {"last_msg_id": 1})
+    _write_cursor_atomic(p, {"last_msg_id": 99})
+    assert json.loads(p.read_text())["last_msg_id"] == 99
+
+
+# ---------------------------------------------------------------------------
+# Backoff
+# ---------------------------------------------------------------------------
+
+
+def _state(tmp_path) -> DaemonState:
+    return DaemonState(
+        self_name="lab-test",
+        state_dir=tmp_path,
+        gateway="http://x:8788",
+        token="tok",
+        poll_s=30,
+        auto_act=False,
+    )
+
+
+def test_backoff_returns_base_when_healthy(tmp_path):
+    s = _state(tmp_path)
+    assert _select_next_poll_seconds(s) == 30
+
+
+def test_backoff_kicks_in_after_consecutive_empty(tmp_path):
+    s = _state(tmp_path)
+    s.consecutive_empty = _BACKOFF_EMPTY_THRESHOLD
+    assert _select_next_poll_seconds(s) == _BACKOFF_EMPTY_SECONDS
+
+
+def test_backoff_5xx_kicks_in_after_5min_disconnect(tmp_path):
+    s = _state(tmp_path)
+    s.disconnect_since = time.time() - (_BACKOFF_5XX_THRESHOLD_SECONDS + 1)
+    assert _select_next_poll_seconds(s) == _BACKOFF_5XX_SECONDS
+
+
+def test_backoff_5xx_short_outage_uses_base(tmp_path):
+    s = _state(tmp_path)
+    s.disconnect_since = time.time() - 10  # 10s out
+    assert _select_next_poll_seconds(s) == 30
+
+
+# ---------------------------------------------------------------------------
+# _drain_iteration — happy path + failure modes
+# ---------------------------------------------------------------------------
+
+
+def _http_factory(scripted: list):
+    """Returns (fake_http_get, captured_calls). scripted is a list of
+    (status, body) pairs returned in order."""
+    captured = []
+    it = iter(scripted)
+
+    def fake(url, *, token, timeout=10.0):
+        captured.append({"url": url, "token": token})
+        return next(it)
+
+    return fake, captured
+
+
+def test_drain_iteration_empty_inbox_advances_empty_counter(tmp_path, monkeypatch):
+    s = _state(tmp_path)
+    fake, _ = _http_factory([(200, {"messages": []})])
+    monkeypatch.setattr(daemon_cmd, "_http_get", fake)
+    asyncio.run(_drain_iteration(s))
+    assert s.consecutive_empty == 1
+    assert s.dms_seen == 0
+
+
+def test_drain_iteration_processes_messages_and_advances_cursor(tmp_path, monkeypatch):
+    s = _state(tmp_path)
+    s.cursor["last_msg_id"] = 5
+    fake, _ = _http_factory([
+        (200, {"messages": [
+            {"id": 6, "from_node": "drop", "kind": "fyi",
+             "content": "hello", "created_at": "2026-05-08T20:00:00Z"},
+            {"id": 7, "from_node": "drop", "kind": "fyi",
+             "content": "second", "created_at": "2026-05-08T20:01:00Z"},
+        ]}),
+    ])
+    monkeypatch.setattr(daemon_cmd, "_http_get", fake)
+    asyncio.run(_drain_iteration(s))
+    assert s.dms_seen == 2
+    assert s.cursor["last_msg_id"] == 7
+    assert s.consecutive_empty == 0
+    # Cursor flushed to disk
+    on_disk = json.loads((tmp_path / "cursor.json").read_text())
+    assert on_disk["last_msg_id"] == 7
+    # inbox.log has both DMs as JSONL
+    log_lines = (tmp_path / "inbox.log").read_text().strip().splitlines()
+    assert len(log_lines) == 2
+    assert json.loads(log_lines[0])["id"] == 6
+
+
+def test_drain_iteration_filters_outbound_self_messages(tmp_path, monkeypatch):
+    """Defense-in-depth filter: even if gateway returns messages where
+    from_node==self_name (latent ?to_node= vs ?to= bug, fixed mid-session),
+    the daemon must not log/process them as inbound. Regression-tested."""
+    s = _state(tmp_path)
+    fake, _ = _http_factory([
+        (200, {"messages": [
+            {"id": 1, "from_node": "drop", "to_node": "lab-test", "kind": "fyi",
+             "content": "real inbound", "created_at": "z"},
+            {"id": 2, "from_node": "lab-test", "to_node": "drop", "kind": "fyi",
+             "content": "MY outbound — should be skipped", "created_at": "z"},
+            {"id": 3, "from_node": "drop", "to_node": "lab-test", "kind": "fyi",
+             "content": "more inbound", "created_at": "z"},
+        ]}),
+    ])
+    monkeypatch.setattr(daemon_cmd, "_http_get", fake)
+    asyncio.run(_drain_iteration(s))
+    assert s.dms_seen == 2  # only id=1 and id=3
+    log_lines = (tmp_path / "inbox.log").read_text().strip().splitlines()
+    assert len(log_lines) == 2
+    contents = [json.loads(l)["content"] for l in log_lines]
+    assert "MY outbound — should be skipped" not in contents
+
+
+def test_drain_iteration_filters_already_seen_messages(tmp_path, monkeypatch):
+    """Gateway returns recent N messages including some <= last_id; daemon
+    must filter so it doesn't re-process."""
+    s = _state(tmp_path)
+    s.cursor["last_msg_id"] = 10
+    fake, _ = _http_factory([
+        (200, {"messages": [
+            {"id": 8, "from_node": "x", "kind": "fyi",
+             "content": "old", "created_at": "z"},
+            {"id": 9, "from_node": "x", "kind": "fyi",
+             "content": "old2", "created_at": "z"},
+            {"id": 11, "from_node": "x", "kind": "fyi",
+             "content": "new", "created_at": "z"},
+        ]}),
+    ])
+    monkeypatch.setattr(daemon_cmd, "_http_get", fake)
+    asyncio.run(_drain_iteration(s))
+    assert s.dms_seen == 1  # only id=11
+    assert s.cursor["last_msg_id"] == 11
+
+
+def test_drain_iteration_processes_in_id_order(tmp_path, monkeypatch):
+    """Gateway may return messages in any order; daemon must process
+    oldest-first so cursor advances monotonically."""
+    s = _state(tmp_path)
+    fake, _ = _http_factory([
+        (200, {"messages": [
+            {"id": 3, "from_node": "x", "kind": "fyi",
+             "content": "third", "created_at": "z"},
+            {"id": 1, "from_node": "x", "kind": "fyi",
+             "content": "first", "created_at": "z"},
+            {"id": 2, "from_node": "x", "kind": "fyi",
+             "content": "second", "created_at": "z"},
+        ]}),
+    ])
+    monkeypatch.setattr(daemon_cmd, "_http_get", fake)
+    asyncio.run(_drain_iteration(s))
+    log_ids = [
+        json.loads(line)["id"]
+        for line in (tmp_path / "inbox.log").read_text().strip().splitlines()
+    ]
+    assert log_ids == [1, 2, 3]
+    assert s.cursor["last_msg_id"] == 3
+
+
+def test_drain_iteration_5xx_records_disconnect(tmp_path, monkeypatch, capsys):
+    s = _state(tmp_path)
+    fake, _ = _http_factory([(503, {"detail": "service unavailable"})])
+    monkeypatch.setattr(daemon_cmd, "_http_get", fake)
+    asyncio.run(_drain_iteration(s))
+    assert s.disconnect_since is not None
+    err = capsys.readouterr().err
+    assert "503" in err
+    assert "service unavailable" in err
+
+
+def test_drain_iteration_4xx_logs_loud(tmp_path, monkeypatch, capsys):
+    s = _state(tmp_path)
+    fake, _ = _http_factory([(401, {"detail": "bad token"})])
+    monkeypatch.setattr(daemon_cmd, "_http_get", fake)
+    asyncio.run(_drain_iteration(s))
+    err = capsys.readouterr().err
+    assert "401" in err
+    # 4xx is not a "disconnect" — caller probably has wrong creds
+    assert s.disconnect_since is None
+
+
+def test_drain_iteration_network_unreachable_records_disconnect(
+    tmp_path, monkeypatch
+):
+    s = _state(tmp_path)
+    fake, _ = _http_factory([(0, {"detail": "name resolution failure"})])
+    monkeypatch.setattr(daemon_cmd, "_http_get", fake)
+    asyncio.run(_drain_iteration(s))
+    assert s.disconnect_since is not None
+
+
+def test_drain_iteration_clears_disconnect_on_recovery(tmp_path, monkeypatch):
+    s = _state(tmp_path)
+    s.disconnect_since = time.time()
+    fake, _ = _http_factory([(200, {"messages": []})])
+    monkeypatch.setattr(daemon_cmd, "_http_get", fake)
+    asyncio.run(_drain_iteration(s))
+    assert s.disconnect_since is None
+
+
+# ---------------------------------------------------------------------------
+# run_daemon — verb entry point with --once test mode
+# ---------------------------------------------------------------------------
+
+
+def test_run_daemon_once_returns_zero(tmp_path, monkeypatch):
+    monkeypatch.setenv("MESH_GATEWAY_TOKEN", "tok")
+    fake, _ = _http_factory([(200, {"messages": []})])
+    monkeypatch.setattr(daemon_cmd, "_http_get", fake)
+    rc = daemon_cmd.run_daemon(
+        [
+            "--state-dir",
+            str(tmp_path / "state"),
+            "--self",
+            "test-peer",
+            "--once",
+        ]
+    )
+    assert rc == 0
+
+
+def test_run_daemon_resolves_self_from_state_dir_basename(tmp_path, monkeypatch):
+    monkeypatch.setenv("MESH_GATEWAY_TOKEN", "tok")
+    monkeypatch.delenv("SWARPH_SELF", raising=False)
+    captured = []
+
+    def fake(url, *, token, timeout=10.0):
+        captured.append(url)
+        return 200, {"messages": []}
+
+    monkeypatch.setattr(daemon_cmd, "_http_get", fake)
+    state_dir = tmp_path / "swarph_state" / "auto-named-peer"
+    rc = daemon_cmd.run_daemon(
+        ["--state-dir", str(state_dir), "--once"]
+    )
+    assert rc == 0
+    # URL should embed auto-named-peer (the basename of state-dir).
+    # Gateway accepts ?to=, NOT ?to_node= — the latter is silently
+    # ignored. Bug regression-test for the session-long latent issue.
+    assert "to=auto-named-peer" in captured[0]
+    assert "to_node=" not in captured[0]
+
+
+def test_run_daemon_no_identity_exits_nonzero(monkeypatch, capsys):
+    monkeypatch.setenv("MESH_GATEWAY_TOKEN", "tok")
+    monkeypatch.delenv("SWARPH_SELF", raising=False)
+    rc = daemon_cmd.run_daemon(["--once"])
+    assert rc == 2
+    err = capsys.readouterr().err
+    assert "cannot resolve identity" in err
+
+
+# ---------------------------------------------------------------------------
+# Verb dispatch
+# ---------------------------------------------------------------------------
+
+
+def test_main_dispatches_daemon_verb(monkeypatch):
+    from swarph_cli import main as main_mod
+
+    captured = {}
+
+    def fake_run(argv):
+        captured["argv"] = argv
+        return 0
+
+    monkeypatch.setattr("swarph_cli.commands.daemon.run_daemon", fake_run)
+    rc = main_mod.main(["daemon", "--state-dir", "/tmp/x", "--once"])
+    assert rc == 0
+    assert captured["argv"] == ["--state-dir", "/tmp/x", "--once"]