threadkeeper 0.5.2__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.5.2
+Version: 0.6.0
 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
@@ -82,10 +82,10 @@ make it more than a memory store:
   harvester, candidate-reviewer, weekly Curator) materialize
   class-level skills as the agents work. Adapted to multi-CLI:
   SKILL.md is the primary write target and gets mirrored to every
-  detected CLI's skills directory simultaneously
-  (`~/.claude/skills/`, `~/.codex/skills/`, `~/.threadkeeper/skills/`),
-  with lessons.md as a fallback for CLIs without a native skills
-  loader.
+  known/configured skills root simultaneously (`~/.claude/skills/`,
+  `~/.codex/skills/`, existing `~/.agents/skills/`, extra roots from
+  `THREADKEEPER_EXTRA_SKILLS_DIRS`, and `~/.threadkeeper/skills/`),
+  with lessons.md as a fallback for CLIs without a native skills loader.
 
 ---
 
@@ -183,6 +183,8 @@ Claude session via a `claude -p` subprocess. By default `slim=True`: the
 child loads only the thread-keeper MCP, no embeddings, no third-party
 servers. ~500 MB RSS versus ~1.3 GB for a full child. Heuristic for the
 parent: N≥2 modular independent units of ≥5 min each = spawn signal.
+Spawn also marks children with `THREADKEEPER_SPAWNED_CHILD=1`, so
+autonomous learning daemons cannot recursively start inside review forks.
 
 A daemon measures combined child RSS every 10 s; admission control
 refuses a new spawn that would exceed `THREADKEEPER_SPAWN_BUDGET_MB`
@@ -223,8 +225,8 @@ shows agents focused on their primary task rarely do).
          brief()    SKILL.md + lessons.md ─► skill_usage   │
             │              │                  │            │
             │              ▼                  ▼            │
-            │         (every detected CLI's   │            │
-            │          skills/ directory)     │            │
+            │         (every configured       │            │
+            │          skills/ root)          │            │
             │              │                  │            │
             │              └──────► [5] Curator daemon ───┘
             │                          (cron, every 7d)
@@ -246,11 +248,11 @@ shows agents focused on their primary task rarely do).
 | 5 | Curator daemon | every 7 days (env knob) | every existing lesson + recently-touched skill | REPORT-`<date>`.md (advisory) or direct PATCH/PRUNE/CONSOLIDATE |
 
 All five write into the universal Skill format (`SKILL.md` under each
-detected CLI's skills directory — `~/.claude/skills/`,
-`~/.codex/skills/`, plus the canonical `~/.threadkeeper/skills/`
-mirror), with `~/.threadkeeper/lessons.md` as a CLI-agnostic fallback
-for clients without a native skills loader (Gemini, Copilot, bare
-MCP).
+known/configured skills root — `~/.claude/skills/`, `~/.codex/skills/`,
+existing `~/.agents/skills/`, optional `THREADKEEPER_EXTRA_SKILLS_DIRS`,
+plus the canonical `~/.threadkeeper/skills/` mirror), with
+`~/.threadkeeper/lessons.md` as a CLI-agnostic fallback for clients
+without a native skills loader (Gemini, Copilot, bare MCP).
 
 #### 1. Auto-review on close_thread
 
@@ -260,9 +262,12 @@ thread's notes. The prompt is rubric-form (Q1–Q5 yes/no) with explicit
 positive examples for incident-vs-rule classification. The fork also
 receives a "recently active skills" block so it prefers PATCHing
 existing umbrellas over creating new ones (*active-update bias*).
-Child appends a lesson via `lesson_append`, optionally mirrors to
-`~/.claude/skills/<name>/SKILL.md`, then closes with
-`mark_skill_materialized`. Opt in with `THREADKEEPER_AUTO_REVIEW=1`.
+Child appends a lesson via `lesson_append`, writes/patches a skill via
+`skill_manage` or writes a skill file directly, then closes with
+`mark_skill_materialized`. If `skill_path` points at a `SKILL.md` (or a
+skill directory), thread-keeper immediately mirrors that whole skill
+into every configured skills root. Opt in with
+`THREADKEEPER_AUTO_REVIEW=1`.
 
 #### 2. Shadow-review daemon
 
@@ -272,7 +277,11 @@ the last cursor **across all CLIs at once**. The window filters
 internal review-child sessions (no self-pollution) and strips adapter
 `[tool_result]` / `[tool_call]` noise (the "clean context" rule). If
 ≥500 chars of meaningful signal remain, spawns a slim observer child
-that decides on class-level learning. Idempotent through
+that decides on class-level learning. It is single-flight across the shared
+DB: if any shadow observer task is already running, the daemon does not spawn
+another one and does not advance the cursor. Shadow observer children are
+marked as spawned/background processes, so they cannot start their own shadow
+daemon even if a CLI drops the no-embeddings env. Idempotent through
 `events.kind='shadow_review_pass'`.
 
 #### 3. Extract daemon
@@ -415,8 +424,18 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_CURATOR_MIN_LESSONS` | 3 | min lessons before curator engages |
 | `THREADKEEPER_CURATOR_DESTRUCTIVE` | "" (advisory) | when "1": curator child applies its own PATCH/PRUNE/CONSOLIDATE directly instead of writing advisory REPORT only |
 | `THREADKEEPER_SPAWN_BUDGET_MB` | 3072 | combined child RSS cap (MB); 0 disables |
+| `THREADKEEPER_MEMORY_GUARD_POLL_S` | 30 | server RSS guard tick (s); 0 disables |
+| `THREADKEEPER_MEMORY_GUARD_WARN_MB` | 1536 | notify/log when a server crosses this RSS |
+| `THREADKEEPER_MEMORY_GUARD_KILL_MB` | 3072 | SIGTERM server above this RSS; 0 disables killing |
+| `THREADKEEPER_MEMORY_GUARD_AGG_WARN_MB` | 2048 | notify/request trim when all server RSS crosses this |
+| `THREADKEEPER_MEMORY_GUARD_AGG_KILL_MB` | 3072 | under aggregate pressure, retire stale idle servers |
+| `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_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_SPAWNED_CHILD` | "" | spawn-internal marker; disables autonomous daemons in children |
 | `THREADKEEPER_SKILL_NUDGE_INTERVAL` | 10 | events between `skill_hint` nudges |
 
 Persist them via `~/.claude/settings.json`'s `env` block (Claude Code) or

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

@@ -48,10 +48,10 @@ make it more than a memory store:
   harvester, candidate-reviewer, weekly Curator) materialize
   class-level skills as the agents work. Adapted to multi-CLI:
   SKILL.md is the primary write target and gets mirrored to every
-  detected CLI's skills directory simultaneously
-  (`~/.claude/skills/`, `~/.codex/skills/`, `~/.threadkeeper/skills/`),
-  with lessons.md as a fallback for CLIs without a native skills
-  loader.
+  known/configured skills root simultaneously (`~/.claude/skills/`,
+  `~/.codex/skills/`, existing `~/.agents/skills/`, extra roots from
+  `THREADKEEPER_EXTRA_SKILLS_DIRS`, and `~/.threadkeeper/skills/`),
+  with lessons.md as a fallback for CLIs without a native skills loader.
 
 ---
 
@@ -149,6 +149,8 @@ Claude session via a `claude -p` subprocess. By default `slim=True`: the
 child loads only the thread-keeper MCP, no embeddings, no third-party
 servers. ~500 MB RSS versus ~1.3 GB for a full child. Heuristic for the
 parent: N≥2 modular independent units of ≥5 min each = spawn signal.
+Spawn also marks children with `THREADKEEPER_SPAWNED_CHILD=1`, so
+autonomous learning daemons cannot recursively start inside review forks.
 
 A daemon measures combined child RSS every 10 s; admission control
 refuses a new spawn that would exceed `THREADKEEPER_SPAWN_BUDGET_MB`
@@ -189,8 +191,8 @@ shows agents focused on their primary task rarely do).
          brief()    SKILL.md + lessons.md ─► skill_usage   │
             │              │                  │            │
             │              ▼                  ▼            │
-            │         (every detected CLI's   │            │
-            │          skills/ directory)     │            │
+            │         (every configured       │            │
+            │          skills/ root)          │            │
             │              │                  │            │
             │              └──────► [5] Curator daemon ───┘
             │                          (cron, every 7d)
@@ -212,11 +214,11 @@ shows agents focused on their primary task rarely do).
 | 5 | Curator daemon | every 7 days (env knob) | every existing lesson + recently-touched skill | REPORT-`<date>`.md (advisory) or direct PATCH/PRUNE/CONSOLIDATE |
 
 All five write into the universal Skill format (`SKILL.md` under each
-detected CLI's skills directory — `~/.claude/skills/`,
-`~/.codex/skills/`, plus the canonical `~/.threadkeeper/skills/`
-mirror), with `~/.threadkeeper/lessons.md` as a CLI-agnostic fallback
-for clients without a native skills loader (Gemini, Copilot, bare
-MCP).
+known/configured skills root — `~/.claude/skills/`, `~/.codex/skills/`,
+existing `~/.agents/skills/`, optional `THREADKEEPER_EXTRA_SKILLS_DIRS`,
+plus the canonical `~/.threadkeeper/skills/` mirror), with
+`~/.threadkeeper/lessons.md` as a CLI-agnostic fallback for clients
+without a native skills loader (Gemini, Copilot, bare MCP).
 
 #### 1. Auto-review on close_thread
 
@@ -226,9 +228,12 @@ thread's notes. The prompt is rubric-form (Q1–Q5 yes/no) with explicit
 positive examples for incident-vs-rule classification. The fork also
 receives a "recently active skills" block so it prefers PATCHing
 existing umbrellas over creating new ones (*active-update bias*).
-Child appends a lesson via `lesson_append`, optionally mirrors to
-`~/.claude/skills/<name>/SKILL.md`, then closes with
-`mark_skill_materialized`. Opt in with `THREADKEEPER_AUTO_REVIEW=1`.
+Child appends a lesson via `lesson_append`, writes/patches a skill via
+`skill_manage` or writes a skill file directly, then closes with
+`mark_skill_materialized`. If `skill_path` points at a `SKILL.md` (or a
+skill directory), thread-keeper immediately mirrors that whole skill
+into every configured skills root. Opt in with
+`THREADKEEPER_AUTO_REVIEW=1`.
 
 #### 2. Shadow-review daemon
 
@@ -238,7 +243,11 @@ the last cursor **across all CLIs at once**. The window filters
 internal review-child sessions (no self-pollution) and strips adapter
 `[tool_result]` / `[tool_call]` noise (the "clean context" rule). If
 ≥500 chars of meaningful signal remain, spawns a slim observer child
-that decides on class-level learning. Idempotent through
+that decides on class-level learning. It is single-flight across the shared
+DB: if any shadow observer task is already running, the daemon does not spawn
+another one and does not advance the cursor. Shadow observer children are
+marked as spawned/background processes, so they cannot start their own shadow
+daemon even if a CLI drops the no-embeddings env. Idempotent through
 `events.kind='shadow_review_pass'`.
 
 #### 3. Extract daemon
@@ -381,8 +390,18 @@ The most-used env knobs (full list in `threadkeeper/config.py`):
 | `THREADKEEPER_CURATOR_MIN_LESSONS` | 3 | min lessons before curator engages |
 | `THREADKEEPER_CURATOR_DESTRUCTIVE` | "" (advisory) | when "1": curator child applies its own PATCH/PRUNE/CONSOLIDATE directly instead of writing advisory REPORT only |
 | `THREADKEEPER_SPAWN_BUDGET_MB` | 3072 | combined child RSS cap (MB); 0 disables |
+| `THREADKEEPER_MEMORY_GUARD_POLL_S` | 30 | server RSS guard tick (s); 0 disables |
+| `THREADKEEPER_MEMORY_GUARD_WARN_MB` | 1536 | notify/log when a server crosses this RSS |
+| `THREADKEEPER_MEMORY_GUARD_KILL_MB` | 3072 | SIGTERM server above this RSS; 0 disables killing |
+| `THREADKEEPER_MEMORY_GUARD_AGG_WARN_MB` | 2048 | notify/request trim when all server RSS crosses this |
+| `THREADKEEPER_MEMORY_GUARD_AGG_KILL_MB` | 3072 | under aggregate pressure, retire stale idle servers |
+| `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_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_SPAWNED_CHILD` | "" | spawn-internal marker; disables autonomous daemons in children |
 | `THREADKEEPER_SKILL_NUDGE_INTERVAL` | 10 | events between `skill_hint` nudges |
 
 Persist them via `~/.claude/settings.json`'s `env` block (Claude Code) or

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "threadkeeper"
-version = "0.5.2"
+version = "0.6.0"
 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/tests/test_memory_guard.py

@@ -0,0 +1,219 @@
+"""Memory guard for thread-keeper server RSS thresholds."""
+from __future__ import annotations
+
+import os
+import signal as _sig
+
+
+_FAKE_CID = "55556666-7777-8888-9999-000011112222"
+
+
+def _tool(pkg, name):
+    return pkg["mcp"]._tool_manager._tools[name].fn
+
+
+def _proc(pid, rss_mb, *, ppid=None):
+    return {
+        "pid": pid,
+        "ppid": os.getpid() if ppid is None else ppid,
+        "rss_kb": rss_mb * 1024,
+        "rss_mb": rss_mb,
+        "etime": "1:00",
+        "command": "python -m threadkeeper.server",
+        "parent_alive": True,
+        "heartbeat_age_s": 5,
+        "is_self": pid == os.getpid(),
+        "is_orphaned": False,
+        "orphan_reason": "parent_alive",
+    }
+
+
+def test_scan_over_limit_splits_warn_and_kill(mp_with_cid, monkeypatch):
+    mp_with_cid(_FAKE_CID)
+    from threadkeeper import memory_guard, process_health
+
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_WARN_MB", 1000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_KILL_MB", 2000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_WARN_MB", 0)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_KILL_MB", 0)
+    monkeypatch.setattr(process_health, "scan", lambda: [
+        _proc(1001, 800),
+        _proc(1002, 1200),
+        _proc(1003, 2500),
+    ])
+
+    out = memory_guard.scan_over_limit()
+    assert [p["pid"] for p in out["warn"]] == [1002]
+    assert [p["pid"] for p in out["kill"]] == [1003]
+
+
+def test_check_dry_run_does_not_kill(mp_with_cid, monkeypatch):
+    mp_with_cid(_FAKE_CID)
+    from threadkeeper import memory_guard, process_health
+
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_WARN_MB", 1000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_KILL_MB", 2000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_WARN_MB", 0)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_KILL_MB", 0)
+    monkeypatch.setattr(process_health, "scan", lambda: [_proc(1003, 2500)])
+    killed: list[tuple[int, int]] = []
+    monkeypatch.setattr(
+        "os.kill",
+        lambda pid, sig: killed.append((pid, sig)) if sig != 0 else None,
+    )
+
+    out = memory_guard.check_once(dry_run=True, notify=False)
+    assert [p["pid"] for p in out["kill"]] == [1003]
+    assert out["killed"] == []
+    assert killed == []
+
+
+def test_check_apply_sends_sigterm(mp_with_cid, monkeypatch):
+    mp_with_cid(_FAKE_CID)
+    from threadkeeper import memory_guard, process_health
+
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_WARN_MB", 1000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_KILL_MB", 2000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_WARN_MB", 0)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_KILL_MB", 0)
+    monkeypatch.setattr(process_health, "scan", lambda: [_proc(1004, 2500)])
+    calls: list[tuple[int, int]] = []
+    monkeypatch.setattr("os.kill", lambda pid, sig: calls.append((pid, sig)))
+    monkeypatch.setattr(memory_guard, "reclaim_memory", lambda reason="": {
+        "before_mb": 2500, "after_mb": 2400, "freed_mb": 100,
+        "pid": os.getpid(), "actions": [],
+    })
+
+    out = memory_guard.check_once(dry_run=False, notify=False)
+    assert out["killed"] == [1004]
+    assert calls == [(1004, _sig.SIGTERM)]
+
+
+def test_memory_guard_status_tool_reports_thresholds(mp_with_cid, monkeypatch):
+    pkg = mp_with_cid(_FAKE_CID)
+    from threadkeeper import memory_guard, process_health
+
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_POLL_S", 30)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_WARN_MB", 1000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_KILL_MB", 2000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_WARN_MB", 0)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_KILL_MB", 0)
+    monkeypatch.setattr(process_health, "scan", lambda: [
+        _proc(1001, 800),
+        _proc(1002, 1200),
+        _proc(1003, 2500),
+    ])
+
+    txt = _tool(pkg, "memory_guard_status")()
+    assert "state=active" in txt
+    assert "warn_mb=1000" in txt
+    assert "kill_mb=2000" in txt
+    assert "ok pid=1001" in txt
+    assert "WARN pid=1002" in txt
+    assert "KILL pid=1003" in txt
+
+
+def test_memory_guard_check_tool_defaults_to_dry_run(mp_with_cid, monkeypatch):
+    pkg = mp_with_cid(_FAKE_CID)
+    from threadkeeper import memory_guard, process_health
+
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_WARN_MB", 1000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_KILL_MB", 2000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_WARN_MB", 0)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_KILL_MB", 0)
+    monkeypatch.setattr(process_health, "scan", lambda: [_proc(1005, 2500)])
+    killed: list[tuple[int, int]] = []
+    monkeypatch.setattr(
+        "os.kill",
+        lambda pid, sig: killed.append((pid, sig)) if sig != 0 else None,
+    )
+
+    txt = _tool(pkg, "memory_guard_check")()
+    assert txt.startswith("dry_run")
+    assert "would SIGTERM pid=1005" in txt
+    assert killed == []
+
+
+def test_scan_reports_aggregate_pressure(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(process_health, "scan", lambda: [
+        _proc(1001, 800),
+        _proc(1002, 900),
+        _proc(1003, 1200),
+    ])
+
+    out = memory_guard.scan_over_limit()
+    assert out["aggregate"]["rss_mb"] == 2900
+    assert out["aggregate"]["warn"] is True
+    assert out["aggregate"]["kill"] is False
+    assert out["warn"] == []
+    assert out["kill"] == []
+
+
+def test_check_apply_requests_peer_trim_on_aggregate_warn(mp_with_cid, monkeypatch):
+    pkg = 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", 0)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_TARGET_SERVERS", 1)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_RETIRE_IDLE_S", 900)
+    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(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])
+
+    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])
+
+
+def test_check_apply_retires_idle_candidate_on_aggregate_pressure(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, "reclaim_memory", lambda reason="": {
+        "before_mb": 900, "after_mb": 800, "freed_mb": 100,
+        "pid": os.getpid(), "actions": ["fake"],
+    })
+
+    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},
+        ]
+
+    monkeypatch.setattr(process_health, "scan", scan)
+    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"] == [1001]
+    assert calls == [(1001, _sig.SIGTERM)]

{threadkeeper-0.5.2 → threadkeeper-0.6.0}/tests/test_nudges.py

@@ -438,3 +438,69 @@ def test_close_thread_with_auto_review_enabled_spawns(tmp_path, monkeypatch):
     assert len(calls) == 1
     assert calls[0]["thread_id"] == tid
     assert calls[0]["mode"] == "auto"
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# compute_thread_nudge  (open-thread nudge for hook-less clients)
+# ──────────────────────────────────────────────────────────────────────────
+
+def _insert_event(pkg, session_id: str, kind: str) -> None:
+    conn = pkg["db"].get_db()
+    conn.execute(
+        "INSERT INTO events (session_id, kind, target, summary, created_at) "
+        "VALUES (?,?,?,?,?)",
+        (session_id, kind, None, "", int(time.time())),
+    )
+    conn.commit()
+
+
+def test_thread_nudge_fires_on_empty_session(tmp_path, monkeypatch):
+    """No activity threshold — fires as soon as a session exists with no
+    open_thread (mirrors the hook firing on the first prompt)."""
+    pkg = _bootstrap_with_env(tmp_path, monkeypatch)
+    conn = pkg["db"].get_db()
+    out = pkg["nudges"].compute_thread_nudge(conn, "sess-empty")
+    assert out is not None
+    assert "thread_hint" in out
+    assert "open_thread(question)" in out
+
+
+def test_thread_nudge_silent_after_open_thread(tmp_path, monkeypatch):
+    pkg = _bootstrap_with_env(tmp_path, monkeypatch)
+    _insert_event(pkg, "sess-B", "open_thread")
+    conn = pkg["db"].get_db()
+    assert pkg["nudges"].compute_thread_nudge(conn, "sess-B") is None
+
+
+def test_thread_nudge_silent_after_shown(tmp_path, monkeypatch):
+    pkg = _bootstrap_with_env(tmp_path, monkeypatch)
+    _insert_event(pkg, "sess-C", "thread_hint_shown")
+    conn = pkg["db"].get_db()
+    assert pkg["nudges"].compute_thread_nudge(conn, "sess-C") is None
+
+
+def test_thread_nudge_silent_without_session_id(tmp_path, monkeypatch):
+    pkg = _bootstrap_with_env(tmp_path, monkeypatch)
+    conn = pkg["db"].get_db()
+    assert pkg["nudges"].compute_thread_nudge(conn, "") is None
+
+
+def test_brief_shows_thread_hint_once_then_suppresses(tmp_path, monkeypatch):
+    """brief() surfaces the nudge on the first call (no env set = hook-less
+    client), logs thread_hint_shown, and stays quiet thereafter."""
+    pkg = _bootstrap_with_env(tmp_path, monkeypatch)
+    monkeypatch.delenv("THREADKEEPER_BRIEF_NO_THREAD_NUDGE", raising=False)
+    brief = _tool(pkg, "brief")
+    out1 = brief()
+    assert "thread_hint" in out1
+    out2 = brief()
+    assert "thread_hint" not in out2
+
+
+def test_brief_suppresses_thread_hint_when_env_set(tmp_path, monkeypatch):
+    """SessionStart-hook path (env set) never surfaces the in-brief nudge —
+    the UserPromptSubmit hook owns it there."""
+    pkg = _bootstrap_with_env(tmp_path, monkeypatch)
+    monkeypatch.setenv("THREADKEEPER_BRIEF_NO_THREAD_NUDGE", "1")
+    out = _tool(pkg, "brief")()
+    assert "thread_hint" not in out

{threadkeeper-0.5.2 → threadkeeper-0.6.0}/tests/test_shadow_review.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import time
 import sys
+import os
 from pathlib import Path
 
 import pytest
@@ -258,6 +259,42 @@ def test_run_shadow_pass_spawns_when_threshold_met(tmp_path, monkeypatch):
     assert long_msg.strip()[:40] in kw["prompt"]
 
 
+def test_run_shadow_pass_single_flight_when_child_running(tmp_path, monkeypatch):
+    pkg = _bootstrap(tmp_path, monkeypatch, min_chars="100")
+    conn = pkg["db"].get_db()
+    now = int(time.time())
+    long_msg = "Pattern: in this type of task always X. " * 10
+    _seed_dialog(conn, "user", long_msg, now - 5)
+    conn.execute(
+        "INSERT INTO tasks (id, pid, parent_cid, spawned_cid, cwd, prompt, "
+        "started_at, rss_kb, rss_updated_at) "
+        "VALUES (?,?,?,?,?,?,?,?,?)",
+        (
+            "tk_shadow_running",
+            os.getpid(),
+            "parent",
+            "child",
+            str(tmp_path),
+            pkg["shadow_review"].SHADOW_REVIEW_PROMPT,
+            now - 1,
+            123,
+            now,
+        ),
+    )
+    conn.commit()
+
+    import threadkeeper.tools.spawn as spawn_mod
+
+    def should_not_spawn(**kwargs):
+        raise AssertionError("shadow pass should be single-flight")
+
+    monkeypatch.setattr(spawn_mod, "spawn", should_not_spawn)
+    out = pkg["shadow_review"].run_shadow_pass(force=True)
+    assert out == "shadow_child_running n=1"
+    # Cursor does not advance; retry the same window when the child exits.
+    assert pkg["shadow_review"]._last_shadow_ts(conn) == 0
+
+
 def test_run_shadow_pass_idempotent_after_cursor_advance(tmp_path, monkeypatch):
     """Second pass over the same data must produce no_window once cursor
     catches up."""
@@ -314,6 +351,24 @@ def test_daemon_does_not_start_in_slim_child(tmp_path, monkeypatch):
     )
 
 
+def test_daemon_does_not_start_in_marked_spawned_child(tmp_path, monkeypatch):
+    """The cascade guard must not depend only on NO_EMBEDDINGS.
+
+    Some CLIs launch MCP servers from a config env block, so the child
+    process may not reliably inherit THREADKEEPER_NO_EMBEDDINGS. The explicit
+    THREADKEEPER_SPAWNED_CHILD marker still has to stop shadow_review.
+    """
+    monkeypatch.setenv("THREADKEEPER_SPAWNED_CHILD", "1")
+    pkg = _bootstrap(tmp_path, monkeypatch, interval="60")
+    import threadkeeper.config as cfg
+    monkeypatch.setattr(cfg, "SEMANTIC_AVAILABLE", True)
+    pkg["shadow_review"]._started = False
+    pkg["shadow_review"].start_shadow_daemon()
+    assert pkg["shadow_review"]._started is False, (
+        "marked spawned child should refuse to start shadow daemon"
+    )
+
+
 def test_mcp_shadow_review_status_reports_passes(tmp_path, monkeypatch):
     pkg = _bootstrap(tmp_path, monkeypatch)
     pkg["shadow_review"]._record_shadow_pass(

{threadkeeper-0.5.2 → threadkeeper-0.6.0}/tests/test_skill_hint.py

@@ -1,5 +1,5 @@
 """brief() skill_hint nudge — fires when a recently-closed thread is rich
-enough to be worth materializing as a Claude skill under ~/.claude/skills/.
+enough to be worth materializing as a mirrored reusable skill.
 
 After complex tasks, the agent should turn distilled insights into
 reusable skills, not let them sit only in notes. The nudge surfaces