threadkeeper 0.8.0__tar.gz → 0.8.1__tar.gz

{threadkeeper-0.8.0 → threadkeeper-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.8.0
+Version: 0.8.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
@@ -82,10 +82,12 @@ make it more than a memory store:
   concurrent sessions signal each other across CLIs. Parent /
   children / sibling agents become a coordinated swarm, not isolated
   chats.
-- **Self-improving skill library** — five autonomous background loops
+- **Self-improving skill library** — autonomous background loops
   (auto-review on thread close, shadow-review daemon, extract
-  harvester, candidate-reviewer, weekly Curator) materialize
-  class-level skills as the agents work. Adapted to multi-CLI:
+  harvester, candidate-reviewer, weekly Curator, and a thread-janitor
+  that auto-closes idle threads so abandoned work reaches the harvest
+  path — closing is reversible, a note reopens a closed thread)
+  materialize class-level skills as the agents work. Adapted to multi-CLI:
   SKILL.md is the primary write target and gets mirrored to every
   known/configured skills root simultaneously (`~/.claude/skills/`,
   `~/.codex/skills/`, existing `~/.agents/skills/`, extra roots from
@@ -519,6 +521,22 @@ them with `dry_run=False` to apply:
 
 ---
 
+## Telemetry
+
+- **`mp_dashboard(window_days=7)`** — one-call rollup of the whole
+  system, read-only. Three sections: **stores** (threads by state,
+  notes/dialog/distill/concepts counts, skills + claims by tier,
+  extract-candidate and evolve queues, probe/task counts), **loops**
+  (how many times each autonomous daemon fired in the window vs 30 days,
+  plus last-fire age), and **outcomes** (what those loops actually
+  produced — skills materialized, tier promotions, candidate
+  accept-vs-reject rate). Surfaces the gaps the point-tools can't:
+  a loop firing constantly while its outcomes stay flat, or a queue
+  backing up. Complements the per-loop `*_status` tools (`mp_health`,
+  `spawn_budget_status`, `shadow_review_status`).
+
+---
+
 ## Storage
 
 `~/.threadkeeper/db.sqlite` (overridable via `THREADKEEPER_DB`). WAL

{threadkeeper-0.8.0 → threadkeeper-0.8.1}/README.md

@@ -43,10 +43,12 @@ make it more than a memory store:
   concurrent sessions signal each other across CLIs. Parent /
   children / sibling agents become a coordinated swarm, not isolated
   chats.
-- **Self-improving skill library** — five autonomous background loops
+- **Self-improving skill library** — autonomous background loops
   (auto-review on thread close, shadow-review daemon, extract
-  harvester, candidate-reviewer, weekly Curator) materialize
-  class-level skills as the agents work. Adapted to multi-CLI:
+  harvester, candidate-reviewer, weekly Curator, and a thread-janitor
+  that auto-closes idle threads so abandoned work reaches the harvest
+  path — closing is reversible, a note reopens a closed thread)
+  materialize class-level skills as the agents work. Adapted to multi-CLI:
   SKILL.md is the primary write target and gets mirrored to every
   known/configured skills root simultaneously (`~/.claude/skills/`,
   `~/.codex/skills/`, existing `~/.agents/skills/`, extra roots from
@@ -480,6 +482,22 @@ them with `dry_run=False` to apply:
 
 ---
 
+## Telemetry
+
+- **`mp_dashboard(window_days=7)`** — one-call rollup of the whole
+  system, read-only. Three sections: **stores** (threads by state,
+  notes/dialog/distill/concepts counts, skills + claims by tier,
+  extract-candidate and evolve queues, probe/task counts), **loops**
+  (how many times each autonomous daemon fired in the window vs 30 days,
+  plus last-fire age), and **outcomes** (what those loops actually
+  produced — skills materialized, tier promotions, candidate
+  accept-vs-reject rate). Surfaces the gaps the point-tools can't:
+  a loop firing constantly while its outcomes stay flat, or a queue
+  backing up. Complements the per-loop `*_status` tools (`mp_health`,
+  `spawn_budget_status`, `shadow_review_status`).
+
+---
+
 ## Storage
 
 `~/.threadkeeper/db.sqlite` (overridable via `THREADKEEPER_DB`). WAL

{threadkeeper-0.8.0 → threadkeeper-0.8.1}/pyproject.toml

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

@@ -0,0 +1,123 @@
+"""mp_dashboard — aggregate rollup tool.
+
+Verifies the tool renders all sections, counts seeded stores, reflects
+loop-pass + outcome events, and degrades without crashing on an empty DB.
+
+NOTE on isolation: assertions are DELTA-based, never absolute counts. The
+suite's `test_tools_smoke.py` does a `del sys.modules` + package re-import
++ every-tool invocation at COLLECTION time in the parent process, which
+`os.environ.setdefault`-pins a DB path and seeds rows. So "exactly N
+threads" is not guaranteed across the full suite even with `fresh_mp`'s
+tmp DB — we assert that the dashboard reflects the rows THIS test adds
+(before/after delta), which is the real contract anyway.
+"""
+from __future__ import annotations
+
+import re
+import time
+
+
+def _tool(pkg, name):
+    return pkg["mcp"]._tool_manager._tools[name].fn
+
+
+def _count(out: str, key: str) -> int:
+    """Pull `<key>=N` from the dashboard text. Absence means zero: when a
+    store is empty the grouped `threads:` line collapses to `threads: 0`
+    (no `active=` token), and that genuinely means 0 active threads — so a
+    missing key reads as 0, which keeps before/after deltas correct."""
+    m = re.search(rf"\b{re.escape(key)}=(\d+)", out)
+    return int(m.group(1)) if m else 0
+
+
+def _active_count(out: str) -> int:
+    return _count(out, "active")
+
+
+def _notes_count(out: str) -> int:
+    return _count(out, "notes")
+
+
+def _concepts_count(out: str) -> int:
+    return _count(out, "concepts")
+
+
+def test_dashboard_registered(fresh_mp):
+    assert "mp_dashboard" in fresh_mp["mcp"]._tool_manager._tools
+
+
+def test_dashboard_empty_db_no_crash(fresh_mp):
+    out = _tool(fresh_mp, "mp_dashboard")()
+    for section in ("dashboard", "stores", "loops", "outcomes", "reliability"):
+        assert section in out, (section, out)
+
+
+def test_dashboard_counts_stores_delta(fresh_mp):
+    dash = _tool(fresh_mp, "mp_dashboard")
+    before = dash()
+    a0, n0, c0 = (_active_count(before), _notes_count(before),
+                  _concepts_count(before))
+
+    open_thread = _tool(fresh_mp, "open_thread")
+    note = _tool(fresh_mp, "note")
+    t1 = open_thread(question="alpha")
+    open_thread(question="beta")
+    note(thread_id=t1, content="a note here", kind="insight")
+    note(thread_id=t1, content="another move", kind="move")
+    _tool(fresh_mp, "register_concept")(description="a concept by example",
+                                        confidence="low")
+
+    after = dash()
+    assert _active_count(after) - a0 == 2, (a0, after)
+    assert _notes_count(after) - n0 == 2, (n0, after)
+    assert _concepts_count(after) - c0 == 1, (c0, after)
+
+
+def _shadow_win(out: str) -> int:
+    m = re.search(r"shadow\s+(\d+) / \d+", out)
+    return int(m.group(1)) if m else 0
+
+
+def test_dashboard_reflects_loop_and_outcome_events(fresh_mp):
+    # Delta measured THROUGH the tool itself (before vs after), so both reads
+    # go through the identical DB-resolution path — immune to whatever DB a
+    # contaminated parent env pinned. Insert the loop/outcome events the
+    # daemons would write, then confirm the dashboard's own count rises by 3.
+    conn = fresh_mp["db"].get_db()
+    now = int(time.time())
+    before = _shadow_win(_tool(fresh_mp, "mp_dashboard")(window_days=7))
+    for _ in range(3):
+        conn.execute(
+            "INSERT INTO events (session_id, kind, target, summary, created_at) "
+            "VALUES ('s', 'shadow_review_pass', ?, '', ?)", (str(now), now))
+    conn.execute(
+        "INSERT INTO events (session_id, kind, target, summary, created_at) "
+        "VALUES ('s', 'skill_materialized', 'Tx', 'path', ?)", (now,))
+    conn.commit()
+    after_out = _tool(fresh_mp, "mp_dashboard")(window_days=7)
+    assert _shadow_win(after_out) - before == 3, (before, after_out)
+    assert "skill_materialized" in after_out, after_out
+
+
+def test_dashboard_accept_rate(fresh_mp):
+    conn = fresh_mp["db"].get_db()
+    now = int(time.time())
+    # Snapshot existing decisions so the ratio assertion is exact regardless
+    # of pre-seeded rows.
+    acc0 = conn.execute(
+        "SELECT COUNT(*) FROM events WHERE kind LIKE 'accept_candidate%'"
+    ).fetchone()[0]
+    rej0 = conn.execute(
+        "SELECT COUNT(*) FROM events WHERE kind='reject_candidate'"
+    ).fetchone()[0]
+    conn.execute(
+        "INSERT INTO events (session_id, kind, target, created_at) "
+        "VALUES ('s','accept_candidate:note','1',?)", (now,))
+    for _ in range(3):
+        conn.execute(
+            "INSERT INTO events (session_id, kind, target, created_at) "
+            "VALUES ('s','reject_candidate','x',?)", (now,))
+    conn.commit()
+    out = _tool(fresh_mp, "mp_dashboard")()
+    acc, dec = acc0 + 1, acc0 + 1 + rej0 + 3
+    assert f"candidate_accept_rate {acc}/{dec}" in out, (acc0, rej0, out)

{threadkeeper-0.8.0 → threadkeeper-0.8.1}/tests/test_extract_daemon.py

@@ -347,6 +347,61 @@ def test_extract_filters_shadow_observer_sessions(tmp_path, monkeypatch):
     assert not any(r["source_cid"] == "shadow-sess" for r in rows)
 
 
+def test_extract_filters_spawned_child_sessions(tmp_path, monkeypatch):
+    """A session whose cid is a tasks.spawned_cid is one of OUR spawned
+    children (curator, panel voter, ad-hoc research agent, ...). Its dialog
+    is system-injected task framing + work artifacts, never user intent —
+    exclude it wholesale, regardless of how its prompt opens. This catches
+    the noise the prompt-prefix list misses: real rejects included children
+    opening with 'You are auditing…', 'You are analyzing whether…',
+    'Use the Write tool to…' — none matched _INTERNAL_PROMPT_PREFIXES, so
+    66/107 historical rejects were exactly this class."""
+    pkg = _bootstrap(tmp_path, monkeypatch)
+    conn = pkg["db"].get_db()
+    now = int(time.time())
+    child_cid = "child-cid-xyz"
+    # Register the child in tasks (parent spawned it). Prompt text is
+    # deliberately NOT in any prefix list — the link is what identifies it.
+    conn.execute(
+        "INSERT INTO tasks (id, pid, parent_cid, spawned_cid, cwd, prompt, "
+        "started_at) VALUES ('tk_x', 0, 'parent-cid', ?, '/x', "
+        "'You are auditing a slice of lessons. Analyze each one.', ?)",
+        (child_cid, now - 200),
+    )
+    # The child emits substantive-looking dialog that WOULD trip H1/H2/H3.
+    _seed_dialog(
+        conn, "user",
+        "I want you to record the decision: always reset the network "
+        "before WDA start, every single run.",
+        now - 90, session_id=child_cid,
+    )
+    _seed_dialog(
+        conn, "assistant",
+        "## Findings\n\nWe want the pipeline to always dedup first.\n"
+        "Therefore the rule is: dedup before enrich. In conclusion, that "
+        "is the durable pattern here for every future run of this job.",
+        now - 85, session_id=child_cid,
+    )
+    # A genuine foreground user session — must still be picked up.
+    _seed_dialog(
+        conn, "user",
+        "I want you to record decision notes automatically without "
+        "waiting for the agent to remember each time.",
+        now - 60, session_id="real-sess",
+    )
+    conn.commit()
+
+    out = pkg["extract_daemon"].run_extract_pass(force=True)
+    assert "ok" in out
+    rows = conn.execute(
+        "SELECT source_cid FROM extract_candidates WHERE status='pending'"
+    ).fetchall()
+    assert any(r["source_cid"] == "real-sess" for r in rows), \
+        "real user session should still yield candidates"
+    assert not any(r["source_cid"] == child_cid for r in rows), \
+        "spawned-child session must be fully excluded"
+
+
 # ──────────────────────────────────────────────────────────────────────
 # Daemon lifecycle
 # ──────────────────────────────────────────────────────────────────────

{threadkeeper-0.8.0 → threadkeeper-0.8.1}/tests/test_skills.py

@@ -31,6 +31,22 @@ def skills_pkg(tmp_path, monkeypatch):
         "CLAUDE_PROJECTS_DIR": str(tmp_path / "fake_claude_projects"),
         "THREADKEEPER_INGEST_INTERVAL_S": "0",
         "THREADKEEPER_INGEST_CAP": "0",
+        # Disable every background daemon. Without this the skill_watcher
+        # daemon runs live and races delete tests: it scans CLAUDE_SKILLS_DIR
+        # on a timer and re-INSERTs a skill_usage row right after a test's
+        # delete removed dir+row, making test_delete_removes_skill_dir_and_
+        # usage_row flake (~2 in 20). Same daemon-vs-test TOCTOU the conftest
+        # _force_clean_env guards against; this bespoke fixture must mirror it.
+        "THREADKEEPER_SKILL_WATCH_INTERVAL_S": "0",
+        "THREADKEEPER_SPAWN_BUDGET_POLL_S": "0",
+        "THREADKEEPER_MEMORY_GUARD_POLL_S": "0",
+        "THREADKEEPER_SEARCH_PROXY_POLL_S": "0",
+        "THREADKEEPER_SHADOW_REVIEW_INTERVAL_S": "0",
+        "THREADKEEPER_CURATOR_INTERVAL_S": "0",
+        "THREADKEEPER_EXTRACT_INTERVAL_S": "0",
+        "THREADKEEPER_CANDIDATE_REVIEW_INTERVAL_S": "0",
+        "THREADKEEPER_PROBE_INTERVAL_S": "0",
+        "THREADKEEPER_EVOLVE_REVIEW_INTERVAL_S": "0",
         "THREADKEEPER_TASK_LOG_DIR": str(tmp_path / "tasks"),
         "THREADKEEPER_CLIENT": "pytest",
         "THREADKEEPER_FORCE_CID": _FAKE_CID,

threadkeeper-0.8.1/tests/test_thread_janitor.py

@@ -0,0 +1,180 @@
+"""Thread-janitor daemon — closes idle threads so the skill-harvest path
+(close_thread → auto-review hook) actually runs.
+
+Isolation: bespoke _bootstrap mirrors conftest._force_clean_env (all
+daemons off) so the janitor only fires when a test calls run_janitor_pass
+directly. AUTO_REVIEW off here — we test the CLOSE behavior; the harvest
+hook is close_thread's own tested concern.
+"""
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+
+
+_FAKE_CID = "11111111-2222-3333-4444-555555555555"
+
+
+def _bootstrap(tmp_path, monkeypatch, interval="0", idle_days="1"):
+    env = {
+        "THREADKEEPER_DB": str(tmp_path / "db.sqlite"),
+        "CLAUDE_PROJECTS_DIR": str(tmp_path / "fake_claude_projects"),
+        "THREADKEEPER_INGEST_INTERVAL_S": "0",
+        "THREADKEEPER_INGEST_CAP": "0",
+        "THREADKEEPER_SKILL_WATCH_INTERVAL_S": "0",
+        "THREADKEEPER_SPAWN_BUDGET_POLL_S": "0",
+        "THREADKEEPER_MEMORY_GUARD_POLL_S": "0",
+        "THREADKEEPER_SEARCH_PROXY_POLL_S": "0",
+        "THREADKEEPER_SHADOW_REVIEW_INTERVAL_S": "0",
+        "THREADKEEPER_CURATOR_INTERVAL_S": "0",
+        "THREADKEEPER_EXTRACT_INTERVAL_S": "0",
+        "THREADKEEPER_CANDIDATE_REVIEW_INTERVAL_S": "0",
+        "THREADKEEPER_PROBE_INTERVAL_S": "0",
+        "THREADKEEPER_EVOLVE_REVIEW_INTERVAL_S": "0",
+        "THREADKEEPER_THREAD_JANITOR_INTERVAL_S": interval,
+        "THREADKEEPER_THREAD_IDLE_CLOSE_DAYS": idle_days,
+        "THREADKEEPER_AUTO_REVIEW": "",  # off — harvest hook is close_thread's concern
+        "THREADKEEPER_LESSONS": str(tmp_path / "lessons.md"),
+        "THREADKEEPER_TASK_LOG_DIR": str(tmp_path / "tasks"),
+        "THREADKEEPER_CLIENT": "pytest",
+        "THREADKEEPER_FORCE_CID": _FAKE_CID,
+        "THREADKEEPER_NO_EMBEDDINGS": "1",
+    }
+    for k, v in env.items():
+        monkeypatch.setenv(k, v)
+    Path(env["CLAUDE_PROJECTS_DIR"]).mkdir(parents=True, exist_ok=True)
+    for name in [m for m in list(sys.modules) if m.startswith("threadkeeper")]:
+        del sys.modules[name]
+    import threadkeeper.server  # noqa: F401
+    from threadkeeper import db, thread_janitor, identity, _mcp
+    return {
+        "db": db,
+        "thread_janitor": thread_janitor,
+        "identity": identity,
+        "mcp": _mcp.mcp,
+    }
+
+
+def _tool(pkg, name):
+    return pkg["mcp"]._tool_manager._tools[name].fn
+
+
+def _age_thread(conn, tid, days_ago):
+    """Backdate a thread's last_touched_at by `days_ago` days."""
+    ts = int(time.time()) - int(days_ago * 86400)
+    conn.execute(
+        "UPDATE threads SET last_touched_at=? WHERE id=?", (ts, tid)
+    )
+    conn.commit()
+
+
+# ──────────────────────────────────────────────────────────────────────
+# dispatch / gating
+# ──────────────────────────────────────────────────────────────────────
+
+def test_disabled_without_force(tmp_path, monkeypatch):
+    pkg = _bootstrap(tmp_path, monkeypatch, interval="0")
+    assert pkg["thread_janitor"].run_janitor_pass() == "disabled"
+
+
+def test_no_stale_when_all_fresh(tmp_path, monkeypatch):
+    pkg = _bootstrap(tmp_path, monkeypatch)
+    _tool(pkg, "open_thread")(question="fresh thread")
+    # default last_touched_at = now → not stale
+    assert pkg["thread_janitor"].run_janitor_pass(force=True) == "no_stale"
+
+
+# ──────────────────────────────────────────────────────────────────────
+# closing behavior
+# ──────────────────────────────────────────────────────────────────────
+
+def test_closes_stale_active_thread(tmp_path, monkeypatch):
+    pkg = _bootstrap(tmp_path, monkeypatch, idle_days="1")
+    conn = pkg["db"].get_db()
+    tid = _tool(pkg, "open_thread")(question="stale one")
+    _age_thread(conn, tid, days_ago=2)  # older than 1d threshold
+    out = pkg["thread_janitor"].run_janitor_pass(force=True)
+    assert out == "closed=1", out
+    row = conn.execute("SELECT state, outcome FROM threads WHERE id=?",
+                       (tid,)).fetchone()
+    assert row["state"] == "closed"
+    assert "janitor" in (row["outcome"] or "")
+
+
+def test_closes_stale_idle_thread(tmp_path, monkeypatch):
+    pkg = _bootstrap(tmp_path, monkeypatch, idle_days="1")
+    conn = pkg["db"].get_db()
+    tid = _tool(pkg, "open_thread")(question="parked")
+    _tool(pkg, "idle_thread")(thread_id=tid)
+    _age_thread(conn, tid, days_ago=3)
+    out = pkg["thread_janitor"].run_janitor_pass(force=True)
+    assert out == "closed=1", out
+    row = conn.execute("SELECT state FROM threads WHERE id=?", (tid,)).fetchone()
+    assert row["state"] == "closed"
+
+
+def test_leaves_fresh_thread_open(tmp_path, monkeypatch):
+    pkg = _bootstrap(tmp_path, monkeypatch, idle_days="1")
+    conn = pkg["db"].get_db()
+    stale = _tool(pkg, "open_thread")(question="stale")
+    fresh = _tool(pkg, "open_thread")(question="fresh")
+    _age_thread(conn, stale, days_ago=2)
+    # fresh keeps default now-ish last_touched_at
+    out = pkg["thread_janitor"].run_janitor_pass(force=True)
+    assert out == "closed=1", out
+    s = conn.execute("SELECT state FROM threads WHERE id=?", (stale,)).fetchone()
+    f = conn.execute("SELECT state FROM threads WHERE id=?", (fresh,)).fetchone()
+    assert s["state"] == "closed"
+    assert f["state"] == "active"
+
+
+def test_idempotent_second_pass(tmp_path, monkeypatch):
+    pkg = _bootstrap(tmp_path, monkeypatch, idle_days="1")
+    conn = pkg["db"].get_db()
+    tid = _tool(pkg, "open_thread")(question="stale")
+    _age_thread(conn, tid, days_ago=2)
+    assert pkg["thread_janitor"].run_janitor_pass(force=True) == "closed=1"
+    # already closed → not re-matched
+    assert pkg["thread_janitor"].run_janitor_pass(force=True) == "no_stale"
+
+
+def test_closed_then_note_reopens_survives_janitor(tmp_path, monkeypatch):
+    """The whole safety story end-to-end: janitor closes a stale thread,
+    a note reopens it (fresh last_touched_at), and the next janitor pass
+    leaves it alone because it's no longer stale."""
+    pkg = _bootstrap(tmp_path, monkeypatch, idle_days="1")
+    conn = pkg["db"].get_db()
+    tid = _tool(pkg, "open_thread")(question="comes back")
+    _age_thread(conn, tid, days_ago=2)
+    pkg["thread_janitor"].run_janitor_pass(force=True)
+    assert conn.execute("SELECT state FROM threads WHERE id=?",
+                        (tid,)).fetchone()["state"] == "closed"
+    # user returns → agent notes on it → reopen
+    _tool(pkg, "note")(thread_id=tid, content="picking this back up", kind="move")
+    assert conn.execute("SELECT state FROM threads WHERE id=?",
+                        (tid,)).fetchone()["state"] == "active"
+    # fresh now, so a second janitor pass must not re-close it
+    assert pkg["thread_janitor"].run_janitor_pass(force=True) == "no_stale"
+    assert conn.execute("SELECT state FROM threads WHERE id=?",
+                        (tid,)).fetchone()["state"] == "active"
+
+
+def test_records_janitor_pass_event(tmp_path, monkeypatch):
+    pkg = _bootstrap(tmp_path, monkeypatch, idle_days="1")
+    conn = pkg["db"].get_db()
+    tid = _tool(pkg, "open_thread")(question="stale")
+    _age_thread(conn, tid, days_ago=2)
+    pkg["thread_janitor"].run_janitor_pass(force=True)
+    row = conn.execute(
+        "SELECT summary FROM events WHERE kind='janitor_pass' "
+        "ORDER BY id DESC LIMIT 1"
+    ).fetchone()
+    assert row is not None
+    assert "closed=1" in row["summary"]
+
+
+def test_daemon_does_not_start_at_interval_zero(tmp_path, monkeypatch):
+    pkg = _bootstrap(tmp_path, monkeypatch, interval="0")
+    pkg["thread_janitor"].start_thread_janitor()
+    assert pkg["thread_janitor"]._started is False

{threadkeeper-0.8.0 → threadkeeper-0.8.1}/threadkeeper/config.py

@@ -372,3 +372,22 @@ EVOLVE_REVIEW_INTERVAL_S: float = float(
 EVOLVE_REVIEW_MIN: int = int(
     os.environ.get("THREADKEEPER_EVOLVE_REVIEW_MIN", "2")
 )
+
+# Thread-janitor daemon. The skill-harvest path fires on close_thread(), but
+# the user never closes threads and the agent rarely does — so threads pile
+# up open (32 active, some 12d stale in the audit) and abandoned work never
+# gets reviewed into a skill (2 auto-review spawns ever, 5 skills / 115
+# closes). This daemon closes threads that have been idle past
+# THREAD_IDLE_CLOSE_DAYS, routing through the normal close_thread() path so
+# the auto-review hook fires for the richest pending thread. Safe because
+# closing is reversible: note() revives a closed thread (see tools/threads
+# note()). 0 disables (default — opt in). Recommended: 86400 (daily) — this
+# is slow housekeeping, not a hot loop.
+THREAD_JANITOR_INTERVAL_S: float = float(
+    os.environ.get("THREADKEEPER_THREAD_JANITOR_INTERVAL_S", "0")
+)
+# Close active/idle threads whose last_touched_at is older than this many
+# days. Default 1 (user's choice): aggressive, but reopenable on return.
+THREAD_IDLE_CLOSE_DAYS: float = float(
+    os.environ.get("THREADKEEPER_THREAD_IDLE_CLOSE_DAYS", "1")
+)

{threadkeeper-0.8.0 → threadkeeper-0.8.1}/threadkeeper/identity.py

@@ -169,6 +169,11 @@ def _ensure_session(conn: sqlite3.Connection, client: Optional[str] = None) -> s
             evolve_daemon.start_evolve_daemon()
         except Exception:
             pass
+        try:
+            from . import thread_janitor
+            thread_janitor.start_thread_janitor()
+        except Exception:
+            pass
     return _session_id
 
 

{threadkeeper-0.8.0 → threadkeeper-0.8.1}/threadkeeper/server.py

@@ -53,6 +53,7 @@ from .tools import shadow_review  # noqa: F401
 from .tools import lessons  # noqa: F401
 from .tools import curator  # noqa: F401
 from .tools import candidate_reviewer  # noqa: F401
+from .tools import dashboard  # noqa: F401
 
 
 if __name__ == "__main__":

threadkeeper-0.8.1/threadkeeper/thread_janitor.py

@@ -0,0 +1,137 @@
+"""Thread-janitor daemon — autonomously close stale threads so abandoned
+work gets harvested into skills.
+
+The skill-harvest path is event-driven: `close_thread()` fires the
+auto-review hook, which spawns a background child that materializes a skill
+from a rich closed thread. But that path only runs when threads actually
+CLOSE — and in practice they don't: the user never closes threads, and the
+agent rarely remembers to. The audit found 32 threads open (some idle 12d),
+2 auto-review spawns ever, 5 skills from 115 closes. The harvest machinery
+was starved of its trigger.
+
+This daemon supplies the trigger. Each pass it finds threads idle past
+THREAD_IDLE_CLOSE_DAYS and closes them via the normal `close_thread()` path,
+so the existing auto-review hook fires (for the richest pending thread) and
+the brief's skill_hint surfaces the rest for the foreground agent.
+
+Aggressive auto-close is safe ONLY because closing is reversible: a note()
+on a closed thread revives it to active (see tools/threads.note). Returning
+to a topic — i.e. adding a note — reopens it. So the janitor can close
+freely; nothing is lost, just parked.
+
+Mirror of the other daemons: interval knob (0 = off), foreground-only via
+BACKGROUND_DAEMONS_ALLOWED so spawned children don't recurse, idempotent
+(already-closed threads don't re-match), records a `janitor_pass` event for
+observability / the dashboard.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import threading
+import time
+
+from .config import THREAD_JANITOR_INTERVAL_S, THREAD_IDLE_CLOSE_DAYS
+from .db import get_db
+from . import identity
+
+logger = logging.getLogger(__name__)
+
+_started = False
+
+
+def _record_janitor_pass(conn: sqlite3.Connection, outcome: str) -> None:
+    try:
+        conn.execute(
+            "INSERT INTO events (session_id, kind, target, summary, "
+            "created_at) VALUES (?, 'janitor_pass', '', ?, ?)",
+            (identity._session_id or "", outcome[:300], int(time.time())),
+        )
+        conn.commit()
+    except sqlite3.OperationalError:
+        logger.debug("thread_janitor: failed to record pass", exc_info=True)
+
+
+def _stale_threads(conn: sqlite3.Connection, cutoff: int) -> list[sqlite3.Row]:
+    """Active or idle threads not touched since `cutoff`, oldest first."""
+    try:
+        return conn.execute(
+            "SELECT id, question FROM threads "
+            "WHERE state IN ('active','idle') AND last_touched_at < ? "
+            "ORDER BY last_touched_at ASC",
+            (cutoff,),
+        ).fetchall()
+    except sqlite3.OperationalError:
+        return []
+
+
+def run_janitor_pass(force: bool = False) -> str:
+    """One janitor pass: close every thread idle past the threshold via
+    close_thread() (which fires the auto-review hook). Returns a short
+    status string for observability:
+
+      'disabled'        — knob off and not forced
+      'no_stale'        — nothing past the idle threshold
+      'closed=N'        — closed N stale threads
+    """
+    if THREAD_JANITOR_INTERVAL_S <= 0 and not force:
+        return "disabled"
+    conn = get_db()
+    now = int(time.time())
+    cutoff = now - int(max(0.0, THREAD_IDLE_CLOSE_DAYS) * 86400)
+    stale = _stale_threads(conn, cutoff)
+    if not stale:
+        _record_janitor_pass(conn, "no_stale")
+        return "no_stale"
+
+    # Late import — tools.threads imports brief/embeddings; importing at
+    # module load would risk a cycle. close_thread() owns the state change,
+    # the close event, AND the auto-review hook, so routing through it keeps
+    # the janitor's closes indistinguishable from a manual close.
+    from .tools.threads import close_thread
+
+    days = THREAD_IDLE_CLOSE_DAYS
+    days_disp = int(days) if float(days).is_integer() else days
+    outcome = f"auto-closed by janitor: idle > {days_disp}d (reopen via note)"
+    closed = 0
+    for t in stale:
+        try:
+            res = close_thread(thread_id=t["id"], outcome=outcome)
+            if isinstance(res, str) and res.startswith("ok"):
+                closed += 1
+        except Exception:  # noqa: BLE001 — never crash the daemon on one row
+            logger.debug("thread_janitor: close failed for %s",
+                         t["id"], exc_info=True)
+    out = f"closed={closed}"
+    _record_janitor_pass(conn, out)
+    return out
+
+
+def _serve_loop() -> None:
+    while True:
+        try:
+            run_janitor_pass()
+        except Exception:
+            logger.debug("thread_janitor tick failed", exc_info=True)
+        time.sleep(THREAD_JANITOR_INTERVAL_S)
+
+
+def start_thread_janitor() -> None:
+    """Idempotent starter. No-op when THREAD_JANITOR_INTERVAL_S<=0. Same
+    cascade prevention as the other daemons: spawned children / non-
+    foreground origins refuse to start it, so a review child the janitor
+    triggers can't spin up its own janitor."""
+    global _started
+    if _started:
+        return
+    if THREAD_JANITOR_INTERVAL_S <= 0:
+        return
+    from .config import BACKGROUND_DAEMONS_ALLOWED
+    if not BACKGROUND_DAEMONS_ALLOWED:
+        return
+    t = threading.Thread(
+        target=_serve_loop, name="thread_janitor", daemon=True,
+    )
+    t.start()
+    _started = True