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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.7.0
+Version: 0.7.1
 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.1}/pyproject.toml

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

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

@@ -263,6 +263,54 @@ def _spawn_via_swarph(role: str, tmux_session: str) -> bool:
         return False
 
 
+def _a1_marker_path(log_path: Path, role: str) -> 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`` 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.
+    """
+    return log_path.parent / f"a1-fired-{role}.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 = {
@@ -323,13 +371,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)
+    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 +394,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 +423,26 @@ 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
+
+    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
 

{swarph_cli-0.7.0 → swarph_cli-0.7.1/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.1
 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.1}/tests/test_watchdog.py

@@ -228,27 +228,154 @@ def test_stale_cursor_alive_tmux_missing_fires_a2(
 
 
 # ---------------------------------------------------------------------------
-# Detection error — gateway unreachable → assume unread (still try A1)
+# F2 — fail-closed on unread=None
 # ---------------------------------------------------------------------------
 
 
-def test_gateway_unreachable_does_not_block_a1(
+def test_gateway_unread_unknown_returns_noop(
     isolated_state, stale_cursor, monkeypatch, capsys
 ):
-    """If gateway is down, return None for unread — watchdog still tries A1
-    (assume unread; gateway-down ≠ session-dead)."""
+    """F2 fix (commander #1092 / droplet #1089) — if gateway returns None
+    for unread count, fail CLOSED rather than firing A1.
+
+    Old behavior fired A1 on None ("gateway down ≠ session dead"); production
+    surfaced the case where gateway is fine but the count is still None
+    (parser mismatch, transient error), and A1 spammed the tmux buffer
+    13 times across 65min. New contract: 'respect peer-time when uncertain' —
+    trade false-negative (occasional missed wake on real strands) for
+    elimination of the false-positive spam class.
+    """
     with patch("swarph_cli.commands.watchdog._process_alive", return_value=True), \
          patch("swarph_cli.commands.watchdog._gateway_unread_count", return_value=None), \
          patch("swarph_cli.commands.watchdog._tmux_session_exists", return_value=True), \
-         patch("swarph_cli.commands.watchdog._tmux_send_keys", return_value=True) as send_mock:
+         patch("swarph_cli.commands.watchdog._tmux_send_keys") as send_mock:
         rc = run_watchdog(argv=[
             "--check", "--cell", "lab",
             "--cursor", str(stale_cursor),
             "--threshold", "60",
         ])
-    # unread=None passes the `if unread == 0` short-circuit and goes to A1
-    assert rc == 1
-    send_mock.assert_called_once()
+    assert rc == 0
+    send_mock.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# F1 — same-stale-window A1 suppression
+# ---------------------------------------------------------------------------
+
+
+def test_a1_fires_at_most_once_per_stale_window(
+    isolated_state, stale_cursor, monkeypatch
+):
+    """F1 fix — repeated checks within the same stale window (cursor mtime
+    unchanged) fire A1 only on the first invocation; subsequent checks
+    noop with reason 'noop_a1_already_fired_this_window'.
+
+    Production incident (commander #1092): cron at */5 fired A1 13 times
+    across 65min into an actively-working session's tmux buffer because
+    cursor only updates at turn-end, not mid-bash. After F1, watchdog
+    fires AT MOST ONCE per stale window; re-arms on cursor advance.
+    """
+    log_path = isolated_state / "wd.log"
+    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._tmux_send_keys", return_value=True) as send_mock:
+        # First invocation — A1 fires
+        rc1 = run_watchdog(argv=[
+            "--check", "--cell", "lab",
+            "--cursor", str(stale_cursor),
+            "--threshold", "60",
+            "--log", str(log_path),
+        ])
+        # Second invocation, no cursor change — A1 must NOT fire again
+        rc2 = run_watchdog(argv=[
+            "--check", "--cell", "lab",
+            "--cursor", str(stale_cursor),
+            "--threshold", "60",
+            "--log", str(log_path),
+        ])
+        # Third invocation — still suppressed
+        rc3 = run_watchdog(argv=[
+            "--check", "--cell", "lab",
+            "--cursor", str(stale_cursor),
+            "--threshold", "60",
+            "--log", str(log_path),
+        ])
+    assert rc1 == 1
+    assert rc2 == 0
+    assert rc3 == 0
+    assert send_mock.call_count == 1  # NOT 3 — suppressed on rc2 and rc3
+    # Second log entry should record the suppression reason explicitly
+    lines = [ln for ln in log_path.read_text().splitlines() if ln.strip()]
+    parsed_second = json.loads(lines[1])
+    assert parsed_second["details"]["decision"] == "noop_a1_already_fired_this_window"
+
+
+def test_a1_rearms_after_cursor_advance(
+    isolated_state, stale_cursor, monkeypatch
+):
+    """F1 fix — after the suppressed window, if cursor advances (session
+    recovered, even briefly), the marker no longer matches and subsequent
+    stale windows fire A1 again. Ensures we don't permanently mute A1 on
+    a peer that recovered then re-stranded."""
+    import os as _os
+    with patch("swarph_cli.commands.watchdog._process_alive", return_value=True), \
+         patch("swarph_cli.commands.watchdog._gateway_unread_count", return_value=2), \
+         patch("swarph_cli.commands.watchdog._tmux_session_exists", return_value=True), \
+         patch("swarph_cli.commands.watchdog._tmux_send_keys", return_value=True) as send_mock:
+        # First A1 fires
+        run_watchdog(argv=[
+            "--check", "--cell", "lab",
+            "--cursor", str(stale_cursor),
+            "--threshold", "60",
+        ])
+        # Simulate cursor advancing 5min — but still stale (8min > 60s threshold)
+        new_mtime = time.time() - 480
+        _os.utime(stale_cursor, (new_mtime, new_mtime))
+        # Second invocation — A1 must fire again (cursor advanced ⇒ new window)
+        run_watchdog(argv=[
+            "--check", "--cell", "lab",
+            "--cursor", str(stale_cursor),
+            "--threshold", "60",
+        ])
+    assert send_mock.call_count == 2
+
+
+def test_a2_escalation_clears_a1_marker(
+    isolated_state, stale_cursor, monkeypatch
+):
+    """F1 fix — A2 respawn path clears the marker so the post-respawn
+    session starts with a clean slate (otherwise a recovered+re-stranded
+    session would inherit a stale marker matching the OLD cursor_mtime,
+    which is theoretically possible since marker stores cursor_mtime not
+    epoch-now). Defensive cleanup."""
+    log_path = isolated_state / "wd.log"
+    with patch("swarph_cli.commands.watchdog._process_alive", return_value=True), \
+         patch("swarph_cli.commands.watchdog._gateway_unread_count", return_value=5), \
+         patch("swarph_cli.commands.watchdog._tmux_session_exists", return_value=True), \
+         patch("swarph_cli.commands.watchdog._tmux_send_keys", return_value=True):
+        # First fire — record marker
+        run_watchdog(argv=[
+            "--check", "--cell", "lab",
+            "--cursor", str(stale_cursor),
+            "--threshold", "60",
+            "--log", str(log_path),
+        ])
+    marker = log_path.parent / "a1-fired-lab.marker"
+    assert marker.exists()
+
+    # Now force A2 path (process dead) and confirm marker is gone
+    with patch("swarph_cli.commands.watchdog._process_alive", return_value=False), \
+         patch("swarph_cli.commands.watchdog._gateway_unread_count", return_value=5), \
+         patch("swarph_cli.commands.watchdog._tmux_session_exists", return_value=False), \
+         patch("swarph_cli.commands.watchdog._spawn_via_swarph", return_value=True):
+        run_watchdog(argv=[
+            "--check", "--cell", "lab",
+            "--cursor", str(stale_cursor),
+            "--threshold", "60",
+            "--log", str(log_path),
+        ])
+    assert not marker.exists()
 
 
 # ---------------------------------------------------------------------------