threadkeeper 0.5.3__tar.gz → 0.6.1__tar.gz

{threadkeeper-0.5.3 → threadkeeper-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.5.3
+Version: 0.6.1
 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
@@ -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`
@@ -275,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
@@ -418,8 +424,19 @@ 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_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_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.3 → threadkeeper-0.6.1}/README.md

@@ -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`
@@ -241,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
@@ -384,8 +390,19 @@ 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_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_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.3 → threadkeeper-0.6.1}/pyproject.toml

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

@@ -0,0 +1,255 @@
+"""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, "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"],
+    })
+
+    def scan():
+        return [
+            _proc(os.getpid(), 900),
+            _proc(1001, 1200, ppid=1) | {
+                "heartbeat_age_s": None,
+                "parent_alive": False,
+                "is_orphaned": True,
+                "orphan_reason": "parent_gone + no_heartbeat",
+            },
+            _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)]
+
+
+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(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.5.3 → threadkeeper-0.6.1}/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.3 → threadkeeper-0.6.1}/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.3 → threadkeeper-0.6.1}/tests/test_spawn_slim.py

@@ -44,7 +44,12 @@ def test_build_slim_mcp_config_from_claude_json(tmp_path, monkeypatch):
         del sys.modules[name]
     from threadkeeper.tools.spawn import _build_slim_mcp_config
 
-    slim_path = _build_slim_mcp_config("tk_test01")
+    slim_path = _build_slim_mcp_config("tk_test01", {
+        "THREADKEEPER_FORCE_CID": _FAKE_CID,
+        "THREADKEEPER_SPAWNED_CHILD": "1",
+        "THREADKEEPER_NO_EMBEDDINGS": "1",
+        "THREADKEEPER_WRITE_ORIGIN": "shadow_review",
+    })
     assert slim_path is not None
     assert slim_path.exists()
     data = json.loads(slim_path.read_text())
@@ -53,6 +58,11 @@ def test_build_slim_mcp_config_from_claude_json(tmp_path, monkeypatch):
     mp = data["mcpServers"]["thread-keeper"]
     assert mp["command"] == "/path/to/python"
     assert mp["args"] == ["-m", "threadkeeper.server"]
+    assert mp["env"]["PYTHONPATH"] == "/path/to/repo"
+    assert mp["env"]["THREADKEEPER_FORCE_CID"] == _FAKE_CID
+    assert mp["env"]["THREADKEEPER_SPAWNED_CHILD"] == "1"
+    assert mp["env"]["THREADKEEPER_NO_EMBEDDINGS"] == "1"
+    assert mp["env"]["THREADKEEPER_WRITE_ORIGIN"] == "shadow_review"
 
 
 def test_build_slim_mcp_config_synthesizes_when_no_claude_json(tmp_path, monkeypatch):
@@ -70,7 +80,10 @@ def test_build_slim_mcp_config_synthesizes_when_no_claude_json(tmp_path, monkeyp
         del sys.modules[name]
     from threadkeeper.tools.spawn import _build_slim_mcp_config
 
-    slim_path = _build_slim_mcp_config("tk_synth")
+    slim_path = _build_slim_mcp_config("tk_synth", {
+        "THREADKEEPER_SPAWNED_CHILD": "1",
+        "THREADKEEPER_NO_EMBEDDINGS": "1",
+    })
     assert slim_path is not None
     data = json.loads(slim_path.read_text())
     assert "thread-keeper" in data["mcpServers"]
@@ -79,6 +92,8 @@ def test_build_slim_mcp_config_synthesizes_when_no_claude_json(tmp_path, monkeyp
     assert mp["command"] == sys.executable
     assert "threadkeeper.server" in mp["args"]
     assert "PYTHONPATH" in mp["env"]
+    assert mp["env"]["THREADKEEPER_SPAWNED_CHILD"] == "1"
+    assert mp["env"]["THREADKEEPER_NO_EMBEDDINGS"] == "1"
 
 
 def test_spawn_slim_falls_back_to_full_config_when_unable(tmp_path, monkeypatch):

{threadkeeper-0.5.3 → threadkeeper-0.6.1}/threadkeeper/_setup.py

@@ -2,8 +2,8 @@
 
 Idempotently wires thread-keeper into a Claude Code installation:
   1. Registers `thread-keeper` MCP server in ~/.claude.json
-  2. Installs hooks (SessionStart, PostToolUse, UserPromptSubmit) in
-     ~/.claude/settings.json
+  2. Installs hooks (SessionStart, PostToolUse, UserPromptSubmit, Stop,
+     PreToolUse) in ~/.claude/settings.json
   3. Copies hook scripts to ~/.threadkeeper/hooks/
   4. Updates the managed block in ~/.claude/CLAUDE.md between sentinel
      markers — content outside the markers is preserved.
@@ -69,8 +69,11 @@ At session start:
     If the user's opening message is substantive, pass it as `query`
     to `brief()` to inline relevant past notes.
 
-During the conversation:
-- New substantive topic → `open_thread()`.
+During the conversation (a UserPromptSubmit hook nudges you once per
+session if you haven't opened a thread, and a Stop hook reminds you to
+close at the end — but the discipline is yours; act before the nudge):
+- The FIRST substantive topic of a session (debugging, a feature, a
+  multi-step task) → `open_thread()` BEFORE diving into tool calls.
 - Topic resolved with an outcome → `close_thread(thread_id, outcome)`.
 - After every turn that produced a decision or insight →
   `note(thread_id, ..., kind in ['move','failed','insight','open_q'])`.
@@ -149,7 +152,14 @@ def install_hooks(dry_run: bool) -> list[str]:
     # and is referenced by every supporting CLI.
     if not dry_run:
         TK_HOOKS_DIR.mkdir(parents=True, exist_ok=True)
-    for fname in ("tk-brief.sh", "tk-status.sh", "inbox-check.sh"):
+    for fname in (
+        "tk-brief.sh",
+        "tk-status.sh",
+        "inbox-check.sh",
+        "tk-task-gate.sh",
+        "tk-thread-nudge.sh",
+        "tk-session-end.sh",
+    ):
         src = HOOKS_SRC / fname
         dst = TK_HOOKS_DIR / fname
         if not src.exists():
@@ -182,6 +192,28 @@ def install_hooks(dry_run: bool) -> list[str]:
             "matcher": "",
             "command": str(TK_HOOKS_DIR / "inbox-check.sh"),
         },
+        # Open-thread safety net: once per session, nudge open_thread() if
+        # none was opened yet (additionalContext, non-blocking).
+        {
+            "event": "UserPromptSubmit",
+            "matcher": "",
+            "command": str(TK_HOOKS_DIR / "tk-thread-nudge.sh"),
+        },
+        # close_thread / session_end safety net at end of turn (throttled to
+        # once per session; advisory systemMessage, never blocks stopping).
+        {
+            "event": "Stop",
+            "matcher": "",
+            "command": str(TK_HOOKS_DIR / "tk-session-end.sh"),
+        },
+        # spawn-vs-Task gate: block the built-in Task tool for work that
+        # should go through mcp__thread-keeper__spawn() (Claude Code only;
+        # other CLIs ignore an unknown PreToolUse event).
+        {
+            "event": "PreToolUse",
+            "matcher": "^Task$",
+            "command": str(TK_HOOKS_DIR / "tk-task-gate.sh"),
+        },
     ]
 
     # 3) Ask each installed adapter to wire them up in its native

{threadkeeper-0.5.3 → threadkeeper-0.6.1}/threadkeeper/brief.py

@@ -10,6 +10,7 @@ pickup_top, evolve_pending, and the trailing user-facing reminder.
 shared dialog log tailed by open_dialog_window().
 """
 
+import os
 import re
 import sqlite3
 import time
@@ -339,6 +340,33 @@ def render_brief(conn: sqlite3.Connection, query: str = "", k: int = 6) -> str:
         for t in closed_t:
             out.append(f"  {t['id']} out={q((t['outcome'] or '-')[:120])}")
 
+    # ── thread_hint (open-thread nudge for hook-less clients) ─────────────
+    # Claude Code / Gemini / Copilot get the open-thread reminder from the
+    # UserPromptSubmit hook (tk-thread-nudge.sh); their SessionStart hook
+    # sets THREADKEEPER_BRIEF_NO_THREAD_NUDGE so this path stays quiet and
+    # doesn't double-fire. Clients with NO hook mechanism (Claude Desktop,
+    # Codex, VS Code) call brief() directly — they have no env set, so the
+    # nudge surfaces here instead. See nudges.compute_thread_nudge.
+    if not os.environ.get("THREADKEEPER_BRIEF_NO_THREAD_NUDGE"):
+        try:
+            from .nudges import compute_thread_nudge
+            th_nudge = compute_thread_nudge(conn, identity._session_id or "")
+        except (sqlite3.OperationalError, ImportError):
+            th_nudge = None
+        if th_nudge:
+            out.append("")
+            out.append(th_nudge)
+            try:
+                conn.execute(
+                    "INSERT INTO events (session_id, kind, target, summary, "
+                    "created_at) VALUES (?,?,?,?,?)",
+                    (identity._session_id or "", "thread_hint_shown",
+                     self_cid or "", "", now),
+                )
+                conn.commit()
+            except sqlite3.OperationalError:
+                pass
+
     # ── memory_nudge ──────────────────────────────────────────────────────
     # Counter-driven (active push, not just passive surface): when N mutating
     # events have passed in this session without a memory save, escalate from