swarph-cli 0.7.1__tar.gz → 0.7.3__tar.gz

{swarph_cli-0.7.1/src/swarph_cli.egg-info → swarph_cli-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.7.1
+Version: 0.7.3
 Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.7.0 ships Phase 7 substrate-doc R7 §11.1.7 operator-tooling layer in 5 increments: PR-A `--new-instance` flag (sibling-spawn case) + PR-B auto-suffix on collision (sibling-slot persistence) + PR-C SessionStart hook (closes bare-claude operator-paste gap) + watchdog (stranded-session recovery) + PR-D swarph-shared cell.yaml relocation (cell-yaml schema graduates to swarph-shared 0.3.0 kernel-tier; substrate-doc R7 §11.1.5 (O5) RESOLVED).
 Author: Pierre Samson, Claude Opus
 License: MIT
@@ -138,6 +138,46 @@ Loud-on-down (PLAN §16.5): never silently exits. Cursor writes are atomic (writ
 
 `--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 watchdog` (Phase 7 — v0.7 stranded-session detection, v0.7.3 systemd install)
+
+Detects stranded Claude sessions (API throttle / harness death) via cursor-mtime + tmux pgrep AND-gate, and recovers via A1 tmux send-keys wake-prompt → A2 `swarph spawn` respawn. Cell.yaml-pinned cursor + tmux session (F4) since v0.7.2.
+
+**One-shot mode (cron-callable, v0.7+):**
+```bash
+*/5 * * * * swarph watchdog --check --cell lab >> ~/.local/log/swarph-watchdog.log 2>&1
+```
+
+**Systemd timer install (v0.7.3+ — closes ev_6954f748 substrate-component-installation-gap):**
+
+```bash
+# Preview without writing (any user):
+swarph watchdog --install-service --cell droplet --dry-run
+
+# Install + enable (requires root for /etc/systemd/system writes):
+sudo swarph watchdog --install-service --cell droplet
+```
+
+This writes three files:
+
+| Path | Purpose |
+|------|---------|
+| `/etc/systemd/system/swarph-watchdog.service` | `Type=oneshot`, runs `swarph watchdog --check` |
+| `/etc/systemd/system/swarph-watchdog.timer` | Fires every 5 minutes (`OnUnitActiveSec=5min`) |
+| `/etc/default/swarph-watchdog` | Sets `SWARPH_CELL=<role>` for the service env |
+
+Then runs `systemctl daemon-reload && systemctl enable --now swarph-watchdog.timer`. Idempotent — re-running overwrites with current package version (newer-version semantics).
+
+Monitoring:
+
+```bash
+systemctl status swarph-watchdog.timer       # is it scheduled?
+systemctl list-timers swarph-watchdog.timer  # next fire?
+journalctl -u swarph-watchdog.service -f     # live log
+tail -f /var/log/swarph-watchdog.log         # append-log alternative
+```
+
+Why this matters: pre-v0.7.3, swarph-cli shipped the watchdog code but no install path. Lab ran it via cron (manual setup); droplet never installed it at all. A real production silence-window (drop's ~24min mute 2026-05-14 08:38→09:02 UTC after an Anthropic API error) made the install-gap visible. v0.7.3 closes it for any peer with one command.
+
 ### `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.

{swarph_cli-0.7.1 → swarph_cli-0.7.3}/README.md

@@ -105,6 +105,46 @@ Loud-on-down (PLAN §16.5): never silently exits. Cursor writes are atomic (writ
 
 `--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 watchdog` (Phase 7 — v0.7 stranded-session detection, v0.7.3 systemd install)
+
+Detects stranded Claude sessions (API throttle / harness death) via cursor-mtime + tmux pgrep AND-gate, and recovers via A1 tmux send-keys wake-prompt → A2 `swarph spawn` respawn. Cell.yaml-pinned cursor + tmux session (F4) since v0.7.2.
+
+**One-shot mode (cron-callable, v0.7+):**
+```bash
+*/5 * * * * swarph watchdog --check --cell lab >> ~/.local/log/swarph-watchdog.log 2>&1
+```
+
+**Systemd timer install (v0.7.3+ — closes ev_6954f748 substrate-component-installation-gap):**
+
+```bash
+# Preview without writing (any user):
+swarph watchdog --install-service --cell droplet --dry-run
+
+# Install + enable (requires root for /etc/systemd/system writes):
+sudo swarph watchdog --install-service --cell droplet
+```
+
+This writes three files:
+
+| Path | Purpose |
+|------|---------|
+| `/etc/systemd/system/swarph-watchdog.service` | `Type=oneshot`, runs `swarph watchdog --check` |
+| `/etc/systemd/system/swarph-watchdog.timer` | Fires every 5 minutes (`OnUnitActiveSec=5min`) |
+| `/etc/default/swarph-watchdog` | Sets `SWARPH_CELL=<role>` for the service env |
+
+Then runs `systemctl daemon-reload && systemctl enable --now swarph-watchdog.timer`. Idempotent — re-running overwrites with current package version (newer-version semantics).
+
+Monitoring:
+
+```bash
+systemctl status swarph-watchdog.timer       # is it scheduled?
+systemctl list-timers swarph-watchdog.timer  # next fire?
+journalctl -u swarph-watchdog.service -f     # live log
+tail -f /var/log/swarph-watchdog.log         # append-log alternative
+```
+
+Why this matters: pre-v0.7.3, swarph-cli shipped the watchdog code but no install path. Lab ran it via cron (manual setup); droplet never installed it at all. A real production silence-window (drop's ~24min mute 2026-05-14 08:38→09:02 UTC after an Anthropic API error) made the install-gap visible. v0.7.3 closes it for any peer with one command.
+
 ### `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.

{swarph_cli-0.7.1 → swarph_cli-0.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.7.1"
+version = "0.7.3"
 description = "The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.7.0 ships Phase 7 substrate-doc R7 §11.1.7 operator-tooling layer in 5 increments: PR-A `--new-instance` flag (sibling-spawn case) + PR-B auto-suffix on collision (sibling-slot persistence) + PR-C SessionStart hook (closes bare-claude operator-paste gap) + watchdog (stranded-session recovery) + PR-D swarph-shared cell.yaml relocation (cell-yaml schema graduates to swarph-shared 0.3.0 kernel-tier; substrate-doc R7 §11.1.5 (O5) RESOLVED)."
 readme = "README.md"
 license = { text = "MIT" }
@@ -59,6 +59,12 @@ swarph = "swarph_cli.main:main"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+# v0.7.3: ship bundled systemd unit + timer + default templates so
+# `swarph watchdog --install-service` can read them via importlib.resources.
+# Closes ev_6954f748 substrate-component-installation-gap.
+swarph_cli = ["systemd/*.service", "systemd/*.timer", "systemd/*.default"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "-v --tb=short"

{swarph_cli-0.7.1 → swarph_cli-0.7.3}/src/swarph_cli/__init__.py

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

{swarph_cli-0.7.1 → swarph_cli-0.7.3}/src/swarph_cli/commands/watchdog.py

@@ -79,6 +79,11 @@ _DEFAULT_THRESHOLD_SEC = 1800  # 30 minutes
 _DEFAULT_A1_RETRIES = 3
 _DEFAULT_A1_BACKOFF_SEC = 60
 _DEFAULT_GATEWAY_URL = "http://localhost:8788"
+# F3 — tmux pane_activity gate threshold. If pane has activity within this
+# many seconds, suppress A1 (session is working, not stalled). 600s (10min)
+# is comfortably above legitimate-pause noise + comfortably below the
+# 30min cursor-staleness threshold, so the two gates compose cleanly.
+_DEFAULT_PANE_ACTIVITY_THRESHOLD_SEC = 600
 
 _USAGE = """\
 Usage:
@@ -86,6 +91,7 @@ Usage:
                           [--gateway URL] [--tmux-session NAME]
                           [--peer NAME] [--no-respawn]
                           [--log PATH] [--verbose]
+  swarph watchdog --install-service [--cell ROLE] [--dry-run]
 
 Detects stranded Claude sessions (API throttle / harness death) and attempts
 recovery via tmux send-keys A1 wake-prompt, escalating to swarph spawn
@@ -94,6 +100,12 @@ respawn (A2) on persistent darkness.
 Designed for cron invocation:
   */5 * * * * swarph watchdog --check --cell lab >> ~/.local/log/swarph-watchdog.log 2>&1
 
+OR systemd timer (v0.7.3+, closes ev_6954f748 substrate-component-installation-gap):
+  sudo swarph watchdog --install-service [--cell <role>]
+  # → installs /etc/systemd/system/swarph-watchdog.{service,timer}
+  # → installs /etc/default/swarph-watchdog with SWARPH_CELL=<role>
+  # → daemon-reload + enable --now swarph-watchdog.timer
+
 Detection (mother #1021 AND-gate design):
   PRIMARY:  cursor file mtime — most-recent Claude action (drain script touches it)
   FALLBACK: pgrep claude on tmux session — confirms process aliveness
@@ -118,11 +130,12 @@ Flags:
   --verbose            also write diagnostics to stderr
 
 Exit codes:
-  0  no action taken (session healthy or no unread DMs queued)
+  0  no action taken (session healthy or no unread DMs queued); install ok
   1  A1 fired (wake-prompt sent)
   2  A2 fired (full respawn triggered)
   3  detection error (cursor unreadable / gateway unreachable)
-  4  configuration error (invalid args, no cell.yaml resolved)
+  4  configuration error (invalid args, no cell.yaml resolved); install needs sudo
+  5  install error (file write failed / systemctl failed)
 """
 
 
@@ -137,10 +150,29 @@ def _stat_mtime(path: Path) -> Optional[int]:
         return None
 
 
-def _resolve_cursor_path(role: str, explicit: Optional[str]) -> Path:
-    """Resolve cursor file path with documented fallback chain."""
+def _resolve_cursor_path(
+    role: str,
+    explicit: Optional[str],
+    cell_yaml_value: Optional[str] = None,
+) -> Path:
+    """Resolve cursor file path with documented fallback chain.
+
+    Precedence (F4 — mother #1057/#1060 + beta #1061/#1065):
+      1. Explicit ``--cursor`` CLI arg (highest)
+      2. ``cell.yaml`` extra.cursor_path when --cell present
+      3. ``$TMPDIR/<role>-cursor.json``
+      4. ``/tmp/lab-claude-cursor.json`` (legacy lab-orchestrator default)
+
+    F4 closes the host-prefix-variant + sibling-instance-variant gap
+    class — cell.yaml carries the canonical cursor path per-cell, watchdog
+    auto-resolves when --cell is provided. Eliminates the silent-default-
+    to-lab-prefix failure mode that gave droplet 23hr of cursor-unreadable
+    errors before catch.
+    """
     if explicit:
         return Path(explicit).expanduser()
+    if cell_yaml_value:
+        return Path(cell_yaml_value).expanduser()
     tmpdir = os.environ.get("TMPDIR", "/tmp")
     primary = Path(tmpdir) / f"{role}-cursor.json"
     if primary.exists():
@@ -149,6 +181,74 @@ def _resolve_cursor_path(role: str, explicit: Optional[str]) -> Path:
     return Path("/tmp/lab-claude-cursor.json")
 
 
+def _resolve_tmux_session(
+    role: str,
+    explicit: Optional[str],
+    cell_yaml_value: Optional[str] = None,
+) -> str:
+    """Resolve tmux session name with documented fallback chain.
+
+    Precedence (F4 sibling to cursor_path):
+      1. Explicit ``--tmux-session`` CLI arg
+      2. ``cell.yaml`` extra.tmux_session when --cell present
+      3. Role itself (convention default)
+
+    Mother's sibling-instance variant (#1061): when slot-N siblings spawn,
+    each slot needs its own tmux session name; the cell.yaml that pins the
+    slot SHOULD also pin the tmux_session to keep the watchdog's reads
+    consistent with the spawn's writes.
+    """
+    if explicit:
+        return explicit
+    if cell_yaml_value:
+        return cell_yaml_value
+    return role
+
+
+def _read_cell_yaml_pins(role: str) -> tuple[Optional[str], Optional[str]]:
+    """Best-effort read of cell.yaml extra.cursor_path + extra.tmux_session.
+
+    Tries the cwd-local ``./cell.yaml`` first (matches hook_output discovery),
+    falls back to ``<cells_dir>/<role>.yaml``. Returns (None, None) on any
+    failure — F4 is additive non-breaking, malformed cell.yaml falls through
+    to the legacy convention defaults.
+
+    NOTE: ``cursor_path`` / ``tmux_session`` live in ``Cell.extra`` (forward-
+    compat catch-all per swarph-shared v0.3) in v0.7.2. swarph-shared 0.4
+    will graduate them to first-class typed fields on ``Cell``; this reader
+    will continue to work because graduate-to-typed-field preserves the
+    extra-dict reading path (per swarph-shared's documented forward-compat
+    discipline).
+    """
+    from swarph_cli.cell import (
+        cells_dir,
+        discover_cell_in_cwd,
+        load_cell,
+        CellError,
+    )
+
+    cell_path = discover_cell_in_cwd()
+    if cell_path is None:
+        candidate = cells_dir() / f"{role}.yaml"
+        if candidate.is_file():
+            cell_path = candidate
+    if cell_path is None:
+        return None, None
+
+    try:
+        cell = load_cell(cell_path)
+    except (CellError, OSError):
+        return None, None
+
+    extra = cell.extra or {}
+    cursor_path = extra.get("cursor_path")
+    tmux_session = extra.get("tmux_session")
+    return (
+        str(cursor_path) if cursor_path else None,
+        str(tmux_session) if tmux_session else None,
+    )
+
+
 def _resolve_log_path(explicit: Optional[str]) -> Path:
     if explicit:
         return Path(explicit).expanduser()
@@ -228,6 +328,39 @@ def _tmux_send_keys(name: str, text: str) -> bool:
         return False
 
 
+def _pane_activity_age_sec(name: str) -> Optional[int]:
+    """Age in seconds since the tmux pane's last activity event.
+
+    Reads tmux's `#{pane_activity}` format variable, which returns a unix
+    epoch timestamp of the most recent activity in the active pane of the
+    target session. Returns None if tmux is missing, the session doesn't
+    exist, or tmux's output isn't parseable as an integer epoch.
+
+    Used by F3 (mother #1087 / drop-on-meta-edge proposal) as a third
+    AND-gate input to distinguish (a) session genuinely stalled from (b)
+    session actively working in a long bash block. cursor-mtime alone
+    measures "time since last turn-end" not "time since last activity";
+    pane_activity covers the mid-turn-active case.
+
+    Returns None on detection error so the caller can fall through to
+    the legacy AND-gate behavior — F3 is a strengthening of the gate,
+    not a replacement of it.
+    """
+    try:
+        result = subprocess.run(
+            ["tmux", "display", "-p", "-t", name, "#{pane_activity}"],
+            capture_output=True, text=True, timeout=5,
+        )
+        if result.returncode != 0:
+            return None
+        out = result.stdout.strip()
+        if not out:
+            return None
+        return max(0, _now() - int(out))
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError, ValueError):
+        return None
+
+
 def _tmux_kill_session(name: str) -> bool:
     try:
         result = subprocess.run(
@@ -263,7 +396,7 @@ def _spawn_via_swarph(role: str, tmux_session: str) -> bool:
         return False
 
 
-def _a1_marker_path(log_path: Path, role: str) -> Path:
+def _a1_marker_path(log_path: Path, role: str, tmux_session: Optional[str] = None) -> Path:
     """Marker file recording the cursor_mtime at which A1 was last fired.
 
     Co-located with the watchdog log so it inherits the same XDG_STATE_HOME
@@ -272,14 +405,27 @@ def _a1_marker_path(log_path: Path, role: str) -> Path:
     where cron fired A1 every 5min for 65min into an active session's tmux
     input buffer (commander #1092 + droplet #1087).
 
-    Keyed on ``role`` alone today. When the F4 follow-up (cell.yaml-pinned
-    cursor_path + tmux_session per mother+beta #1064/#1065) lands and the
-    sibling-instance pattern (alpha+beta drop-on-meta-edge per
-    project_drop_mitosis_to_meta_edge) ships at scale, two siblings sharing
-    the same base ``role`` would clobber each other's markers. Re-key on
-    ``(role, tmux_session)`` once F4 lands — flagged by mother in #1103.
+    Keyed on ``(role, tmux_session)`` post-F4 so sibling-instance patterns
+    (alpha+beta drop-on-meta-edge per project_drop_mitosis_to_meta_edge)
+    don't clobber each other's markers — mother's flag from #1103 closed in
+    v0.7.2. tmux_session is sanitized to alphanumeric + ``-_.`` for the
+    filename to avoid path-traversal or weird characters from cell.yaml-
+    pinned values.
+
+    NOTE (mother #1138 sanitization edge case): two siblings whose
+    ``tmux_session`` values differ ONLY in disallowed characters (e.g.,
+    ``cell:a`` vs ``cell:b`` — colons sanitized to ``_`` collapsing both
+    to ``cell_a`` / ``cell_b`` — fine in this example, but ``cell:a`` vs
+    ``cell$a`` would both collapse to ``cell_a``) would collide post-
+    sanitization. cell.yaml-pinned ``tmux_session`` values SHOULD differ
+    in alphanumeric content, not just punctuation. Cosmetic in practice
+    (operators don't choose session names that close), but worth knowing.
     """
-    return log_path.parent / f"a1-fired-{role}.marker"
+    safe_tmux = "".join(
+        c if (c.isalnum() or c in "-_.") else "_"
+        for c in (tmux_session or role)
+    )
+    return log_path.parent / f"a1-fired-{role}-{safe_tmux}.marker"
 
 
 def _a1_already_fired_at(marker: Path, cursor_mtime: int) -> bool:
@@ -331,10 +477,17 @@ def _log_event(log_path: Path, event: str, details: dict, verbose: bool = False)
 
 def run_check(args: argparse.Namespace) -> int:
     role = args.cell
-    cursor = _resolve_cursor_path(role, args.cursor)
+    # F4 — cell.yaml-pinned cursor_path + tmux_session (mother #1057/#1060
+    # + beta #1061/#1065). Reads cell.yaml `extra.cursor_path` /
+    # `extra.tmux_session` when --cell is provided; explicit CLI args still
+    # win. Best-effort: malformed cell.yaml falls through to legacy
+    # convention defaults (additive non-breaking).
+    cell_cursor, cell_tmux = _read_cell_yaml_pins(role)
+    cursor = _resolve_cursor_path(role, args.cursor, cell_cursor)
+    tmux_session = _resolve_tmux_session(role, args.tmux_session, cell_tmux)
     log_path = _resolve_log_path(args.log)
     threshold = args.threshold
-    tmux_session = args.tmux_session or role
+    pane_activity_threshold = args.pane_activity_threshold
     peer = args.peer or role
     gateway = args.gateway
     token = os.environ.get("MESH_GATEWAY_TOKEN")
@@ -346,6 +499,9 @@ def run_check(args: argparse.Namespace) -> int:
         "threshold_sec": threshold,
         "tmux_session": tmux_session,
         "peer": peer,
+        "pane_activity_threshold_sec": pane_activity_threshold,
+        "cell_yaml_pinned_cursor": cell_cursor is not None,
+        "cell_yaml_pinned_tmux": cell_tmux is not None,
     }
 
     # PRIMARY signal: cursor file mtime
@@ -378,7 +534,7 @@ def run_check(args: argparse.Namespace) -> int:
     # cursor_stale + process_alive + unread None  → noop (F2 fail-closed: can't verify work, don't poke)
     # cursor_stale + a1_marker matches cursor_mtime → noop (F1 same-window suppression)
 
-    marker = _a1_marker_path(log_path, role)
+    marker = _a1_marker_path(log_path, role, tmux_session)
     diag["a1_marker"] = str(marker)
 
     if not process_alive:
@@ -434,6 +590,21 @@ def run_check(args: argparse.Namespace) -> int:
         _log_event(log_path, "noop", diag, verbose)
         return 0
 
+    # F3 — tmux pane_activity AND-gate (mother #1087). cursor-mtime measures
+    # "time since last turn-end" not "time since last activity"; mid-long-
+    # turn cursor is stale even though session is maximally alive. tmux's
+    # `#{pane_activity}` covers the mid-turn-active case. If the pane has
+    # had activity within `pane_activity_threshold_sec`, suppress A1 — the
+    # session is working, not stalled. Falls through to firing A1 when
+    # pane_activity is None (tmux missing / older tmux without the format)
+    # so F3 is a strengthening of the gate, not a hard dependency.
+    pane_age = _pane_activity_age_sec(tmux_session)
+    diag["pane_activity_age_sec"] = pane_age
+    if pane_age is not None and pane_age < pane_activity_threshold:
+        diag["decision"] = "noop_pane_activity_recent"
+        _log_event(log_path, "noop", diag, verbose)
+        return 0
+
     diag["decision"] = "a1_send_keys"
     wake_text = (
         f"watchdog wake — cursor stale {cursor_age}s, "
@@ -447,6 +618,107 @@ def run_check(args: argparse.Namespace) -> int:
     return 1 if sent else 4
 
 
+_SYSTEMD_UNIT_DIR = Path("/etc/systemd/system")
+_SYSTEMD_DEFAULT_DIR = Path("/etc/default")
+_SYSTEMD_UNIT_NAMES = ("swarph-watchdog.service", "swarph-watchdog.timer")
+_SYSTEMD_DEFAULT_NAME = "swarph-watchdog"  # /etc/default/swarph-watchdog
+
+
+def _bundled_systemd_files() -> dict[str, str]:
+    """Return {filename: content} for the 3 bundled systemd templates.
+
+    Reads from the package's bundled `systemd/` data directory via
+    importlib.resources. Works regardless of install method (pipx, pip,
+    editable, wheel-from-PyPI).
+    """
+    try:
+        from importlib.resources import files as _files
+    except ImportError:  # pragma: no cover — Python <3.9 not supported anyway
+        from importlib_resources import files as _files  # type: ignore[no-redef]
+
+    pkg_root = _files("swarph_cli") / "systemd"
+    out: dict[str, str] = {}
+    for name in (*_SYSTEMD_UNIT_NAMES, "swarph-watchdog.default"):
+        out[name] = (pkg_root / name).read_text(encoding="utf-8")
+    return out
+
+
+def run_install_service(args: argparse.Namespace) -> int:
+    """Install systemd timer + service for periodic watchdog --check.
+
+    Idempotent: overwrites existing unit files (newer-version semantics).
+    Requires sudo for /etc/systemd/system writes unless --dry-run.
+
+    Exit codes:
+      0  success (or dry-run completed)
+      4  configuration error (non-root without --dry-run)
+      5  install error (file write failed / systemctl failed)
+    """
+    files = _bundled_systemd_files()
+
+    # Template the default file with the requested role
+    default_content = files["swarph-watchdog.default"].replace(
+        "SWARPH_CELL=lab",
+        f"SWARPH_CELL={args.cell}",
+        1,
+    )
+
+    targets = [
+        (_SYSTEMD_UNIT_DIR / _SYSTEMD_UNIT_NAMES[0], files[_SYSTEMD_UNIT_NAMES[0]]),
+        (_SYSTEMD_UNIT_DIR / _SYSTEMD_UNIT_NAMES[1], files[_SYSTEMD_UNIT_NAMES[1]]),
+        (_SYSTEMD_DEFAULT_DIR / _SYSTEMD_DEFAULT_NAME, default_content),
+    ]
+
+    if args.dry_run:
+        print(f"# DRY RUN — cell={args.cell}", file=sys.stderr)
+        for path, content in targets:
+            print(f"\n# would write {path}:", file=sys.stderr)
+            print(content, file=sys.stderr)
+        print(
+            "\n# would then run:\n"
+            "#   sudo systemctl daemon-reload\n"
+            "#   sudo systemctl enable --now swarph-watchdog.timer",
+            file=sys.stderr,
+        )
+        return 0
+
+    if os.geteuid() != 0:
+        print(
+            "ERROR: --install-service requires root. Re-run with sudo, or use "
+            "--dry-run to preview the install without writing.",
+            file=sys.stderr,
+        )
+        return 4
+
+    try:
+        for path, content in targets:
+            path.write_text(content, encoding="utf-8")
+            print(f"wrote {path}", file=sys.stderr)
+    except (OSError, PermissionError) as exc:
+        print(f"ERROR: failed to write unit files: {exc}", file=sys.stderr)
+        return 5
+
+    try:
+        subprocess.run(["systemctl", "daemon-reload"], check=True)
+        subprocess.run(
+            ["systemctl", "enable", "--now", "swarph-watchdog.timer"],
+            check=True,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError) as exc:
+        print(f"ERROR: systemctl failed: {exc}", file=sys.stderr)
+        return 5
+
+    print(
+        f"\nswarph-watchdog.timer installed + enabled for cell={args.cell}.\n"
+        f"  status:  systemctl status swarph-watchdog.timer\n"
+        f"  logs:    journalctl -u swarph-watchdog.service -f\n"
+        f"           OR /var/log/swarph-watchdog.log\n"
+        f"  next:    systemctl list-timers swarph-watchdog.timer",
+        file=sys.stderr,
+    )
+    return 0
+
+
 def run_watchdog(argv: Optional[list[str]] = None) -> int:
     if argv is None:
         argv = sys.argv[2:]  # skip "swarph watchdog"
@@ -460,9 +732,27 @@ def run_watchdog(argv: Optional[list[str]] = None) -> int:
         "--check", action="store_true",
         help="One-shot check (cron-callable; exits with status code).",
     )
+    p.add_argument(
+        "--install-service", action="store_true",
+        help="Install systemd timer + service for periodic --check invocation. "
+             "Requires sudo. Closes ev_6954f748 substrate-component-install gap.",
+    )
+    p.add_argument(
+        "--dry-run", action="store_true",
+        help="With --install-service: show what would be written without "
+             "writing. Useful for review or non-root preview.",
+    )
     p.add_argument("--cell", default=os.environ.get("SWARPH_CELL", "lab"))
     p.add_argument("--cursor", default=None)
     p.add_argument("--threshold", type=int, default=_DEFAULT_THRESHOLD_SEC)
+    p.add_argument(
+        "--pane-activity-threshold",
+        type=int,
+        default=_DEFAULT_PANE_ACTIVITY_THRESHOLD_SEC,
+        help="F3 gate: suppress A1 if tmux pane had activity within this "
+             "many seconds (covers mid-long-turn working sessions where "
+             "cursor-mtime is stale but session is alive).",
+    )
     p.add_argument("--gateway", default=_DEFAULT_GATEWAY_URL)
     p.add_argument("--tmux-session", default=None)
     p.add_argument("--peer", default=None)
@@ -475,6 +765,9 @@ def run_watchdog(argv: Optional[list[str]] = None) -> int:
     except SystemExit as exc:
         return int(exc.code or 0)
 
+    if args.install_service:
+        return run_install_service(args)
+
     if not args.check:
         print(_USAGE, file=sys.stderr)
         return 4

swarph_cli-0.7.3/src/swarph_cli/systemd/swarph-watchdog.default

@@ -0,0 +1,9 @@
+# /etc/default/swarph-watchdog — environment for swarph-watchdog.service
+#
+# SWARPH_CELL sets the cell role for the watchdog. The watchdog reads
+# cell.yaml for this role to discover the cursor path + tmux session pin
+# (per F4 cell.yaml-pinning landed in v0.7.2).
+#
+# If unset, watchdog defaults to "lab" (per the --cell argparse default).
+# Override here per-vertex: droplet, gpu-wsl, razorpeter, etc.
+SWARPH_CELL=lab

swarph_cli-0.7.3/src/swarph_cli/systemd/swarph-watchdog.service

@@ -0,0 +1,15 @@
+[Unit]
+Description=Swarph watchdog one-shot check (stranded-session recovery)
+Documentation=https://github.com/darw007d/swarph-cli
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+EnvironmentFile=-/etc/default/swarph-watchdog
+ExecStart=/usr/local/bin/swarph watchdog --check
+StandardOutput=append:/var/log/swarph-watchdog.log
+StandardError=append:/var/log/swarph-watchdog.log
+
+[Install]
+WantedBy=multi-user.target

swarph_cli-0.7.3/src/swarph_cli/systemd/swarph-watchdog.timer

@@ -0,0 +1,13 @@
+[Unit]
+Description=Run swarph watchdog every 5 minutes (stranded-session recovery)
+Documentation=https://github.com/darw007d/swarph-cli
+Requires=swarph-watchdog.service
+
+[Timer]
+OnBootSec=2min
+OnUnitActiveSec=5min
+AccuracySec=1min
+Persistent=true
+
+[Install]
+WantedBy=timers.target

{swarph_cli-0.7.1 → swarph_cli-0.7.3/src/swarph_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.7.1
+Version: 0.7.3
 Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. v0.7.0 ships Phase 7 substrate-doc R7 §11.1.7 operator-tooling layer in 5 increments: PR-A `--new-instance` flag (sibling-spawn case) + PR-B auto-suffix on collision (sibling-slot persistence) + PR-C SessionStart hook (closes bare-claude operator-paste gap) + watchdog (stranded-session recovery) + PR-D swarph-shared cell.yaml relocation (cell-yaml schema graduates to swarph-shared 0.3.0 kernel-tier; substrate-doc R7 §11.1.5 (O5) RESOLVED).
 Author: Pierre Samson, Claude Opus
 License: MIT
@@ -138,6 +138,46 @@ Loud-on-down (PLAN §16.5): never silently exits. Cursor writes are atomic (writ
 
 `--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 watchdog` (Phase 7 — v0.7 stranded-session detection, v0.7.3 systemd install)
+
+Detects stranded Claude sessions (API throttle / harness death) via cursor-mtime + tmux pgrep AND-gate, and recovers via A1 tmux send-keys wake-prompt → A2 `swarph spawn` respawn. Cell.yaml-pinned cursor + tmux session (F4) since v0.7.2.
+
+**One-shot mode (cron-callable, v0.7+):**
+```bash
+*/5 * * * * swarph watchdog --check --cell lab >> ~/.local/log/swarph-watchdog.log 2>&1
+```
+
+**Systemd timer install (v0.7.3+ — closes ev_6954f748 substrate-component-installation-gap):**
+
+```bash
+# Preview without writing (any user):
+swarph watchdog --install-service --cell droplet --dry-run
+
+# Install + enable (requires root for /etc/systemd/system writes):
+sudo swarph watchdog --install-service --cell droplet
+```
+
+This writes three files:
+
+| Path | Purpose |
+|------|---------|
+| `/etc/systemd/system/swarph-watchdog.service` | `Type=oneshot`, runs `swarph watchdog --check` |
+| `/etc/systemd/system/swarph-watchdog.timer` | Fires every 5 minutes (`OnUnitActiveSec=5min`) |
+| `/etc/default/swarph-watchdog` | Sets `SWARPH_CELL=<role>` for the service env |
+
+Then runs `systemctl daemon-reload && systemctl enable --now swarph-watchdog.timer`. Idempotent — re-running overwrites with current package version (newer-version semantics).
+
+Monitoring:
+
+```bash
+systemctl status swarph-watchdog.timer       # is it scheduled?
+systemctl list-timers swarph-watchdog.timer  # next fire?
+journalctl -u swarph-watchdog.service -f     # live log
+tail -f /var/log/swarph-watchdog.log         # append-log alternative
+```
+
+Why this matters: pre-v0.7.3, swarph-cli shipped the watchdog code but no install path. Lab ran it via cron (manual setup); droplet never installed it at all. A real production silence-window (drop's ~24min mute 2026-05-14 08:38→09:02 UTC after an Anthropic API error) made the install-gap visible. v0.7.3 closes it for any peer with one command.
+
 ### `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.

{swarph_cli-0.7.1 → swarph_cli-0.7.3}/src/swarph_cli.egg-info/SOURCES.txt

@@ -23,6 +23,9 @@ src/swarph_cli/commands/spawn.py
 src/swarph_cli/commands/watchdog.py
 src/swarph_cli/parsers/__init__.py
 src/swarph_cli/parsers/claude.py
+src/swarph_cli/systemd/swarph-watchdog.default
+src/swarph_cli/systemd/swarph-watchdog.service
+src/swarph_cli/systemd/swarph-watchdog.timer
 tests/test_cell_loader.py
 tests/test_chat_command.py
 tests/test_claude_parser.py

{swarph_cli-0.7.1 → swarph_cli-0.7.3}/tests/test_watchdog.py

@@ -341,6 +341,135 @@ def test_a1_rearms_after_cursor_advance(
     assert send_mock.call_count == 2
 
 
+# ---------------------------------------------------------------------------
+# F3 — tmux pane_activity AND-gate (mother #1087)
+# ---------------------------------------------------------------------------
+
+
+def test_pane_activity_recent_suppresses_a1(
+    isolated_state, stale_cursor, monkeypatch
+):
+    """F3 — cursor stale + alive + unread > 0 but pane_activity recent →
+    suppress A1. Session is working in a long bash block; cursor only
+    updates at turn-end. Same incident class as commander #1092 65-min
+    spam, but caught upstream of F1 marker by checking pane_activity
+    BEFORE firing."""
+    with patch("swarph_cli.commands.watchdog._process_alive", return_value=True), \
+         patch("swarph_cli.commands.watchdog._gateway_unread_count", return_value=3), \
+         patch("swarph_cli.commands.watchdog._tmux_session_exists", return_value=True), \
+         patch("swarph_cli.commands.watchdog._pane_activity_age_sec", return_value=30), \
+         patch("swarph_cli.commands.watchdog._tmux_send_keys") as send_mock:
+        rc = run_watchdog(argv=[
+            "--check", "--cell", "lab",
+            "--cursor", str(stale_cursor),
+            "--threshold", "60",
+            "--pane-activity-threshold", "600",
+        ])
+    assert rc == 0
+    send_mock.assert_not_called()
+
+
+def test_pane_activity_old_falls_through_to_a1(
+    isolated_state, stale_cursor, monkeypatch
+):
+    """F3 — pane_activity OLDER than threshold means session has actually
+    been quiet; A1 still fires. Stop signal compatibility check."""
+    with patch("swarph_cli.commands.watchdog._process_alive", return_value=True), \
+         patch("swarph_cli.commands.watchdog._gateway_unread_count", return_value=3), \
+         patch("swarph_cli.commands.watchdog._tmux_session_exists", return_value=True), \
+         patch("swarph_cli.commands.watchdog._pane_activity_age_sec", return_value=1200), \
+         patch("swarph_cli.commands.watchdog._tmux_send_keys", return_value=True) as send_mock:
+        rc = run_watchdog(argv=[
+            "--check", "--cell", "lab",
+            "--cursor", str(stale_cursor),
+            "--threshold", "60",
+            "--pane-activity-threshold", "600",
+        ])
+    assert rc == 1
+    send_mock.assert_called_once()
+
+
+def test_pane_activity_unavailable_falls_through_to_a1(
+    isolated_state, stale_cursor, monkeypatch
+):
+    """F3 — detection error (tmux missing / older tmux without
+    #{pane_activity}) returns None; A1 still fires. F3 is a strengthening
+    of the gate, not a hard dependency."""
+    with patch("swarph_cli.commands.watchdog._process_alive", return_value=True), \
+         patch("swarph_cli.commands.watchdog._gateway_unread_count", return_value=3), \
+         patch("swarph_cli.commands.watchdog._tmux_session_exists", return_value=True), \
+         patch("swarph_cli.commands.watchdog._pane_activity_age_sec", return_value=None), \
+         patch("swarph_cli.commands.watchdog._tmux_send_keys", return_value=True) as send_mock:
+        rc = run_watchdog(argv=[
+            "--check", "--cell", "lab",
+            "--cursor", str(stale_cursor),
+            "--threshold", "60",
+        ])
+    assert rc == 1
+    send_mock.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# F4 — cell.yaml-pinned cursor_path + tmux_session (mother #1057/#1060 + beta #1061/#1065)
+# ---------------------------------------------------------------------------
+
+
+def test_resolve_cursor_path_cell_yaml_pin_beats_default(isolated_state):
+    """F4 — cell.yaml extra.cursor_path takes precedence over the
+    /tmp/lab-claude-cursor.json fallback when no explicit --cursor."""
+    from swarph_cli.commands.watchdog import _resolve_cursor_path
+    pinned = isolated_state / "custom-cursor.json"
+    assert _resolve_cursor_path("lab", None, str(pinned)) == pinned
+
+
+def test_resolve_cursor_path_explicit_beats_cell_yaml_pin(isolated_state):
+    """F4 — explicit --cursor still wins over cell.yaml pin."""
+    from swarph_cli.commands.watchdog import _resolve_cursor_path
+    explicit = isolated_state / "explicit-cursor.json"
+    pinned = isolated_state / "pinned-cursor.json"
+    assert _resolve_cursor_path("lab", str(explicit), str(pinned)) == explicit
+
+
+def test_resolve_tmux_session_cell_yaml_pin_beats_role(isolated_state):
+    """F4 — cell.yaml extra.tmux_session takes precedence over role
+    default when no explicit --tmux-session."""
+    from swarph_cli.commands.watchdog import _resolve_tmux_session
+    assert _resolve_tmux_session("drop-mother", None, "drop-mother-tmux") == "drop-mother-tmux"
+
+
+def test_resolve_tmux_session_explicit_beats_cell_yaml_pin(isolated_state):
+    """F4 — explicit --tmux-session still wins over cell.yaml pin."""
+    from swarph_cli.commands.watchdog import _resolve_tmux_session
+    assert _resolve_tmux_session("lab", "explicit-name", "pinned-name") == "explicit-name"
+
+
+def test_resolve_tmux_session_falls_back_to_role(isolated_state):
+    """F4 — no explicit + no cell.yaml pin → role itself."""
+    from swarph_cli.commands.watchdog import _resolve_tmux_session
+    assert _resolve_tmux_session("lab", None, None) == "lab"
+
+
+def test_a1_marker_path_keyed_on_role_and_tmux_session(isolated_state):
+    """F4 — marker filename includes both role + tmux_session to prevent
+    sibling-instance marker collisions (mother #1103 follow-up)."""
+    from swarph_cli.commands.watchdog import _a1_marker_path
+    log_path = isolated_state / "wd.log"
+    m1 = _a1_marker_path(log_path, "drop-on-meta-edge", "drop-on-meta-edge")
+    m2 = _a1_marker_path(log_path, "drop-on-meta-edge", "drop-on-meta-edge-2")
+    assert m1 != m2
+    assert m1.name == "a1-fired-drop-on-meta-edge-drop-on-meta-edge.marker"
+    assert m2.name == "a1-fired-drop-on-meta-edge-drop-on-meta-edge-2.marker"
+
+
+def test_a1_marker_path_sanitizes_tmux_session(isolated_state):
+    """F4 — tmux_session sanitized to alphanumeric+underscore so
+    cell.yaml-pinned values with weird chars don't break the filename."""
+    from swarph_cli.commands.watchdog import _a1_marker_path
+    log_path = isolated_state / "wd.log"
+    m = _a1_marker_path(log_path, "lab", "weird/name with spaces!")
+    assert ":" not in m.name and "/" not in m.name and " " not in m.name
+
+
 def test_a2_escalation_clears_a1_marker(
     isolated_state, stale_cursor, monkeypatch
 ):
@@ -361,7 +490,10 @@ def test_a2_escalation_clears_a1_marker(
             "--threshold", "60",
             "--log", str(log_path),
         ])
-    marker = log_path.parent / "a1-fired-lab.marker"
+    # F4 v0.7.2 marker keyed on (role, tmux_session) — tmux_session defaults
+    # to role when no --tmux-session arg + no cell.yaml pin, so filename is
+    # a1-fired-{role}-{role}.marker.
+    marker = log_path.parent / "a1-fired-lab-lab.marker"
     assert marker.exists()
 
     # Now force A2 path (process dead) and confirm marker is gone
@@ -430,3 +562,65 @@ def test_watchdog_log_appends_across_invocations(isolated_state, monkeypatch):
     parsed_second = json.loads(lines[1])
     assert parsed_first["details"]["decision"] == "healthy_cursor_fresh"
     assert parsed_second["details"]["decision"] == "noop_no_unread"
+
+
+# ---------------------------------------------------------------------------
+# --install-service (v0.7.3 — closes ev_6954f748 substrate-component-install)
+# ---------------------------------------------------------------------------
+
+
+def test_install_service_dry_run_writes_no_files(isolated_state, capsys):
+    """--dry-run prints what would be written without touching the filesystem."""
+    rc = run_watchdog(argv=["--install-service", "--cell", "droplet", "--dry-run"])
+    assert rc == 0
+    captured = capsys.readouterr()
+    # Dry-run output goes to stderr
+    assert "DRY RUN" in captured.err
+    assert "cell=droplet" in captured.err
+    # All three target files surface in the preview
+    assert "/etc/systemd/system/swarph-watchdog.service" in captured.err
+    assert "/etc/systemd/system/swarph-watchdog.timer" in captured.err
+    assert "/etc/default/swarph-watchdog" in captured.err
+    # SWARPH_CELL was templated to the requested role
+    assert "SWARPH_CELL=droplet" in captured.err
+    # The bundled service file's identifying line shows up
+    assert "Swarph watchdog one-shot check" in captured.err
+
+
+def test_install_service_dry_run_default_cell_is_lab(isolated_state, capsys):
+    """Without --cell, the dry-run preview keeps SWARPH_CELL=lab default."""
+    rc = run_watchdog(argv=["--install-service", "--dry-run"])
+    assert rc == 0
+    captured = capsys.readouterr()
+    assert "SWARPH_CELL=lab" in captured.err
+
+
+def test_install_service_without_sudo_returns_4(isolated_state, capsys, monkeypatch):
+    """Non-root install (no --dry-run) refuses with helpful message + exit 4."""
+    monkeypatch.setattr("os.geteuid", lambda: 1000)
+    rc = run_watchdog(argv=["--install-service", "--cell", "droplet"])
+    assert rc == 4
+    captured = capsys.readouterr()
+    assert "requires root" in captured.err
+    assert "--dry-run" in captured.err  # hint surfaces
+
+
+def test_bundled_systemd_files_readable():
+    """Package-data manifest correctness — importlib.resources can read all
+    three bundled templates. Regression guard for pyproject package-data
+    declaration."""
+    from swarph_cli.commands.watchdog import _bundled_systemd_files
+
+    files = _bundled_systemd_files()
+    assert set(files.keys()) == {
+        "swarph-watchdog.service",
+        "swarph-watchdog.timer",
+        "swarph-watchdog.default",
+    }
+    # Service file has the expected Type=oneshot shape
+    assert "Type=oneshot" in files["swarph-watchdog.service"]
+    assert "ExecStart=/usr/local/bin/swarph watchdog --check" in files["swarph-watchdog.service"]
+    # Timer fires every 5 minutes
+    assert "OnUnitActiveSec=5min" in files["swarph-watchdog.timer"]
+    # Default file has the SWARPH_CELL=lab template line
+    assert "SWARPH_CELL=lab" in files["swarph-watchdog.default"]