swarph-cli 0.7.0__tar.gz → 0.7.2__tar.gz

{swarph_cli-0.7.0/src/swarph_cli.egg-info → swarph_cli-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.7.0
+Version: 0.7.2
 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

{swarph_cli-0.7.0 → swarph_cli-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.7.0"
+version = "0.7.2"
 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" }

{swarph_cli-0.7.0 → swarph_cli-0.7.2}/src/swarph_cli/__init__.py

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

{swarph_cli-0.7.0 → swarph_cli-0.7.2}/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:
@@ -137,10 +142,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 +173,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 +320,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,6 +388,67 @@ def _spawn_via_swarph(role: str, tmux_session: str) -> bool:
         return False
 
 
+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
+    discipline. Cleared on cursor-advance OR A2 escalation. Used to suppress
+    repeat A1 fires within the same stale window — fix for the spam incident
+    where cron fired A1 every 5min for 65min into an active session's tmux
+    input buffer (commander #1092 + droplet #1087).
+
+    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.
+    """
+    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:
+    """Returns True if a previous A1 was fired with this exact cursor_mtime.
+
+    Same cursor_mtime ⇒ no cursor advance since last fire ⇒ we're still in
+    the same stale window ⇒ another A1 would spam. Suppresses the fire.
+    """
+    try:
+        return int(marker.read_text().strip()) == cursor_mtime
+    except (FileNotFoundError, OSError, ValueError):
+        return False
+
+
+def _record_a1_fired(marker: Path, cursor_mtime: int) -> None:
+    """Best-effort marker write; failures are logged elsewhere but never block."""
+    try:
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.write_text(str(cursor_mtime))
+    except OSError:
+        pass
+
+
+def _clear_a1_marker(marker: Path) -> None:
+    """Idempotent marker removal. Called on A2 escalation paths."""
+    try:
+        marker.unlink()
+    except (FileNotFoundError, OSError):
+        pass
+
+
 def _log_event(log_path: Path, event: str, details: dict, verbose: bool = False) -> None:
     log_path.parent.mkdir(parents=True, exist_ok=True)
     entry = {
@@ -283,10 +469,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")
@@ -298,6 +491,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
@@ -323,13 +519,19 @@ def run_check(args: argparse.Namespace) -> int:
     unread = _gateway_unread_count(gateway, peer, token)
     diag["unread_count"] = unread
 
-    # Decision matrix:
-    # cursor_stale + process_alive + unread > 0  → A1 (alive but throttled, prompt may unblock)
+    # Decision matrix (post commander #1092 + droplet #1087 + #1089 hardening):
     # cursor_stale + not process_alive            → A2 (dead, respawn regardless of unread)
+    # cursor_stale + process_alive + unread > 0   → A1 (alive but throttled, prompt may unblock)
     # cursor_stale + process_alive + unread = 0   → noop (no DMs to drain anyway)
-    # cursor_stale + unread = None                → A1 (assume unread; gateway down ≠ session dead)
+    # 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, tmux_session)
+    diag["a1_marker"] = str(marker)
 
     if not process_alive:
+        # A2 escalation — clear the A1 marker so the next A1 (after respawn) fires.
+        _clear_a1_marker(marker)
         diag["decision"] = "a2_respawn_process_dead"
         if args.no_respawn:
             diag["dry_run_skip"] = True
@@ -340,17 +542,27 @@ def run_check(args: argparse.Namespace) -> int:
         _log_event(log_path, "a2_respawn", diag, verbose)
         return 2 if spawn_ok else 4
 
-    # Process is alive but cursor is stale — A1 escalation
+    # Process is alive but cursor is stale.
+    # F2 — fail-closed when unread can't be verified. Trade false-negative for
+    # false-positive ("respect peer-time when uncertain" per droplet #1089).
+    # Production incident shape (commander #1092): gateway returned None for
+    # unread; old code fell through to A1, spamming the tmux buffer for 65min.
+    if unread is None:
+        diag["decision"] = "noop_unread_unknown"
+        _log_event(log_path, "noop", diag, verbose)
+        return 0
+
     if unread == 0:
         diag["decision"] = "noop_no_unread"
         _log_event(log_path, "noop", diag, verbose)
         return 0
 
-    diag["decision"] = "a1_send_keys"
     if not _tmux_session_exists(tmux_session):
         # Process alive somewhere but tmux session gone — partial state.
         # Treat as A2 case: respawn fresh sibling.
+        _clear_a1_marker(marker)
         diag["tmux_missing"] = True
+        diag["decision"] = "a2_respawn_tmux_missing"
         if args.no_respawn:
             _log_event(log_path, "a2_dry_run", diag, verbose)
             return 2
@@ -359,12 +571,41 @@ def run_check(args: argparse.Namespace) -> int:
         _log_event(log_path, "a2_respawn", diag, verbose)
         return 2 if spawn_ok else 4
 
+    # F1 — same-stale-window suppression. If A1 already fired at this exact
+    # cursor_mtime, further A1s would only stack wake-prompts in the tmux
+    # input buffer (commander #1092: 13 fires across 65min on a session that
+    # was actively working but cursor only updates at turn-end). Fire AT MOST
+    # ONCE per stale window; re-arm only when cursor advances (recovery) or
+    # A2 escalates (respawn clears the marker above).
+    if _a1_already_fired_at(marker, cursor_mtime):
+        diag["decision"] = "noop_a1_already_fired_this_window"
+        _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, "
         f"unread={unread}; please drain inbox"
     )
     sent = _tmux_send_keys(tmux_session, wake_text)
     diag["send_keys_ok"] = sent
+    if sent:
+        _record_a1_fired(marker, cursor_mtime)
     _log_event(log_path, "a1_send_keys", diag, verbose)
     return 1 if sent else 4
 
@@ -385,6 +626,14 @@ def run_watchdog(argv: Optional[list[str]] = None) -> int:
     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)

{swarph_cli-0.7.0 → swarph_cli-0.7.2/src/swarph_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.7.0
+Version: 0.7.2
 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