swarph-cli 0.7.5__tar.gz → 0.7.7__tar.gz

{swarph_cli-0.7.5/src/swarph_cli.egg-info → swarph_cli-0.7.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.7.5
+Version: 0.7.7
 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.5 → swarph_cli-0.7.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.7.5"
+version = "0.7.7"
 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.5 → swarph_cli-0.7.7}/src/swarph_cli/__init__.py

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

{swarph_cli-0.7.5 → swarph_cli-0.7.7}/src/swarph_cli/commands/install_hook.py

@@ -22,6 +22,13 @@ Idempotent: rerun safe. Detects existing hook entries pointing at
 Skip when SWARPH_SPAWN=1 env (set by ``swarph spawn``) — avoids
 double-injection when the spawn path already passed the prompt via
 ``--append-system-prompt``.
+
+NOTE (2026-05-17): IF this file grows to manage 3+ DISTINCT hook events
+(beyond SessionStart), revisit adopting a hook framework
+(claude-hooks / cchooks / similar). Solo eval 2026-05-17 deferred
+framework adoption because 1-hook surface didn't justify the
+750-LOC dependency. See lab memory ``project_deferred_decisions.md``
+for the full threshold conditions + revisit checklist.
 """
 
 from __future__ import annotations

{swarph_cli-0.7.5 → swarph_cli-0.7.7}/src/swarph_cli/commands/spawn.py

@@ -201,6 +201,61 @@ def _resolve_cell(args: argparse.Namespace) -> tuple[Cell, Optional[str]]:
     return load_cell(path), requested_role
 
 
+def _validate_routing(cell: Cell) -> None:
+    """Phase 1B v0 (2026-05-19) — read + validate ``cell.extra.routing``.
+
+    Phase 1B-primary architecture commits the cell-membrane framing:
+    Claude CLI is the membrane for Anthropic-side spawns; non-Anthropic
+    cells get a different membrane (currently NOT implemented).
+
+    cell.yaml ``routing`` field shape (v0):
+    ::
+        routing:
+          native: anthropic         # only valid value in v0
+
+    v0 accepts ``routing`` absent (= default anthropic) OR
+    ``routing.native: anthropic``. Any other value raises CellError
+    pointing at Phase 1B v1+ direction.
+
+    Forward-compat: reads via ``Cell.extra`` (same pattern as
+    cursor_path / tmux_session shipped in v0.7.2 before graduating to
+    typed fields in swarph-shared 0.4.x). When swarph-shared graduates
+    ``routing`` to a typed Cell field, this helper swaps to typed
+    access with no API surface change for cell.yaml authors.
+
+    See research/swarph_cli/CELL_MEMBRANE_PHASE_0_RFC.md §5 (Phase 1B)
+    for the architectural context. See lab memory
+    ``project_next_up.md`` for the commander 2026-05-19 decision that
+    Phase 1B is primary + path (c) Anthropic-only v0.
+    """
+    extra = cell.extra or {}
+    routing = extra.get("routing")
+    if routing is None:
+        return  # No routing field → default Anthropic, allow
+    if not isinstance(routing, dict):
+        raise CellError(
+            f"swarph spawn: cell.yaml `routing` must be a mapping, "
+            f"got {type(routing).__name__}. See "
+            f"research/swarph_cli/CELL_MEMBRANE_PHASE_0_RFC.md for the "
+            f"valid v0 schema."
+        )
+    native = routing.get("native", "anthropic")
+    if native == "anthropic":
+        return  # Explicit Anthropic OR default → allow
+    # Any other native value is a Phase 1B v1+ feature not yet built
+    raise CellError(
+        f"swarph spawn: cell.yaml `routing.native: {native!r}` is not "
+        f"supported in v0 of Phase 1B (Anthropic-only). Non-Anthropic "
+        f"routing (e.g. routing.native: openrouter) is Phase 1B v1+ "
+        f"scope, deferred per commander 2026-05-19 until a concrete "
+        f"non-Anthropic-cell use case emerges. For now, remove the "
+        f"`routing.native` field OR set it to 'anthropic' to use the "
+        f"existing Claude CLI spawn path. See "
+        f"research/swarph_cli/CELL_MEMBRANE_PHASE_0_RFC.md §5 for the "
+        f"architectural direction."
+    )
+
+
 def _session_state_exists(session_id: str) -> bool:
     """True if Claude Code already has on-disk session state for this UUID.
 
@@ -346,6 +401,15 @@ def run_spawn(argv: Optional[list[str]] = None) -> int:
         print(f"swarph spawn: {exc}", file=sys.stderr)
         return 1
 
+    # Phase 1B v0 (2026-05-19): validate cell.yaml routing field.
+    # In v0 only `routing.native: anthropic` (or absent) is accepted.
+    # Future non-Anthropic dispatch is Phase 1B v1+ scope.
+    try:
+        _validate_routing(cell)
+    except CellError as exc:
+        print(f"swarph spawn: {exc}", file=sys.stderr)
+        return 1
+
     # When user typed a slot-role (e.g. `swarph spawn drop-on-meta-edge-2`)
     # the cell.yaml resolved to the BASE file (drop-on-meta-edge.yaml) so
     # cell.role = "drop-on-meta-edge". But the operator wants slot 2's
@@ -418,6 +482,32 @@ def run_spawn(argv: Optional[list[str]] = None) -> int:
         )
         return 127
 
+    # Windows-platform known-issues banner. Claude Code's TUI (Ink-based)
+    # has documented input/rendering bugs on Windows native consoles
+    # (conhost.exe in particular). Specific symptom commander hit
+    # 2026-05-17 on workstation-lc: pressing Enter inserts literal 'm'
+    # character instead of submitting. See docs/WINDOWS_KNOWN_ISSUES.md
+    # for the full hypothesis chain + workarounds (Windows Terminal vs
+    # conhost, WSL2 fallback, TERM env injection).
+    #
+    # Banner is suppressed by --no-banner OR when the operator has
+    # already acknowledged via SWARPH_WIN_ACK=1 in env (set once after
+    # reading the doc).
+    if (
+        sys.platform == "win32"
+        and not args.no_banner
+        and not os.environ.get("SWARPH_WIN_ACK")
+    ):
+        print(
+            "swarph spawn: WARNING — Windows shell detected. Claude Code's "
+            "TUI has documented input/rendering issues on Windows native "
+            "consoles (conhost.exe). Known symptom: Enter inserts literal "
+            "'m' character. See docs/WINDOWS_KNOWN_ISSUES.md for "
+            "workarounds (use Windows Terminal not conhost, or WSL2). "
+            "Set SWARPH_WIN_ACK=1 in env to suppress this warning.",
+            file=sys.stderr,
+        )
+
     try:
         os.chdir(cell.cwd)
     except OSError as exc:

{swarph_cli-0.7.5 → swarph_cli-0.7.7}/src/swarph_cli/commands/watchdog.py

@@ -71,7 +71,9 @@ import subprocess
 import sys
 import time
 import urllib.error
+import urllib.parse
 import urllib.request
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Optional
 
@@ -85,12 +87,23 @@ _DEFAULT_GATEWAY_URL = "http://localhost:8788"
 # 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
+# Phase 4 (v0.7.6) — peer-health-event poll defaults. The recovery
+# event we care about is `usage_limit_reset` (throttle cleared; session
+# may be sitting idle unaware of queued DMs). 600s window catches a
+# reset that fired up to 10min before this cron tick. 120s recovery
+# threshold gives the session a brief grace period to notice the reset
+# itself before we send-keys at it.
+_DEFAULT_PEER_HEALTH_WINDOW_SEC = 600
+_DEFAULT_PEER_HEALTH_RECOVERY_THRESHOLD_SEC = 120
+_RECOVERY_EVENT_TYPES = ("usage_limit_reset",)
 
 _USAGE = """\
 Usage:
   swarph watchdog --check [--cell ROLE] [--cursor PATH] [--threshold SEC]
                           [--gateway URL] [--tmux-session NAME]
                           [--peer NAME] [--no-respawn]
+                          [--peer-health-poll] [--peer-health-window-sec SEC]
+                          [--peer-health-recovery-threshold SEC]
                           [--log PATH] [--verbose]
   swarph watchdog --install-service [--cell ROLE] [--dry-run]
 
@@ -127,6 +140,18 @@ Flags:
   --tmux-session NAME  tmux session name; default = cell role
   --peer NAME          mesh peer name for unread-DM query; default = cell name
   --no-respawn         A1 only; don't escalate to A2 (dry-run mode)
+  --peer-health-poll                    Phase 4: also query /peer-health-events.
+                                        On recent usage_limit_reset event, treat
+                                        sessions as wake-candidates even before
+                                        the 30min cursor-staleness threshold.
+                                        Requires MESH_GATEWAY_TOKEN in env.
+  --peer-health-window-sec SEC          how far back to look for recovery
+                                        events; default 600 (10 min)
+  --peer-health-recovery-threshold SEC  min cursor staleness before a recovery
+                                        event promotes the session to wake-
+                                        candidate; default 120 (2 min). Avoids
+                                        poking a session that JUST got reset
+                                        and is already self-recovering.
   --log PATH           append diagnostic log; default $XDG_STATE_HOME/swarph/watchdog.log
   --verbose            also write diagnostics to stderr
 
@@ -282,6 +307,57 @@ def _gateway_unread_count(gateway: str, peer: str, token: Optional[str]) -> Opti
     return None
 
 
+def _gateway_recent_recovery_event(
+    gateway: str,
+    peer: str,
+    window_sec: int,
+    token: Optional[str],
+) -> Optional[dict]:
+    """Phase 4 (v0.7.6) — query /peer-health-events for a recent recovery event.
+
+    Returns the most recent event whose ``event_type`` is in
+    ``_RECOVERY_EVENT_TYPES`` (currently just ``usage_limit_reset``) for
+    this peer within the last ``window_sec`` seconds. Returns None if no
+    such event exists OR if the query fails (treat absence + error as
+    "no override"; the regular cursor-staleness path still applies).
+
+    Why this matters: the lab + drop both hit ``usage_limit_reset`` from
+    Claude's quota system — the throttle clears, but the session has no
+    autonomous mechanism to notice. DMs queued during the throttle sit
+    unread until commander manually chimes the session, OR until the
+    30min cursor-staleness threshold trips A1. Phase 4 closes that gap
+    by lowering the threshold to ``--peer-health-recovery-threshold``
+    (default 2min) once the gateway sees the reset event.
+
+    Detection ≠ recovery distinction: the gateway already CAPTURES these
+    events (claude_session_event_logger.py + POST /peer-health-events).
+    What was missing was the wake-up mechanism — this function plus the
+    fall-through in run_check is the watchdog half of the loop.
+    """
+    since_dt = datetime.now(timezone.utc) - timedelta(seconds=window_sec)
+    since_iso = since_dt.isoformat()
+    query = urllib.parse.urlencode(
+        {"peer": peer, "since": since_iso, "limit": 50},
+    )
+    url = f"{gateway.rstrip('/')}/peer-health-events?{query}"
+    req = urllib.request.Request(url)
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+    try:
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except (urllib.error.URLError, urllib.error.HTTPError, OSError, json.JSONDecodeError):
+        return None
+    events = data.get("events") if isinstance(data, dict) else None
+    if not isinstance(events, list):
+        return None
+    # Server sorts by time DESC, so the first match is the most recent.
+    for ev in events:
+        if isinstance(ev, dict) and ev.get("event_type") in _RECOVERY_EVENT_TYPES:
+            return ev
+    return None
+
+
 def _process_alive(tmux_session: str) -> bool:
     """Detect if a claude process is running inside the tmux session.
 
@@ -515,10 +591,41 @@ def run_check(args: argparse.Namespace) -> int:
     diag["cursor_age_sec"] = cursor_age
 
     if cursor_age <= threshold:
-        # Cursor recent — Claude has been active. No action.
-        diag["decision"] = "healthy_cursor_fresh"
-        _log_event(log_path, "noop", diag, verbose)
-        return 0
+        # Phase 4 (v0.7.6) — peer-health-event override. If the gateway
+        # observed a recent recovery event (usage_limit_reset) for this
+        # peer AND the cursor is at least somewhat stale, fall through
+        # to the A1 path so an idle-after-reset session gets nudged.
+        # When --peer-health-poll is OFF, behavior is identical to v0.7.5.
+        if args.peer_health_poll:
+            recovery_event = _gateway_recent_recovery_event(
+                gateway, peer, args.peer_health_window_sec, token,
+            )
+            diag["peer_health_poll"] = True
+            diag["recovery_event_seen"] = bool(recovery_event)
+            if recovery_event:
+                diag["recovery_event_type"] = recovery_event.get("event_type")
+                diag["recovery_event_time"] = recovery_event.get("time")
+            if recovery_event and cursor_age > args.peer_health_recovery_threshold:
+                # Promote to wake-candidate. Don't return — fall through
+                # below to the existing process_alive / unread / F1-F3
+                # gates, which still get a vote. This is a threshold
+                # override, not a gate bypass.
+                diag["phase4_override"] = "fall_through_to_a1"
+            else:
+                # Either no recovery event, OR cursor is fresh enough
+                # that the session is likely self-recovering. No action.
+                diag["decision"] = (
+                    "healthy_cursor_fresh_recovery_too_recent"
+                    if recovery_event
+                    else "healthy_cursor_fresh"
+                )
+                _log_event(log_path, "noop", diag, verbose)
+                return 0
+        else:
+            # Cursor recent — Claude has been active. No action.
+            diag["decision"] = "healthy_cursor_fresh"
+            _log_event(log_path, "noop", diag, verbose)
+            return 0
 
     # FALLBACK signal: pgrep claude (per mother #1021 AND-gate)
     process_alive = _process_alive(tmux_session)
@@ -799,6 +906,26 @@ def run_watchdog(argv: Optional[list[str]] = None) -> int:
     p.add_argument("--tmux-session", default=None)
     p.add_argument("--peer", default=None)
     p.add_argument("--no-respawn", action="store_true")
+    p.add_argument(
+        "--peer-health-poll", action="store_true",
+        help="Phase 4 (v0.7.6): also query mesh-gateway /peer-health-events. "
+             "On recent usage_limit_reset event, treat sessions as wake-"
+             "candidates even before the 30min cursor-staleness threshold. "
+             "Requires MESH_GATEWAY_TOKEN in env. Default OFF (opt-in).",
+    )
+    p.add_argument(
+        "--peer-health-window-sec",
+        type=int,
+        default=_DEFAULT_PEER_HEALTH_WINDOW_SEC,
+        help="Phase 4: window for recovery-event lookup; default 600 (10 min).",
+    )
+    p.add_argument(
+        "--peer-health-recovery-threshold",
+        type=int,
+        default=_DEFAULT_PEER_HEALTH_RECOVERY_THRESHOLD_SEC,
+        help="Phase 4: min cursor staleness for recovery event to promote "
+             "session to wake-candidate; default 120 (2 min).",
+    )
     p.add_argument("--log", default=None)
     p.add_argument("--verbose", action="store_true")
 

{swarph_cli-0.7.5 → swarph_cli-0.7.7/src/swarph_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.7.5
+Version: 0.7.7
 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.5 → swarph_cli-0.7.7}/tests/test_spawn_command.py

@@ -428,3 +428,108 @@ def test_build_claude_argv_uses_resume_when_state_exists(fake_cell_yaml, tmp_pat
     assert "--session-id" not in argv
     # UUID still passed (just as --resume's value not --session-id's)
     assert uuid in argv
+
+
+# ---------------------------------------------------------------------------
+# Phase 1B v0 — cell.yaml routing field (2026-05-19)
+# ---------------------------------------------------------------------------
+
+
+def test_validate_routing_absent_allows(fake_cell_yaml):
+    """No `routing` field → default Anthropic, _validate_routing returns silently."""
+    from swarph_cli.commands.spawn import _validate_routing
+    cell = load_cell(fake_cell_yaml)
+    # fake_cell_yaml has no routing field → should pass
+    _validate_routing(cell)  # no exception = pass
+
+
+def test_validate_routing_explicit_anthropic_allows(tmp_path):
+    """`routing.native: anthropic` → allowed (explicit form)."""
+    from swarph_cli.commands.spawn import _validate_routing
+    payload = {
+        "schema_version": SCHEMA_VERSION_V1,
+        "name": "lab-ovh",
+        "role": "lab-test",
+        "cwd": str(tmp_path),
+        "provider": "claude",
+        "routing": {"native": "anthropic"},
+    }
+    p = tmp_path / "cell.yaml"
+    p.write_text(yaml.safe_dump(payload), encoding="utf-8")
+    cell = load_cell(p)
+    _validate_routing(cell)  # no exception = pass
+
+
+def test_validate_routing_non_anthropic_rejects(tmp_path):
+    """`routing.native: openrouter` → rejected with v0 + v1 direction message."""
+    from swarph_cli.commands.spawn import _validate_routing
+    from swarph_cli.cell import CellError
+    payload = {
+        "schema_version": SCHEMA_VERSION_V1,
+        "name": "lab-ovh",
+        "role": "lab-test",
+        "cwd": str(tmp_path),
+        "provider": "claude",
+        "routing": {"native": "openrouter"},
+    }
+    p = tmp_path / "cell.yaml"
+    p.write_text(yaml.safe_dump(payload), encoding="utf-8")
+    cell = load_cell(p)
+    with pytest.raises(CellError) as exc_info:
+        _validate_routing(cell)
+    err = str(exc_info.value)
+    assert "openrouter" in err
+    assert "v0" in err
+    assert "Phase 1B" in err
+    assert "anthropic" in err  # should point at the only valid value
+
+
+def test_validate_routing_non_dict_rejects(tmp_path):
+    """`routing: "anthropic"` (string instead of dict) → schema error."""
+    from swarph_cli.commands.spawn import _validate_routing
+    from swarph_cli.cell import CellError
+    payload = {
+        "schema_version": SCHEMA_VERSION_V1,
+        "name": "lab-ovh",
+        "role": "lab-test",
+        "cwd": str(tmp_path),
+        "provider": "claude",
+        "routing": "anthropic",  # WRONG — should be dict
+    }
+    p = tmp_path / "cell.yaml"
+    p.write_text(yaml.safe_dump(payload), encoding="utf-8")
+    cell = load_cell(p)
+    with pytest.raises(CellError) as exc_info:
+        _validate_routing(cell)
+    assert "mapping" in str(exc_info.value)
+
+
+def test_validate_routing_omitted_native_allows(tmp_path):
+    """`routing: {}` (empty dict, no native key) → defaults to anthropic, allows."""
+    from swarph_cli.commands.spawn import _validate_routing
+    payload = {
+        "schema_version": SCHEMA_VERSION_V1,
+        "name": "lab-ovh",
+        "role": "lab-test",
+        "cwd": str(tmp_path),
+        "provider": "claude",
+        "routing": {},
+    }
+    p = tmp_path / "cell.yaml"
+    p.write_text(yaml.safe_dump(payload), encoding="utf-8")
+    cell = load_cell(p)
+    _validate_routing(cell)  # default anthropic = allowed
+
+
+def test_run_spawn_rejects_non_anthropic_routing_in_dry_run(
+    fake_cell_yaml, isolated_xdg, capsys
+):
+    """End-to-end: `swarph spawn --dry-run` with non-anthropic routing → exit 1 + error message."""
+    payload = yaml.safe_load(fake_cell_yaml.read_text())
+    payload["routing"] = {"native": "gemini"}
+    fake_cell_yaml.write_text(yaml.safe_dump(payload))
+    rc = run_spawn(["--dry-run", str(fake_cell_yaml)])
+    assert rc == 1
+    captured = capsys.readouterr()
+    assert "gemini" in captured.err
+    assert "Phase 1B" in captured.err