swarph-cli 0.7.4__tar.gz → 0.7.6__tar.gz

{swarph_cli-0.7.4/src/swarph_cli.egg-info → swarph_cli-0.7.6}/PKG-INFO

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

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

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

{swarph_cli-0.7.4 → swarph_cli-0.7.6}/src/swarph_cli/commands/spawn.py

@@ -27,6 +27,7 @@ import argparse
 import os
 import shutil
 import sys
+from pathlib import Path
 from typing import Optional
 
 from swarph_cli import __version__
@@ -200,6 +201,33 @@ def _resolve_cell(args: argparse.Namespace) -> tuple[Cell, Optional[str]]:
     return load_cell(path), requested_role
 
 
+def _session_state_exists(session_id: str) -> bool:
+    """True if Claude Code already has on-disk session state for this UUID.
+
+    Closes v0.7.4 spawn-bug surfaced 2026-05-14 post-reboot (DM #1255):
+    `claude --session-id <UUID>` rejects with "Session ID <UUID> is already
+    in use" when session-state files exist on disk, even after reboot
+    (files persist; the in-use check is filesystem-based not runtime-lock-
+    based). Switching to `claude --resume <UUID>` is the correct semantic
+    when the UUID's state already exists.
+
+    Probes the three filesystem locations Claude Code stores per-session
+    state in: ~/.claude/file-history/<UUID>, ~/.claude/session-env/<UUID>,
+    and ~/.claude/projects/<project-hash>/<UUID>.jsonl (the latter
+    discovered via glob since project-hash varies).
+    """
+    claude_dir = Path.home() / ".claude"
+    if (claude_dir / "file-history" / session_id).exists():
+        return True
+    if (claude_dir / "session-env" / session_id).exists():
+        return True
+    projects_dir = claude_dir / "projects"
+    if projects_dir.exists():
+        for _ in projects_dir.glob(f"*/{session_id}.jsonl"):
+            return True
+    return False
+
+
 def _build_claude_argv(
     cell: Cell,
     session_id: str,
@@ -208,7 +236,14 @@ def _build_claude_argv(
     effective_role: Optional[str] = None,
 ) -> list[str]:
     name_value = effective_role if effective_role is not None else cell.role
-    argv: list[str] = ["claude", "--name", name_value, "--session-id", session_id]
+    # v0.7.5: auto-detect existing session state and switch from --session-id
+    # (create-new-with-pinned-UUID semantic) to --resume (attach-to-existing
+    # semantic). Both pass the same UUID; the verb determines whether claude
+    # treats it as fresh-create vs resume-existing.
+    if _session_state_exists(session_id):
+        argv: list[str] = ["claude", "--name", name_value, "--resume", session_id]
+    else:
+        argv = ["claude", "--name", name_value, "--session-id", session_id]
 
     if not no_starter:
         starter = read_starter_prompt(cell)

{swarph_cli-0.7.4 → swarph_cli-0.7.6}/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.4 → swarph_cli-0.7.6/src/swarph_cli.egg-info}/PKG-INFO

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

@@ -339,3 +339,92 @@ def test_run_spawn_dry_run_redacts_starter_prompt_in_command(
     assert rc == 0
     assert "redacted" not in captured.out  # the literal word from the prompt
     assert "starter prompt>" in captured.out  # the redaction marker
+
+
+# ---------------------------------------------------------------------------
+# v0.7.5 — _session_state_exists + --resume on existing session
+# ---------------------------------------------------------------------------
+#
+# Closes the bug surfaced 2026-05-14 post-reboot: claude --session-id <UUID>
+# rejects with "Session ID <UUID> is already in use" when on-disk session
+# state exists, even after host reboot (files persist; check is filesystem-
+# based not runtime-lock-based). Fix: detect existing state + switch from
+# --session-id (create-new semantic) to --resume (attach-existing semantic).
+
+
+def test_session_state_exists_false_for_fresh_uuid(tmp_path, monkeypatch):
+    """No filesystem state for the UUID = fresh; _build_claude_argv uses
+    --session-id (create-new semantic)."""
+    from swarph_cli.commands.spawn import _session_state_exists
+
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    fresh_uuid = "00000000-0000-0000-0000-000000000000"
+    assert _session_state_exists(fresh_uuid) is False
+
+
+def test_session_state_exists_true_when_file_history_present(tmp_path, monkeypatch):
+    """File-history dir alone is enough to flip detection (any one of the
+    three location signals triggers)."""
+    from swarph_cli.commands.spawn import _session_state_exists
+
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    uuid = "a30e406c-8bae-4ea2-8cb2-fb0dff35a6f0"
+    (tmp_path / ".claude" / "file-history" / uuid).mkdir(parents=True)
+    assert _session_state_exists(uuid) is True
+
+
+def test_session_state_exists_true_when_session_env_present(tmp_path, monkeypatch):
+    from swarph_cli.commands.spawn import _session_state_exists
+
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    uuid = "a30e406c-8bae-4ea2-8cb2-fb0dff35a6f0"
+    (tmp_path / ".claude" / "session-env").mkdir(parents=True)
+    (tmp_path / ".claude" / "session-env" / uuid).write_text("")
+    assert _session_state_exists(uuid) is True
+
+
+def test_session_state_exists_true_when_project_jsonl_present(tmp_path, monkeypatch):
+    """Projects path varies by project-hash; glob discovers any match."""
+    from swarph_cli.commands.spawn import _session_state_exists
+
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    uuid = "a30e406c-8bae-4ea2-8cb2-fb0dff35a6f0"
+    proj = tmp_path / ".claude" / "projects" / "-some-project-hash"
+    proj.mkdir(parents=True)
+    (proj / f"{uuid}.jsonl").write_text("{}\n")
+    assert _session_state_exists(uuid) is True
+
+
+def test_build_claude_argv_uses_session_id_when_fresh(fake_cell_yaml, tmp_path, monkeypatch):
+    """No prior session state → --session-id (create-new) verb."""
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    cell = load_cell(fake_cell_yaml)
+    argv = _build_claude_argv(
+        cell=cell,
+        session_id="00000000-0000-0000-0000-000000000000",
+        no_starter=True,
+        passthrough=[],
+    )
+    assert "--session-id" in argv
+    assert "--resume" not in argv
+
+
+def test_build_claude_argv_uses_resume_when_state_exists(fake_cell_yaml, tmp_path, monkeypatch):
+    """Prior session state exists → --resume (attach-existing) verb.
+
+    Closes the v0.7.4 spawn-after-reboot rejection class.
+    """
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    uuid = "a30e406c-8bae-4ea2-8cb2-fb0dff35a6f0"
+    (tmp_path / ".claude" / "file-history" / uuid).mkdir(parents=True)
+    cell = load_cell(fake_cell_yaml)
+    argv = _build_claude_argv(
+        cell=cell,
+        session_id=uuid,
+        no_starter=True,
+        passthrough=[],
+    )
+    assert "--resume" in argv
+    assert "--session-id" not in argv
+    # UUID still passed (just as --resume's value not --session-id's)
+    assert uuid in argv