threadkeeper 0.6.0__tar.gz → 0.6.2__tar.gz

{threadkeeper-0.6.0 → threadkeeper-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.6.0
+Version: 0.6.2
 Summary: Multi-agent shared brain across Claude Code/Desktop, Codex, Gemini, Copilot, VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server.
 Author: thread-keeper contributors
 License: MIT
@@ -432,6 +432,7 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_MEMORY_GUARD_RECLAIM_MB` | 1024 | local RSS floor before warn-triggered self trim |
 | `THREADKEEPER_MEMORY_GUARD_TARGET_SERVERS` | 1 | aggregate-pressure target after retiring stale idle servers |
 | `THREADKEEPER_MEMORY_GUARD_RETIRE_IDLE_S` | 900 | heartbeat age before a non-self server is retireable |
+| `THREADKEEPER_MEMORY_GUARD_RETIRE_LIVE` | "" (off) | allow retiring parent-alive MCP servers; off protects live clients |
 | `THREADKEEPER_MEMORY_GUARD_NOTIFY` | "1" | send macOS desktop notification when possible |
 | `THREADKEEPER_INGEST_INTERVAL_S` | 3 | transcript ingest tick (s) |
 | `THREADKEEPER_NO_EMBEDDINGS` | "" | force-disable sentence-transformers |

{threadkeeper-0.6.0 → threadkeeper-0.6.2}/README.md

@@ -398,6 +398,7 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_MEMORY_GUARD_RECLAIM_MB` | 1024 | local RSS floor before warn-triggered self trim |
 | `THREADKEEPER_MEMORY_GUARD_TARGET_SERVERS` | 1 | aggregate-pressure target after retiring stale idle servers |
 | `THREADKEEPER_MEMORY_GUARD_RETIRE_IDLE_S` | 900 | heartbeat age before a non-self server is retireable |
+| `THREADKEEPER_MEMORY_GUARD_RETIRE_LIVE` | "" (off) | allow retiring parent-alive MCP servers; off protects live clients |
 | `THREADKEEPER_MEMORY_GUARD_NOTIFY` | "1" | send macOS desktop notification when possible |
 | `THREADKEEPER_INGEST_INTERVAL_S` | 3 | transcript ingest tick (s) |
 | `THREADKEEPER_NO_EMBEDDINGS` | "" | force-disable sentence-transformers |

{threadkeeper-0.6.0 → threadkeeper-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "threadkeeper"
-version = "0.6.0"
+version = "0.6.2"
 description = "Multi-agent shared brain across Claude Code/Desktop, Codex, Gemini, Copilot, VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server."
 requires-python = ">=3.11"
 authors = [{ name = "thread-keeper contributors" }]

{threadkeeper-0.6.0 → threadkeeper-0.6.2}/tests/test_memory_guard.py

@@ -108,6 +108,7 @@ def test_memory_guard_status_tool_reports_thresholds(mp_with_cid, monkeypatch):
     assert "state=active" in txt
     assert "warn_mb=1000" in txt
     assert "kill_mb=2000" in txt
+    assert "coordinator=on" in txt
     assert "ok pid=1001" in txt
     assert "WARN pid=1002" in txt
     assert "KILL pid=1003" in txt
@@ -172,17 +173,51 @@ def test_check_apply_requests_peer_trim_on_aggregate_warn(mp_with_cid, monkeypat
     })
     monkeypatch.setattr(process_health, "scan", lambda: [
         _proc(os.getpid(), 900),
-        _proc(1002, 1200, ppid=os.getpid()),
+        _proc(os.getpid() + 1002, 1200, ppid=os.getpid()),
     ])
 
     out = memory_guard.check_once(dry_run=False, notify=False)
-    assert sorted(out["reclaim_requests"]["requested"]) == sorted([os.getpid(), 1002])
+    peer_pid = os.getpid() + 1002
+    assert sorted(out["reclaim_requests"]["requested"]) == sorted(
+        [os.getpid(), peer_pid]
+    )
 
     conn = pkg["db"].get_db()
     rows = conn.execute(
         "SELECT target_pid FROM resource_controls WHERE action='trim'"
     ).fetchall()
-    assert sorted(r["target_pid"] for r in rows) == sorted([os.getpid(), 1002])
+    assert sorted(r["target_pid"] for r in rows) == sorted([os.getpid(), peer_pid])
+
+
+def test_aggregate_side_effects_only_run_on_coordinator(mp_with_cid, monkeypatch):
+    mp_with_cid(_FAKE_CID)
+    from threadkeeper import memory_guard, process_health
+
+    self_pid = os.getpid()
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_WARN_MB", 5000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_KILL_MB", 6000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_WARN_MB", 2000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_KILL_MB", 0)
+    monkeypatch.setattr(process_health, "scan", lambda: [
+        _proc(self_pid - 1, 1200),
+        _proc(self_pid, 1200),
+    ])
+    reclaim_calls: list[str] = []
+    monkeypatch.setattr(
+        memory_guard,
+        "reclaim_memory",
+        lambda reason="": reclaim_calls.append(reason) or {
+            "before_mb": 1200, "after_mb": 1100, "freed_mb": 100,
+            "pid": self_pid, "actions": [],
+        },
+    )
+
+    out = memory_guard.check_once(dry_run=False, notify=False)
+    assert out["aggregate"]["warn"] is True
+    assert out["coordinator"] is False
+    assert out["reclaim_requests"]["count"] == 0
+    assert out["local_reclaim"] is None
+    assert reclaim_calls == []
 
 
 def test_check_apply_retires_idle_candidate_on_aggregate_pressure(mp_with_cid, monkeypatch):
@@ -195,6 +230,7 @@ def test_check_apply_retires_idle_candidate_on_aggregate_pressure(mp_with_cid, m
     monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_KILL_MB", 3000)
     monkeypatch.setattr(memory_guard, "MEMORY_GUARD_TARGET_SERVERS", 1)
     monkeypatch.setattr(memory_guard, "MEMORY_GUARD_RETIRE_IDLE_S", 900)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_RETIRE_LIVE", False)
     monkeypatch.setattr(memory_guard, "reclaim_memory", lambda reason="": {
         "before_mb": 900, "after_mb": 800, "freed_mb": 100,
         "pid": os.getpid(), "actions": ["fake"],
@@ -203,8 +239,13 @@ def test_check_apply_retires_idle_candidate_on_aggregate_pressure(mp_with_cid, m
     def scan():
         return [
             _proc(os.getpid(), 900),
-            _proc(1001, 1200, ppid=os.getpid()) | {"heartbeat_age_s": None},
-            _proc(1002, 800, ppid=os.getpid()) | {"heartbeat_age_s": 5},
+            _proc(os.getpid() + 1001, 1200, ppid=1) | {
+                "heartbeat_age_s": None,
+                "parent_alive": False,
+                "is_orphaned": True,
+                "orphan_reason": "parent_gone + no_heartbeat",
+            },
+            _proc(os.getpid() + 1002, 800, ppid=os.getpid()) | {"heartbeat_age_s": 5},
         ]
 
     monkeypatch.setattr(process_health, "scan", scan)
@@ -215,5 +256,36 @@ def test_check_apply_retires_idle_candidate_on_aggregate_pressure(mp_with_cid, m
     )
 
     out = memory_guard.check_once(dry_run=False, notify=False)
-    assert out["retired"] == [1001]
-    assert calls == [(1001, _sig.SIGTERM)]
+    stale_pid = os.getpid() + 1001
+    assert out["retired"] == [stale_pid]
+    assert calls == [(stale_pid, _sig.SIGTERM)]
+
+
+def test_aggregate_retire_skips_live_parent_without_opt_in(mp_with_cid, monkeypatch):
+    mp_with_cid(_FAKE_CID)
+    from threadkeeper import memory_guard, process_health
+
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_WARN_MB", 5000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_KILL_MB", 6000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_WARN_MB", 2000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_KILL_MB", 3000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_TARGET_SERVERS", 1)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_RETIRE_IDLE_S", 900)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_RETIRE_LIVE", False)
+    monkeypatch.setattr(memory_guard, "reclaim_memory", lambda reason="": {
+        "before_mb": 900, "after_mb": 800, "freed_mb": 100,
+        "pid": os.getpid(), "actions": ["fake"],
+    })
+    monkeypatch.setattr(process_health, "scan", lambda: [
+        _proc(os.getpid(), 900),
+        _proc(os.getpid() + 1001, 1200, ppid=os.getpid()) | {"heartbeat_age_s": None},
+    ])
+    calls: list[tuple[int, int]] = []
+    monkeypatch.setattr(
+        "os.kill",
+        lambda pid, sig: calls.append((pid, sig)) if sig != 0 else None,
+    )
+
+    out = memory_guard.check_once(dry_run=False, notify=False)
+    assert out["retired"] == []
+    assert calls == []

{threadkeeper-0.6.0 → threadkeeper-0.6.2}/threadkeeper/config.py

@@ -183,6 +183,9 @@ MEMORY_GUARD_TARGET_SERVERS: int = int(
 MEMORY_GUARD_RETIRE_IDLE_S: int = int(
     os.environ.get("THREADKEEPER_MEMORY_GUARD_RETIRE_IDLE_S", "900")
 )
+MEMORY_GUARD_RETIRE_LIVE: bool = os.environ.get(
+    "THREADKEEPER_MEMORY_GUARD_RETIRE_LIVE", ""
+).lower() in {"1", "true", "yes", "on"}
 MEMORY_GUARD_NOTIFY: bool = os.environ.get(
     "THREADKEEPER_MEMORY_GUARD_NOTIFY", "1"
 ).lower() in {"1", "true", "yes", "on"}

{threadkeeper-0.6.0 → threadkeeper-0.6.2}/threadkeeper/memory_guard.py

@@ -28,6 +28,7 @@ from .config import (
     MEMORY_GUARD_POLL_S,
     MEMORY_GUARD_RECLAIM_MB,
     MEMORY_GUARD_RETIRE_IDLE_S,
+    MEMORY_GUARD_RETIRE_LIVE,
     MEMORY_GUARD_TARGET_SERVERS,
     MEMORY_GUARD_WARN_MB,
     TASK_LOG_DIR,
@@ -72,13 +73,19 @@ def _log_line(line: str) -> None:
         logger.debug("memory_guard: failed to append log", exc_info=True)
 
 
-def _emit_event(kind: str, pid: int, summary: str) -> None:
+def _emit_event(kind: str, target: int | str, summary: str) -> None:
     try:
         conn = get_db()
         conn.execute(
             "INSERT INTO events (session_id, kind, target, summary, created_at) "
             "VALUES (?,?,?,?,?)",
-            (identity._session_id or "", kind, str(pid), summary[:200], int(time.time())),
+            (
+                identity._session_id or "",
+                kind,
+                str(target),
+                summary[:200],
+                int(time.time()),
+            ),
         )
         conn.commit()
     except Exception:
@@ -227,6 +234,18 @@ def _pending_recent_control(conn, action: str, pid: int, now: int) -> bool:
     return row is not None
 
 
+def _recent_event(conn, kind: str, target: str, now: int) -> bool:
+    if MEMORY_GUARD_COOLDOWN_S <= 0:
+        return False
+    row = conn.execute(
+        "SELECT 1 FROM events "
+        "WHERE kind=? AND target=? AND created_at>=? "
+        "ORDER BY id DESC LIMIT 1",
+        (kind, target, now - max(1, MEMORY_GUARD_COOLDOWN_S)),
+    ).fetchone()
+    return row is not None
+
+
 def request_reclaim(procs: list[dict] | None = None, reason: str = "manual") -> dict:
     """Queue trim requests for the given process rows, deduped by cooldown."""
     if procs is None:
@@ -288,14 +307,44 @@ def _aggregate_state(procs: list[dict]) -> dict:
         "kill_mb": MEMORY_GUARD_AGG_KILL_MB,
         "target_servers": MEMORY_GUARD_TARGET_SERVERS,
         "retire_idle_s": MEMORY_GUARD_RETIRE_IDLE_S,
+        "retire_live": MEMORY_GUARD_RETIRE_LIVE,
     }
 
 
+def _global_guard_coordinator_pid(procs: list[dict]) -> int | None:
+    candidates = [
+        int(p["pid"])
+        for p in procs
+        if int(p.get("pid") or 0) > 0 and not p.get("is_orphaned")
+    ]
+    if not candidates:
+        candidates = [int(p["pid"]) for p in procs if int(p.get("pid") or 0) > 0]
+    return min(candidates) if candidates else None
+
+
+def is_global_guard_coordinator(procs: list[dict]) -> bool:
+    """True when this server owns process-wide aggregate side effects.
+
+    Every MCP server runs its own local daemon. Without coordination, N open
+    conversations produce N aggregate warnings, N trim sweeps, and racing retire
+    attempts. The oldest non-orphaned server is the single coordinator; if the
+    scanner somehow misses this process, treat the current manual caller as the
+    coordinator so diagnostics/tests still apply side effects.
+    """
+    self_pid = os.getpid()
+    pids = {int(p["pid"]) for p in procs if int(p.get("pid") or 0) > 0}
+    if self_pid not in pids:
+        return True
+    return self_pid == _global_guard_coordinator_pid(procs)
+
+
 def _idle_retire_candidates(procs: list[dict]) -> list[dict]:
     candidates: list[dict] = []
     for p in procs:
         if p.get("is_self"):
             continue
+        if p.get("parent_alive") and not MEMORY_GUARD_RETIRE_LIVE:
+            continue
         hb = p.get("heartbeat_age_s")
         if hb is None or hb >= MEMORY_GUARD_RETIRE_IDLE_S:
             candidates.append(dict(p, rss_mb=_rss_mb(p)))
@@ -347,12 +396,15 @@ def scan_over_limit() -> dict:
             warn.append(p)
     aggregate = _aggregate_state(procs)
     retire = _retire_plan(procs, aggregate)
+    coordinator = is_global_guard_coordinator(procs)
     return {
         "procs": procs,
         "warn": warn,
         "kill": kill,
         "aggregate": aggregate,
         "retire": retire,
+        "coordinator": coordinator,
+        "coordinator_pid": _global_guard_coordinator_pid(procs),
         "warn_mb": MEMORY_GUARD_WARN_MB,
         "kill_mb": MEMORY_GUARD_KILL_MB,
         "reclaim_mb": MEMORY_GUARD_RECLAIM_MB,
@@ -373,6 +425,7 @@ def check_once(*, dry_run: bool = True, notify: bool = True) -> dict:
         handled_controls = handle_resource_controls()
 
     result = scan_over_limit()
+    is_coordinator = bool(result.get("coordinator"))
     killed: list[int] = []
     failed: list[dict] = []
     retired: list[int] = []
@@ -380,6 +433,8 @@ def check_once(*, dry_run: bool = True, notify: bool = True) -> dict:
     local_reclaim: dict | None = None
 
     for p in result["warn"]:
+        if p["pid"] != os.getpid():
+            continue
         msg = (
             f"pid {p['pid']} RSS {p['rss_mb']}MB crossed warn "
             f"threshold {MEMORY_GUARD_WARN_MB}MB"
@@ -392,21 +447,24 @@ def check_once(*, dry_run: bool = True, notify: bool = True) -> dict:
             _maybe_notify(p["pid"], "warn", msg)
 
     aggregate = result["aggregate"]
-    if aggregate["warn"]:
+    if aggregate["warn"] and is_coordinator:
         msg = (
             f"aggregate RSS {aggregate['rss_mb']}MB crossed warn "
             f"threshold {aggregate['warn_mb']}MB across "
             f"{len(result['procs'])} server process(es)"
         )
         if not dry_run:
-            _emit_event("memory_guard_aggregate_warn", os.getpid(), msg)
-            reclaim_requests = request_reclaim(
-                result["procs"], reason="aggregate_warn"
-            )
-            if any(p["pid"] == os.getpid() for p in result["procs"]):
-                local_reclaim = reclaim_memory(reason="aggregate_warn")
-        if notify and not dry_run:
-            _maybe_notify(os.getpid(), "aggregate_warn", msg)
+            conn = get_db()
+            now = int(time.time())
+            if not _recent_event(conn, "memory_guard_aggregate_warn", "aggregate", now):
+                _emit_event("memory_guard_aggregate_warn", "aggregate", msg)
+                reclaim_requests = request_reclaim(
+                    result["procs"], reason="aggregate_warn"
+                )
+                if any(p["pid"] == os.getpid() for p in result["procs"]):
+                    local_reclaim = reclaim_memory(reason="aggregate_warn")
+                if notify:
+                    _maybe_notify(os.getpid(), "aggregate_warn", msg)
 
     kill_rows = sorted(
         result["kill"], key=lambda p: p["pid"] == os.getpid()
@@ -418,6 +476,8 @@ def check_once(*, dry_run: bool = True, notify: bool = True) -> dict:
         )
         if dry_run:
             continue
+        if p["pid"] != os.getpid() and not is_coordinator:
+            continue
         _emit_event("memory_guard_kill", p["pid"], msg)
         if notify:
             _maybe_notify(p["pid"], "kill", msg, force=True)
@@ -427,7 +487,7 @@ def check_once(*, dry_run: bool = True, notify: bool = True) -> dict:
         except (ProcessLookupError, PermissionError, OSError) as e:
             failed.append({"pid": p["pid"], "err": str(e)})
 
-    if aggregate["warn"] and result["retire"]:
+    if aggregate["warn"] and is_coordinator and result["retire"]:
         for p in result["retire"]:
             msg = (
                 f"aggregate RSS {aggregate['rss_mb']}MB; retiring idle "

{threadkeeper-0.6.0 → threadkeeper-0.6.2}/threadkeeper/tools/memory_guard.py

@@ -32,6 +32,9 @@ def memory_guard_status() -> str:
         f"warn_mb={result['warn_mb']} kill_mb={result['kill_mb']} "
         f"agg_warn_mb={agg['warn_mb']} agg_kill_mb={agg['kill_mb']} "
         f"target_servers={agg['target_servers']} "
+        f"retire_live={'on' if agg['retire_live'] else 'off'} "
+        f"coordinator={'on' if result['coordinator'] else 'off'} "
+        f"coordinator_pid={result['coordinator_pid'] or '-'} "
         f"notify={'on' if result['notify'] else 'off'}",
         f"processes={len(procs)} rss_total={total_mb}MB aggregate={agg_marker}",
     ]

{threadkeeper-0.6.0 → threadkeeper-0.6.2}/threadkeeper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.6.0
+Version: 0.6.2
 Summary: Multi-agent shared brain across Claude Code/Desktop, Codex, Gemini, Copilot, VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server.
 Author: thread-keeper contributors
 License: MIT
@@ -432,6 +432,7 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_MEMORY_GUARD_RECLAIM_MB` | 1024 | local RSS floor before warn-triggered self trim |
 | `THREADKEEPER_MEMORY_GUARD_TARGET_SERVERS` | 1 | aggregate-pressure target after retiring stale idle servers |
 | `THREADKEEPER_MEMORY_GUARD_RETIRE_IDLE_S` | 900 | heartbeat age before a non-self server is retireable |
+| `THREADKEEPER_MEMORY_GUARD_RETIRE_LIVE` | "" (off) | allow retiring parent-alive MCP servers; off protects live clients |
 | `THREADKEEPER_MEMORY_GUARD_NOTIFY` | "1" | send macOS desktop notification when possible |
 | `THREADKEEPER_INGEST_INTERVAL_S` | 3 | transcript ingest tick (s) |
 | `THREADKEEPER_NO_EMBEDDINGS` | "" | force-disable sentence-transformers |