swarph-cli 0.72.4__tar.gz → 0.72.5__tar.gz

{swarph_cli-0.72.4/src/swarph_cli.egg-info → swarph_cli-0.72.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.72.4
+Version: 0.72.5
 Summary: The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, per-invocation `gh` identity routing, a silent DM-wake hook, session `import`, and a stranded-session `watchdog`.
 Author: Pierre Samson, Claude Opus
 License: MIT

{swarph_cli-0.72.4 → swarph_cli-0.72.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.72.4"
+version = "0.72.5"
 description = "The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, per-invocation `gh` identity routing, a silent DM-wake hook, session `import`, and a stranded-session `watchdog`."
 readme = "README.md"
 license = { text = "MIT" }

{swarph_cli-0.72.4 → swarph_cli-0.72.5}/src/swarph_cli/__init__.py

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

{swarph_cli-0.72.4 → swarph_cli-0.72.5}/src/swarph_cli/commands/mesh.py

@@ -3392,6 +3392,35 @@ def _monitor_deliver(state: MonitorState) -> None:
         _write_ledgers_atomic(state.ledgers_path, state.ledgers)
 
 
+def _type_slash_clear(target: str) -> bool:
+    """Type ``/clear`` and submit it. One command, not a wake."""
+    for argv in (
+        ["tmux", "send-keys", "-t", target, "-l", "/clear"],
+        ["tmux", "send-keys", "-t", target, "Enter"],
+    ):
+        try:
+            r = subprocess.run(
+                argv, capture_output=True, timeout=5,
+                text=True, encoding="utf-8", errors="replace",
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return False
+        if r.returncode != 0:
+            return False
+    return True
+
+
+def _maybe_rowclear(state: MonitorState) -> str:
+    """Card #432. Off and non-opted-in cells return before any pane read."""
+    from swarph_cli.rowclear import maybe_rowclear
+    return maybe_rowclear(
+        state,
+        agent_running=_agent_running,
+        http_get=_http_get_json,
+        type_clear=_type_slash_clear,
+    )
+
+
 def _monitor_iteration(state: MonitorState, *, poll_channels: bool = True) -> None:
     state.iterations += 1
     last_id = int(state.observed.get("last_msg_id", 0))
@@ -3456,6 +3485,9 @@ def _monitor_iteration(state: MonitorState, *, poll_channels: bool = True) -> No
     # A delivery deferred by the idle guard (or failed against a dead sink) must
     # still land even though no NEW mail arrived, so this runs on every poll.
     _monitor_deliver(state)
+    # Card #432: after delivery, so an owed DM (cursor still behind) blocks
+    # the clear. off / not-opted-in return before any pane or board read.
+    _maybe_rowclear(state)
     # The observation cursor is written BEFORE delivery, while last_wake_at is
     # still unknown. A wake that landed this poll has to be written again or
     # cursor.json keeps the 0.0 default after a real keystroke (#405).

swarph_cli-0.72.5/src/swarph_cli/commands/rowclear_hook.py

@@ -0,0 +1,42 @@
+"""``swarph rowclear-hook`` — SessionStart hook for card #432.
+
+Claude Code runs this on SessionStart. When the payload's ``source`` is
+``clear``, the new ``session_id`` is written into the role's
+``<role>.session-id`` pin (the role is ``SWARPH_SELF``). Spawn then
+resumes that id instead of the pre-clear session.
+
+Exit 0 on every path. A hook that fails closed refuses the session.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from swarph_cli import identity
+from swarph_cli.rowclear import apply_sessionstart_clear
+
+
+def _read_stdin() -> dict:
+    try:
+        if not sys.stdin.isatty():
+            raw = sys.stdin.read()
+            if raw.strip():
+                return json.loads(raw.lstrip("\ufeff"))
+    except Exception:
+        return {}
+    return {}
+
+
+def run_rowclear_hook(argv: list[str] | None = None) -> int:
+    del argv
+    role = identity.declared(env=identity.SELF_ONLY)[0] or ""
+    if not role:
+        print("rowclear-hook: SWARPH_SELF unset — pin not rewritten",
+              file=sys.stderr)
+        return 0
+    try:
+        apply_sessionstart_clear(_read_stdin(), role)
+    except Exception as exc:
+        print(f"rowclear-hook: {exc}", file=sys.stderr)
+    return 0

{swarph_cli-0.72.4 → swarph_cli-0.72.5}/src/swarph_cli/guide/GUIDE.md

@@ -543,6 +543,7 @@ answers `--help`; hook-plumbing verbs are the callbacks hooks invoke, not comman
 - `swarph protocol-handler` -- register `swarph://` as an OS URL-scheme handler.
 - `swarph ratify` -- witness flip that admits an onboarded peer; takes the peer name and `--reason`.
 - `swarph rights` -- RBAC rights over the gateway (companion of `swarph group`).
+- `swarph rowclear-hook` -- SessionStart hook (card #432): when `source` is `clear`, write the new session id into the role's `<role>.session-id` pin so the next spawn resumes the cleared session.
 - `swarph scan` -- statically scan an artifact for dangerous patterns before publish.
 - `swarph schedule` -- the gateway's scheduled events: create, list, get, enable, disable, delete, fire-now.
 - `swarph service` -- stand up a $0 subscription-LLM HTTP lane.

{swarph_cli-0.72.4 → swarph_cli-0.72.5}/src/swarph_cli/main.py

@@ -92,6 +92,7 @@ _VERB_HANDLERS: dict[str, str] = {
     "install-wake-hook": "swarph_cli.commands.install_wake_hook.run_install_wake_hook",
     "wake-hook-output": "swarph_cli.commands.wake_hook_output.run_wake_hook_output",
     "postcompact-hook-output": "swarph_cli.commands.postcompact_hook_output.run_postcompact_hook_output",
+    "rowclear-hook": "swarph_cli.commands.rowclear_hook.run_rowclear_hook",
     "install-postcompact-hook": "swarph_cli.commands.install_postcompact_hook.run_install_postcompact_hook",
     "install-opencode-plugin": "swarph_cli.commands.install_opencode_plugin.run_install_opencode_plugin",
     "memory-emit-hook": "swarph_cli.commands.memory_emit_hook.run_memory_emit_hook",
@@ -147,8 +148,13 @@ def _verbs_block(width: int = 78) -> str:
     import textwrap
     verbs = registered_verbs()
     head = f"Verbs ({len(verbs)}) -- each has --help and a guide entry (swarph guide <verb>):"
-    return head + "\n" + textwrap.fill(", ".join(verbs), width=width,
-                                       initial_indent="  ", subsequent_indent="  ") + "\n"
+    # break_on_hyphens would split a verb at a wrap (wake-hook-output
+    # became "wake-hook-" / "output" once the list grew past the width).
+    return head + "\n" + textwrap.fill(
+        ", ".join(verbs), width=width,
+        initial_indent="  ", subsequent_indent="  ",
+        break_on_hyphens=False, break_long_words=False,
+    ) + "\n"
 
 
 def _build_parser() -> argparse.ArgumentParser:

swarph_cli-0.72.5/src/swarph_cli/rowclear.py

@@ -0,0 +1,239 @@
+"""Card #432: type ``/clear`` at a row boundary, and follow the new session.
+
+The monitor types ``/clear`` into an opted-in role cell's tmux pane only
+when the cell holds no live row, the pane reads idle, and no DM is owed.
+``SWARPH_ROWCLEAR`` is ``off`` (default), ``shadow`` (log a would-clear,
+type nothing), or ``live``. v1 opt-in is drop-on-meta-edge only: a cell
+that owns a project keeps its context (design_1007 / optin_owners).
+
+A ``/clear`` mints a new Claude session id. The SessionStart hook with
+``source=clear`` writes that id into the role's ``<role>.session-id``
+pin, so the next spawn resumes the cleared session instead of the long
+one the pin still named.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from typing import Any, Callable, Optional
+
+from swarph_cli.cell import (
+    CellError,
+    _read_session_sidecar,
+    _write_session_sidecar,
+    session_state_path,
+    validate_uuid_str,
+)
+
+# v1. Further cells join only by their own or the commander's opt-in.
+OPT_IN = frozenset({"drop-on-meta-edge"})
+
+# Gateway statuses are open, closed, and fallback_fired. ``open`` is a
+# live row (taken or offered). ``closed`` and ``fallback_fired`` are
+# finished and do not block: drop-on-meta-edge holds a fallback_fired
+# row that would otherwise make the only opted-in cell never clear.
+# Any other status fails closed — a status this code does not know must
+# not look like an empty cell.
+_LIVE = "open"
+_FINISHED = frozenset({"closed", "fallback_fired"})
+
+_MODES = frozenset({"off", "shadow", "live"})
+
+
+def mode_from_env() -> str:
+    raw = os.environ.get("SWARPH_ROWCLEAR", "off").strip().lower()
+    return raw if raw in _MODES else "off"
+
+
+def _latch_path(state) -> "os.PathLike[str]":
+    return state.state_dir / "rowclear.json"
+
+
+def _log_path(state) -> "os.PathLike[str]":
+    return state.state_dir / "rowclear.log"
+
+
+def _read_latch(state) -> Optional[str]:
+    path = _latch_path(state)
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    mode = data.get("latched_mode") if isinstance(data, dict) else None
+    return mode if isinstance(mode, str) else None
+
+
+def _write_latch(state, mode: Optional[str]) -> None:
+    path = _latch_path(state)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps({"latched_mode": mode}) + "\n", encoding="utf-8")
+
+
+def _tmux_target(state) -> Optional[str]:
+    for sink in state.sinks:
+        if type(sink).__name__ == "TmuxSink":
+            target = getattr(sink, "target", None)
+            if target:
+                return target
+    return None
+
+
+def _dm_owed(state) -> bool:
+    observed = int(state.observed.get("last_msg_id", 0))
+    for sink in state.sinks:
+        if not getattr(sink, "keeps_ledger", False):
+            continue
+        led = state.ledger(sink.name)
+        if int(led.get("last_delivered_id", 0)) < observed:
+            return True
+        if led.get("wake_outstanding"):
+            return True
+    return False
+
+
+def _live_row_count(state, http_get: Callable) -> Optional[int]:
+    """How many unfinished rows this cell holds, or None if unread.
+
+    None fails closed: an unreadable board must not look like an empty
+    one, or a live row we failed to see gets a ``/clear``.
+    """
+    url = f"{state.gateway}/board/obligations?holder={state.self_name}"
+    try:
+        status, body = http_get(url, state.token)
+    except Exception:
+        return None
+    if status != 200 or not isinstance(body, dict):
+        return None
+    rows = body.get("obligations")
+    if not isinstance(rows, list):
+        return None
+    live = 0
+    for row in rows:
+        if not isinstance(row, dict):
+            return None
+        status = str(row.get("status") or "")
+        if status == _LIVE:
+            live += 1
+        elif status not in _FINISHED:
+            return None
+    return live
+
+
+def _append_would_clear(state, *, open_rows: int, pane_state: str) -> None:
+    path = _log_path(state)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    record = {
+        "cell": state.self_name,
+        "time": datetime.now(timezone.utc).isoformat(),
+        "open_rows": open_rows,
+        "pane_state": pane_state,
+        "action": "would-clear",
+    }
+    with path.open("a", encoding="utf-8") as fp:
+        fp.write(json.dumps(record) + "\n")
+
+
+def maybe_rowclear(
+    state,
+    *,
+    agent_running: Callable[[str], Optional[bool]],
+    http_get: Callable,
+    type_clear: Callable[[str], bool],
+) -> str:
+    """One poll. Returns the decision, so a test can name why no key went.
+
+    ``off`` and a cell not on the opt-in list return before any read or
+    write: they are unchanged. A live row, a busy pane, or an owed DM
+    unlatches the idle boundary and types nothing. Unknown rows or an
+    unknown pane type nothing and leave the latch alone.
+    """
+    mode = mode_from_env()
+    if mode == "off":
+        return "off"
+    if state.self_name not in OPT_IN:
+        return "not-opted-in"
+
+    live = _live_row_count(state, http_get)
+    if live is None:
+        return "blocked-rows-unknown"
+    if live > 0:
+        _write_latch(state, None)
+        return "blocked-live-row"
+
+    target = _tmux_target(state)
+    if target is None:
+        return "blocked-no-pane"
+    pane = agent_running(target)
+    if pane is True:
+        _write_latch(state, None)
+        return "blocked-busy"
+    if pane is None:
+        return "blocked-unknown-pane"
+    if _dm_owed(state):
+        _write_latch(state, None)
+        return "blocked-owed-dm"
+
+    if _read_latch(state) == mode:
+        return "latched"
+
+    if mode == "shadow":
+        _append_would_clear(state, open_rows=live, pane_state="idle")
+        _write_latch(state, mode)
+        print(
+            f"[rowclear] {state.self_name}: would-clear "
+            f"(open_rows={live}, pane=idle) — shadow, zero keys",
+            flush=True,
+        )
+        return "shadow"
+
+    if not type_clear(target):
+        print(
+            f"[rowclear] {state.self_name}: /clear send failed — "
+            "not latched, retried next poll",
+            flush=True,
+        )
+        return "type-failed"
+    _write_latch(state, mode)
+    print(
+        f"[rowclear] {state.self_name}: typed /clear "
+        f"(open_rows={live}, pane=idle, no DM owed)",
+        flush=True,
+    )
+    return "live"
+
+
+def apply_sessionstart_clear(payload: dict[str, Any], role: str) -> bool:
+    """Write ``session_id`` into the role pin when SessionStart source is clear.
+
+    Any other source leaves the pin alone: a resume must not clobber the
+    id the spawn will attach to. Returns True only when the pin was rewritten.
+    """
+    if not isinstance(payload, dict) or payload.get("source") != "clear":
+        return False
+    raw = payload.get("session_id") or payload.get("sessionId") or ""
+    try:
+        session_id = validate_uuid_str(str(raw))
+    except (CellError, TypeError, ValueError):
+        return False
+    path = session_state_path(role)
+    _uuid, recorded_cwd = _read_session_sidecar(path)
+    payload_cwd = payload.get("cwd") or ""
+    # ruling_1236: a clear from a different project must not rewrite
+    # another role's pin (shared HOME, card #964). Refuse only when
+    # both sides name a cwd and they differ. A missing side keeps the
+    # old fallback.
+    if recorded_cwd and str(payload_cwd).strip():
+        if os.path.normpath(recorded_cwd) != os.path.normpath(str(payload_cwd)):
+            print(
+                f"rowclear: payload cwd {payload_cwd} differs from the "
+                f"pin's recorded cwd {recorded_cwd} — pin not rewritten",
+                file=sys.stderr,
+            )
+            return False
+    cwd = payload_cwd or recorded_cwd or ""
+    _write_session_sidecar(path, session_id, cwd)
+    return True

{swarph_cli-0.72.4 → swarph_cli-0.72.5/src/swarph_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.72.4
+Version: 0.72.5
 Summary: The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, per-invocation `gh` identity routing, a silent DM-wake hook, session `import`, and a stranded-session `watchdog`.
 Author: Pierre Samson, Claude Opus
 License: MIT

{swarph_cli-0.72.4 → swarph_cli-0.72.5}/src/swarph_cli.egg-info/SOURCES.txt

@@ -26,6 +26,7 @@ src/swarph_cli/peer_service_payload.py
 src/swarph_cli/peer_service_reply.py
 src/swarph_cli/peer_staging.py
 src/swarph_cli/query_filters.py
+src/swarph_cli/rowclear.py
 src/swarph_cli/session_bridge.py
 src/swarph_cli/source_text.py
 src/swarph_cli/stall_alert.py
@@ -109,6 +110,7 @@ src/swarph_cli/commands/peer_reply_drain.py
 src/swarph_cli/commands/postcompact_hook_output.py
 src/swarph_cli/commands/protocol_handler.py
 src/swarph_cli/commands/ratify.py
+src/swarph_cli/commands/rowclear_hook.py
 src/swarph_cli/commands/schedule.py
 src/swarph_cli/commands/security.py
 src/swarph_cli/commands/service.py
@@ -209,6 +211,7 @@ tests/test_356_query_filters.py
 tests/test_397_gh_identity_router.py
 tests/test_397_router_preflight.py
 tests/test_402_one_identity_resolver.py
+tests/test_432_rowclear.py
 tests/test_467b_onboard_operator_credential.py
 tests/test_472_register_caller_binding.py
 tests/test_484_codex_queue_sink.py