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

{swarph_cli-0.3.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.3.0
-Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.3.0 ships the Phase 5 `swarph chat` REPL on top of Phase 2 one-shot + Phase 2.5 import (PLAN.md §13).
+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,13 +49,68 @@ This is one of three repos in the v0.3.x architecture:
 
 ## Status
 
-**v0.3.0 — Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL.** Three 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>` — 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>`, onboard/ratify, daemon, additional source formats).
+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)
+
+Per PLAN.md §15, onboarding splits into a **mechanics phase** (`swarph onboard`) that automates the boring parts (registry POST, scaffolding, token resolution) and a **manual contract phase** (the new peer composes the handshake DM in their own words). A witness peer judges the handshake and runs `swarph ratify <peer>` to flip `ratified=true`, gating `task_claim` server-side.
+
+```bash
+# New peer self-onboards
+$ swarph onboard razorpeter
+[1/6] validate_node_name('razorpeter')          ok
+[2/6] prepare peer-registry row                 ok
+[3/6] resolve MESH_GATEWAY_TOKEN                ok
+[4/6] POST .../peers/register                   ok (registered_unratified=true)
+[5/6] verify_subscription_setup()               ok
+[6/6] scaffold ~/swarph_state/razorpeter/       ok
+
+[manual] handshake template at /tmp/razorpeter-handshake.md
+  Edit each section in your own words, then send to your witness peer.
+
+# After peer composes + sends handshake, witness ratifies
+$ SWARPH_WITNESS=lab-ovh swarph ratify razorpeter \
+    --reason "handshake covers all four invariants in own words"
+[1/6] validate_node_name('razorpeter')          ok
+[2/6] verify witness 'lab-ovh' is ratified      ok
+[3/6] verify 'razorpeter' is registered_unratified  ok
+[4/6] PATCH .../peers/razorpeter                ok
+[5/6] verify peer_ratifications audit row       ok (id=N reason='...')
+[6/6] invalidate local TTL cache                ok
+```
+
+Server-side gating (mesh-gateway PR A): unratified peers can read inbox + send DMs (so the handshake itself works) but `task_claim` returns 403. Witness must itself be ratified — no self-ratification, no unratified-witnesses-ratifying-others. Audit log (`peer_ratifications`) is append-only.
 
 ### `swarph chat`
 
@@ -158,10 +213,11 @@ Pong!
 | **0** | Scaffold — entry-point + status banner |
 | **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 — this release) | **`swarph chat` interactive REPL** — multi-turn against any of five adapters + slash commands (`/help`, `/clear`, `/system`, `/provider`, `/model`, `/history`, `/cost`, `/quit`) |
+| **5** (v0.3.0) | `swarph chat` interactive REPL — multi-turn against any of five adapters + slash commands |
+| **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.5** | `swarph onboard <peer-name>` + `swarph ratify <peer-name>` (PLAN.md §15) |
-| **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.3.0 → swarph_cli-0.5.0}/README.md

@@ -17,13 +17,68 @@ This is one of three repos in the v0.3.x architecture:
 
 ## Status
 
-**v0.3.0 — Phase 2 one-shot + Phase 2.5 import + Phase 5 REPL.** Three 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>` — 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>`, onboard/ratify, daemon, additional source formats).
+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)
+
+Per PLAN.md §15, onboarding splits into a **mechanics phase** (`swarph onboard`) that automates the boring parts (registry POST, scaffolding, token resolution) and a **manual contract phase** (the new peer composes the handshake DM in their own words). A witness peer judges the handshake and runs `swarph ratify <peer>` to flip `ratified=true`, gating `task_claim` server-side.
+
+```bash
+# New peer self-onboards
+$ swarph onboard razorpeter
+[1/6] validate_node_name('razorpeter')          ok
+[2/6] prepare peer-registry row                 ok
+[3/6] resolve MESH_GATEWAY_TOKEN                ok
+[4/6] POST .../peers/register                   ok (registered_unratified=true)
+[5/6] verify_subscription_setup()               ok
+[6/6] scaffold ~/swarph_state/razorpeter/       ok
+
+[manual] handshake template at /tmp/razorpeter-handshake.md
+  Edit each section in your own words, then send to your witness peer.
+
+# After peer composes + sends handshake, witness ratifies
+$ SWARPH_WITNESS=lab-ovh swarph ratify razorpeter \
+    --reason "handshake covers all four invariants in own words"
+[1/6] validate_node_name('razorpeter')          ok
+[2/6] verify witness 'lab-ovh' is ratified      ok
+[3/6] verify 'razorpeter' is registered_unratified  ok
+[4/6] PATCH .../peers/razorpeter                ok
+[5/6] verify peer_ratifications audit row       ok (id=N reason='...')
+[6/6] invalidate local TTL cache                ok
+```
+
+Server-side gating (mesh-gateway PR A): unratified peers can read inbox + send DMs (so the handshake itself works) but `task_claim` returns 403. Witness must itself be ratified — no self-ratification, no unratified-witnesses-ratifying-others. Audit log (`peer_ratifications`) is append-only.
 
 ### `swarph chat`
 
@@ -126,10 +181,11 @@ Pong!
 | **0** | Scaffold — entry-point + status banner |
 | **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 — this release) | **`swarph chat` interactive REPL** — multi-turn against any of five adapters + slash commands (`/help`, `/clear`, `/system`, `/provider`, `/model`, `/history`, `/cost`, `/quit`) |
+| **5** (v0.3.0) | `swarph chat` interactive REPL — multi-turn against any of five adapters + slash commands |
+| **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.5** | `swarph onboard <peer-name>` + `swarph ratify <peer-name>` (PLAN.md §15) |
-| **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.3.0 → swarph_cli-0.5.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.3.0"
-description = "The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.3.0 ships the Phase 5 `swarph chat` REPL on top of Phase 2 one-shot + Phase 2.5 import (PLAN.md §13)."
+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.3.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.3.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