threadkeeper 0.4.0__py3-none-any.whl

threadkeeper/search_proxy.py

@@ -0,0 +1,160 @@
+"""Search-proxy daemon: parent processes (SEMANTIC_AVAILABLE=True) serve
+semantic-search requests from spawned slim children (SEMANTIC_AVAILABLE=False).
+
+Mechanism:
+- A child without embeddings posts a `signals` row with kind='search_request'
+  addressed to the parent's cid. Payload is JSON: {query, k, mode, scope}.
+- This daemon, running ONLY in processes where SEMANTIC_AVAILABLE=True,
+  polls signals every 500ms for unread 'search_request' rows addressed to
+  me (or broadcast). For each, runs the requested search and writes back
+  a 'search_response' signal to the requester. Marks the request read.
+- The child's `search_via_parent` MCP tool wraps post + wait.
+
+Why this exists: loading sentence-transformers in every spawned child costs
+~300-500MB. Most spawned children only need to *write* a few notes/skills;
+they rarely need to *search* semantically. When they do, delegating to
+the existing parent is far cheaper than each child loading its own model.
+
+Daemon is started lazily on first _ensure_session() call. No-op when
+SEMANTIC_AVAILABLE=False — children's daemons stay silent, so each request
+is answered by exactly one parent (or zero if none exists, in which case
+the child's tool times out and falls back to FTS).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+from typing import Optional
+
+from .config import SEMANTIC_AVAILABLE
+from .db import get_db
+from . import identity
+
+logger = logging.getLogger(__name__)
+
+_started = False
+_POLL_INTERVAL_S = float(
+    __import__("os").environ.get("THREADKEEPER_SEARCH_PROXY_POLL_S", "0.5")
+)
+
+# Maximum number of requests per poll tick — guard against runaway loops.
+_MAX_BATCH = 10
+
+
+def _serve_request(conn, sig_row) -> None:
+    """Run the requested search and post a 'search_response' signal back."""
+    from .embeddings import _cosine_search, _dialog_cosine_search, _fts_search
+    from .config import SEMANTIC_AVAILABLE as _sa
+
+    try:
+        payload = json.loads(sig_row["content"])
+    except (json.JSONDecodeError, TypeError):
+        payload = {}
+    if not isinstance(payload, dict):
+        payload = {}
+
+    query = str(payload.get("query", "")).strip()
+    if not query:
+        _write_response(conn, sig_row, {"error": "empty_query", "results": []})
+        return
+
+    k = int(payload.get("k", 5) or 5)
+    if k <= 0 or k > 100:
+        k = 5
+    scope = str(payload.get("scope", "notes")).lower()  # 'notes' | 'dialog'
+    mode = str(payload.get("mode", "hybrid")).lower()   # for dialog only
+
+    hits: list[dict] = []
+    try:
+        if scope == "dialog":
+            sem = _dialog_cosine_search(conn, query, k * 3) if _sa else []
+            fts = _fts_search(conn, query, k * 3)
+            if mode == "semantic":
+                hits = sem[:k]
+            elif mode == "fts":
+                hits = fts[:k]
+            else:
+                from .embeddings import _rrf_combine
+                hits = _rrf_combine([sem, fts], top_n=k)
+        else:
+            hits = _cosine_search(conn, query, k) if _sa else []
+    except Exception as e:
+        logger.debug("search_proxy serve failed: %s", e, exc_info=True)
+        _write_response(conn, sig_row, {"error": str(e), "results": []})
+        return
+
+    # Trim payload: drop embedding blob, cap content length to keep signal small.
+    out = []
+    for h in hits:
+        h2 = {k_: v for k_, v in h.items()
+              if k_ not in ("embedding",)}
+        if isinstance(h2.get("content"), str) and len(h2["content"]) > 400:
+            h2["content"] = h2["content"][:400] + "…"
+        out.append(h2)
+    _write_response(conn, sig_row, {"results": out, "scope": scope})
+
+
+def _write_response(conn, request_row, body: dict) -> None:
+    """Post a kind='search_response' whisper back to the requester and mark
+    the original request read."""
+    now = int(time.time())
+    self_cid = identity._detect_self_cid() or ""
+    requester = request_row["from_cid"]
+    try:
+        conn.execute(
+            "INSERT INTO signals (from_cid, to_cid, kind, content, created_at) "
+            "VALUES (?, ?, 'search_response', ?, ?)",
+            (self_cid, requester, json.dumps(body), now),
+        )
+        conn.execute(
+            "UPDATE signals SET read_at=? WHERE id=?",
+            (now, request_row["id"]),
+        )
+        conn.commit()
+    except Exception as e:
+        logger.debug("search_proxy write_response failed: %s", e, exc_info=True)
+
+
+def _serve_loop() -> None:
+    while True:
+        try:
+            self_cid = identity._detect_self_cid()
+            if not self_cid:
+                time.sleep(_POLL_INTERVAL_S)
+                continue
+            conn = get_db()
+            rows = conn.execute(
+                "SELECT id, from_cid, to_cid, content, created_at "
+                "FROM signals "
+                "WHERE kind='search_request' AND read_at IS NULL "
+                "  AND (to_cid = ? OR to_cid IS NULL) "
+                "  AND from_cid != ? "
+                "ORDER BY id ASC LIMIT ?",
+                (self_cid, self_cid, _MAX_BATCH),
+            ).fetchall()
+            for r in rows:
+                _serve_request(conn, r)
+            conn.close()
+        except Exception:
+            logger.debug("search_proxy loop tick failed", exc_info=True)
+        time.sleep(_POLL_INTERVAL_S)
+
+
+def start_search_proxy() -> None:
+    """Idempotent daemon-thread starter. No-op when SEMANTIC_AVAILABLE=False
+    so light children don't compete with the parent to answer requests."""
+    global _started
+    if _started:
+        return
+    if not SEMANTIC_AVAILABLE:
+        return
+    if _POLL_INTERVAL_S <= 0:
+        return  # disabled via env (test environments, or explicit opt-out)
+    t = threading.Thread(
+        target=_serve_loop, name="search_proxy", daemon=True,
+    )
+    t.start()
+    _started = True

threadkeeper/server.py

@@ -0,0 +1,55 @@
+"""threadkeeper.server — package entry point.
+
+Importing each tools module triggers its @mcp.tool() decorators against the
+shared FastMCP singleton in threadkeeper._mcp. After all imports, the
+runtime is fully assembled; mcp.run() starts the stdio MCP loop.
+
+To launch:
+    python -m threadkeeper.server
+"""
+from __future__ import annotations
+
+# Singleton must be importable before tool modules.
+from ._mcp import mcp
+
+# Core modules — registered for completeness; no @mcp.tool() decorators here.
+# Import them so any import-time side effects happen in a predictable order.
+from . import config  # noqa: F401
+from . import db  # noqa: F401
+from . import helpers  # noqa: F401
+from . import identity  # noqa: F401
+from . import embeddings  # noqa: F401
+from . import ingest  # noqa: F401
+from . import brief  # noqa: F401
+
+# Tool modules — each import registers a group of @mcp.tool() entries on
+# the shared mcp instance. Order is deliberate: peers/spawn first because
+# pickup imports spawn for auto_spawn; brief is already imported above so
+# tools.threads can pull render_brief.
+from .tools import threads  # noqa: F401
+from .tools import style  # noqa: F401
+from .tools import peers  # noqa: F401
+from .tools import spawn  # noqa: F401
+from .tools import probes  # noqa: F401
+from .tools import concepts  # noqa: F401
+from .tools import distill  # noqa: F401
+from .tools import core_memory  # noqa: F401
+from .tools import graph  # noqa: F401
+from .tools import correlation  # noqa: F401
+from .tools import extract  # noqa: F401
+from .tools import consolidate  # noqa: F401
+from .tools import invariants  # noqa: F401
+from .tools import missed_spawns  # noqa: F401
+from .tools import dialog  # noqa: F401
+from .tools import pickup  # noqa: F401
+from .tools import session  # noqa: F401
+from .tools import skills  # noqa: F401
+from .tools import dialectic  # noqa: F401
+from .tools import process_health  # noqa: F401
+from .tools import shadow_review  # noqa: F401
+from .tools import lessons  # noqa: F401
+from .tools import curator  # noqa: F401
+
+
+if __name__ == "__main__":
+    mcp.run()

threadkeeper/shadow_review.py

@@ -0,0 +1,358 @@
+"""Shadow-review daemon: an autonomous observer that periodically scans
+recently-ingested dialog and decides whether any class-level learning
+emerged worth materializing into a Claude skill — independent of whether
+foreground Claude bothered to call close_thread.
+
+The architecture has two layers:
+
+1. PURE FUNCTIONS (below) — read dialog_messages diff since last pass,
+   build a context dump, decide whether the window is worth evaluating
+   at all (cheap char-count floor). Idempotent: tracks last-evaluated
+   timestamp via events.kind='shadow_review_pass'.
+
+2. DAEMON / SPAWN (start_shadow_daemon) — periodic thread in the parent
+   thread-keeper process. On each tick: collect candidate window, if
+   non-trivial → spawn slim child with SHADOW_REVIEW_PROMPT + dialog
+   dump. Child IS the LLM evaluator; it decides yes/no and (when yes)
+   applies skill_manage / mark_skill_materialized.
+
+Why this exists: foreground Claude is an unreliable narrator of when to
+close threads / materialize skills. The shadow pass closes that gap.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sqlite3
+import threading
+import time
+from typing import Optional
+
+from .config import (
+    SHADOW_REVIEW_INTERVAL_S,
+    SHADOW_REVIEW_MIN_CHARS,
+    SHADOW_REVIEW_WINDOW_S,
+)
+from .db import get_db
+from . import identity
+
+logger = logging.getLogger(__name__)
+
+_started = False
+
+
+# The shadow prompt is what the spawned evaluator child sees. It encodes
+# the class-vs-incident decision rubric inline so the child doesn't need
+# to (and can't, in slim mode) load the ai-memory-learning-loop skill.
+from .i18n import SHADOW_CLASS_SIGNAL_EXAMPLES
+from .review_prompts import POSITIVE_EXAMPLES
+
+SHADOW_REVIEW_PROMPT = f"""\
+You are a SHADOW LEARNING OBSERVER for thread-keeper. You read a slice
+of recent dialog from across ALL Claude sessions on this machine and
+decide whether any CLASS-LEVEL learning emerged that's worth a durable
+skill under ~/.claude/skills/.
+
+CLASS-LEVEL signals (materialize):
+{SHADOW_CLASS_SIGNAL_EXAMPLES}\
+- a debugging insight that generalizes beyond the specific bug
+- a workflow rule the user stated as policy
+- a corrected misunderstanding (existing skill is wrong/incomplete)
+- a recovery / cleanup procedure for flaky infra (the FIX outlives the
+  incident even when the symptom was env-specific)
+
+NOT class-level (skip):
+- one-off task descriptions
+- session-transient confusion that resolved itself
+- the user asking what something is
+- you complimenting yourself or summarizing what just happened
+- GENUINELY transient env errors with no durable rule ("rebooted, fixed",
+  "wrong dir, fixed"). NOTE: this is narrower than it sounds — see the
+  POSITIVE_EXAMPLES block below before defaulting to SKIP.
+
+{POSITIVE_EXAMPLES}
+
+PROCEDURE
+1. Read the dialog window below.
+2. If nothing class-level emerges → output exactly `SKIP: <one-line reason>` and stop.
+3. If class-level learning is present:
+   a. PRIMARY: call `mcp__thread-keeper__lesson_append(title, body, summary, source='shadow')`
+      to write into ~/.threadkeeper/lessons.md (shared by every CLI).
+      - title: lowercase-hyphens slug describing a CLASS of task, not the incident
+      - body: markdown rationale + procedure
+      - summary: optional one-line TL;DR
+   b. OPTIONAL: also call `mcp__thread-keeper__skill_manage(...)` to mirror
+      under ~/.claude/skills/ when Claude-specific frontmatter
+      auto-triggering adds value beyond the lesson alone.
+   c. Output `MATERIALIZED: <slug>` on success.
+
+CONSTRAINTS
+- Be conservative. False negatives (skipping) cost nothing; false
+  positives pollute the skill store.
+- Do NOT open/close memory threads. Your sole output is a skill write
+  or SKIP.
+- Do NOT cite internal IDs in human-readable output (no T-codes, cids,
+  task IDs). The user style requires plain prose.
+
+DIALOG WINDOW (most recent at the bottom)
+=========================================
+"""
+
+
+def _last_shadow_ts(conn: sqlite3.Connection) -> int:
+    """Earliest dialog-message timestamp we have NOT yet evaluated.
+
+    Returns the high-water mark recorded in the most recent
+    `events.kind='shadow_review_pass'` row. The mark lives in `target`
+    so `summary` is free for the human-readable outcome.
+    Returns 0 when no prior pass exists — caller falls back to a
+    window-based floor.
+    """
+    try:
+        row = conn.execute(
+            "SELECT target FROM events WHERE kind='shadow_review_pass' "
+            "ORDER BY id DESC LIMIT 1"
+        ).fetchone()
+    except sqlite3.OperationalError:
+        return 0
+    if not row or not row["target"]:
+        return 0
+    try:
+        return int(row["target"])
+    except (ValueError, TypeError):
+        return 0
+
+
+def _record_shadow_pass(conn: sqlite3.Connection,
+                        high_water_ts: int,
+                        outcome: str) -> None:
+    """Write a shadow_review_pass event so the next tick advances cursor.
+
+    `high_water_ts` is the created_at of the newest dialog message we
+    evaluated (stored in `target` for cursor reads). `outcome` is a
+    short human-readable status string stored in `summary` (e.g.
+    'no_window', 'spawned task_id=...', 'too_short').
+    """
+    try:
+        conn.execute(
+            "INSERT INTO events (session_id, kind, target, summary, created_at) "
+            "VALUES (?, 'shadow_review_pass', ?, ?, ?)",
+            (identity._session_id or "", str(high_water_ts),
+             outcome[:300], int(time.time())),
+        )
+        conn.commit()
+    except sqlite3.OperationalError:
+        logger.debug("shadow: failed to record pass", exc_info=True)
+
+
+# Opening lines of every prompt we ourselves inject into a spawned
+# child. When a child writes its conversation to ~/.claude/projects/
+# the parent ingests it back into dialog_messages — without this filter
+# the next shadow pass picks up its OWN prior child's reasoning as the
+# "recent dialog" and SKIPs ("dialog window contains only shadow-observer
+# task framing"). Also catches the close_thread auto-review child whose
+# prompt is built around "You are reviewing closed thread <T-code>".
+#
+# Match is on the FIRST 80 chars of the very first user message of a
+# session, so we exclude every message of that session (not just the
+# prompt itself — slim children's broadcasts, tool_results, and SKIP
+# verdicts also pollute the window).
+_INTERNAL_PROMPT_PREFIXES: tuple[str, ...] = (
+    "You are a SHADOW LEARNING OBSERVER",
+    "You are reviewing closed thread",
+)
+
+
+# Lines starting with these markers carry no semantic signal for
+# class-level learning — they're verbose adapter-side renderings of
+# tool_use / tool_result blocks (file dumps, shell output, search
+# results). Inspired by Hermes Agent v0.12's review-fork upgrade that
+# excludes prior-turn tool messages from the review summary so the
+# fork sees a clean context. We keep `[thinking]` blocks — those ARE
+# signal (chain-of-thought often contains the rule being learned).
+_NOISE_LINE_PREFIXES: tuple[str, ...] = (
+    "[tool_result]",
+    "[tool_call]",
+    "[tool_use]",
+)
+
+
+def _strip_tool_noise(text: str) -> str:
+    """Drop adapter-prefixed tool_result / tool_call lines from a message.
+
+    Returns the cleaned text. If every line in the message was a tool
+    artifact, returns the empty string — caller can decide to skip the
+    row entirely (zero-information content).
+    """
+    if not text:
+        return text
+    # Fast path: no markers → no work
+    if not any(p in text for p in _NOISE_LINE_PREFIXES):
+        return text
+    kept: list[str] = []
+    for line in text.split("\n"):
+        stripped = line.lstrip()
+        if any(stripped.startswith(p) for p in _NOISE_LINE_PREFIXES):
+            continue
+        kept.append(line)
+    return "\n".join(kept).strip("\n")
+
+
+def _collect_window(conn: sqlite3.Connection,
+                    floor_ts: int,
+                    window_s: int) -> tuple[str, int, int]:
+    """Pull dialog messages newer than max(floor_ts, now-window_s),
+    excluding any session whose opening user prompt is one of our own
+    internal spawn prompts (shadow-observer or close_thread reviewer).
+
+    Returns (dump_text, high_water_ts, char_count).
+      - dump_text: human-readable rendering ready for the shadow prompt
+      - high_water_ts: largest created_at seen (== floor for next tick)
+      - char_count: total visible char length (input to MIN_CHARS guard)
+
+    Mixes all NON-internal active sessions — that's the point. The
+    shadow agent's review pool is global across the user's real
+    conversations, not the chatter of internal review children.
+    """
+    now = int(time.time())
+    cutoff = max(floor_ts, now - max(1, window_s))
+    # Per-prefix `substr(content,1,N) = ?` is friendlier to SQLite's
+    # planner than chained `LIKE 'X%' OR LIKE 'Y%'` (no LIKE_PATTERN
+    # compile, exact prefix bytewise). N = max prefix length.
+    prefix_clauses = " OR ".join(
+        ["substr(content, 1, ?) = ?"] * len(_INTERNAL_PROMPT_PREFIXES)
+    )
+    prefix_params: list = []
+    for p in _INTERNAL_PROMPT_PREFIXES:
+        prefix_params.extend([len(p), p])
+    rows = conn.execute(
+        "SELECT role, content, created_at, session_id "
+        "FROM dialog_messages "
+        "WHERE created_at > ? "
+        "  AND session_id NOT IN ("
+        "    SELECT DISTINCT session_id FROM dialog_messages "
+        f"    WHERE role = 'user' AND ({prefix_clauses})"
+        "  ) "
+        "ORDER BY created_at ASC",
+        (cutoff, *prefix_params),
+    ).fetchall()
+    if not rows:
+        return ("", cutoff, 0)
+    lines: list[str] = []
+    char_count = 0
+    high_water = cutoff
+    for r in rows:
+        body = _strip_tool_noise(r["content"] or "")
+        if not body:
+            # Whole turn was tool noise — skip but still advance the
+            # cursor (we don't want to re-evaluate this row next pass).
+            high_water = max(high_water, int(r["created_at"]))
+            continue
+        # Cap each turn at 1.5KB so a single noisy block doesn't blow
+        # the prompt budget. Most class-level signals are short.
+        if len(body) > 1500:
+            body = body[:1500] + "…"
+        char_count += len(body)
+        high_water = max(high_water, int(r["created_at"]))
+        sid = (r["session_id"] or "?")[-6:]
+        lines.append(f"[{r['role']} @{sid}]\n{body}\n")
+    return ("\n".join(lines), high_water, char_count)
+
+
+def run_shadow_pass(force: bool = False) -> str:
+    """Execute one shadow pass synchronously. Used by the daemon AND by
+    the MCP tool for manual triggering / testing.
+
+    Returns a short status string for observability:
+      - 'disabled'        — env knob off and not forced
+      - 'no_window'       — no fresh dialog since last cursor
+      - 'too_short'       — window exists but < MIN_CHARS
+      - 'spawned task_id=…' — evaluator child launched
+      - 'spawn_error: …'  — spawn() rejected (budget cap, etc)
+    """
+    if SHADOW_REVIEW_INTERVAL_S <= 0 and not force:
+        return "disabled"
+    conn = get_db()
+    floor = _last_shadow_ts(conn)
+    dump, high_water, n_chars = _collect_window(
+        conn, floor, SHADOW_REVIEW_WINDOW_S,
+    )
+    if n_chars == 0:
+        _record_shadow_pass(conn, high_water, "no_window")
+        return "no_window"
+    if n_chars < SHADOW_REVIEW_MIN_CHARS:
+        _record_shadow_pass(conn, high_water, "too_short")
+        return "too_short"
+
+    full_prompt = SHADOW_REVIEW_PROMPT + dump
+
+    # Late import — spawn module imports identity / config; importing it
+    # at module load time would create cycles.
+    from .tools.spawn import spawn  # type: ignore
+    try:
+        result = spawn(
+            prompt=full_prompt,
+            visible=False,
+            capture_output=True,
+            permission_mode="auto",
+            role="shadow_observer",
+            write_origin="shadow_review",
+            slim=True,
+            extra_allowed_tools=(
+                "mcp__thread-keeper__lesson_append,"
+                "mcp__thread-keeper__lesson_list,"
+                "mcp__thread-keeper__skill_manage,"
+                "mcp__thread-keeper__skill_list,"
+                "mcp__thread-keeper__mark_skill_materialized,"
+                "Read,Write"
+            ),
+        )
+    except Exception as e:
+        _record_shadow_pass(conn, high_water, f"spawn_error: {e}")
+        return f"spawn_error: {e}"
+
+    _record_shadow_pass(conn, high_water, str(result)[:200])
+    return str(result)
+
+
+def _serve_loop() -> None:
+    """Daemon body. Sleep → tick → sleep, until process dies."""
+    while True:
+        try:
+            run_shadow_pass()
+        except Exception:
+            logger.debug("shadow_review tick failed", exc_info=True)
+        time.sleep(SHADOW_REVIEW_INTERVAL_S)
+
+
+def start_shadow_daemon() -> None:
+    """Idempotent daemon starter. Honors env: no-op when
+    SHADOW_REVIEW_INTERVAL_S<=0 so tests stay quiet.
+
+    CRITICAL: only the parent mp process runs this daemon. Spawned slim
+    children DO start their own MCP server (so they can call tools), and
+    each MCP server in turn calls _ensure_session() which would start
+    yet another shadow daemon — that one tries to spawn its own
+    evaluator children, which themselves spawn more shadows, etc.
+    A recursive spawn cascade.
+
+    We tell parent-vs-child by SEMANTIC_AVAILABLE: parents load the
+    embedding model and have it True; slim children get NO_EMBEDDINGS=1
+    injected by spawn() so they're False. Same gating that search_proxy
+    uses for the symmetric reason.
+    """
+    global _started
+    if _started:
+        return
+    if SHADOW_REVIEW_INTERVAL_S <= 0:
+        return
+    from .config import SEMANTIC_AVAILABLE
+    if not SEMANTIC_AVAILABLE:
+        return  # slim child: don't fire shadow review from here
+    t = threading.Thread(
+        target=_serve_loop, name="shadow_review", daemon=True,
+    )
+    t.start()
+    _started = True

threadkeeper/skill_watcher.py

@@ -0,0 +1,96 @@
+"""Background daemon that watches ~/.claude/skills/*/SKILL.md for mtime
+changes and updates skill_usage telemetry. Catches patches made via
+external editors / direct Edit/Write tool calls that bypass skill_manage.
+
+Tick interval is configurable; default 10s. Daemon thread, started lazily
+on first _ensure_session() call so import-time side effects stay
+minimal. Reads only — never writes to SKILL.md.
+"""
+
+from __future__ import annotations
+import logging
+import os
+import threading
+import time
+from typing import Optional
+
+from .config import CLAUDE_SKILLS_DIR
+from .db import get_db
+
+logger = logging.getLogger(__name__)
+
+_started = False
+_tick_interval_s = float(os.environ.get(
+    'THREADKEEPER_SKILL_WATCH_INTERVAL_S', '10'))
+
+
+def _scan_once(conn) -> int:
+    """Scan ~/.claude/skills/*/SKILL.md mtimes. For each file whose mtime
+    is newer than skill_usage.last_patched_at (or row missing), bump
+    last_patched_at + patch_count. Returns number of rows updated.
+    """
+    if not CLAUDE_SKILLS_DIR.exists():
+        return 0
+    updates = 0
+    for skill_dir in CLAUDE_SKILLS_DIR.iterdir():
+        if not skill_dir.is_dir():
+            continue
+        if skill_dir.name.startswith('.'):  # skip .archive
+            continue
+        md = skill_dir / 'SKILL.md'
+        if not md.exists():
+            continue
+        try:
+            mtime = int(md.stat().st_mtime)
+        except OSError:
+            continue
+        name = skill_dir.name
+        # Ensure row exists; insert with foreground origin if not present
+        # (this is a user-edited skill, not agent-created).
+        conn.execute(
+            "INSERT INTO skill_usage (name, created_at, created_by_origin) "
+            "VALUES (?, ?, 'foreground') ON CONFLICT(name) DO NOTHING",
+            (name, mtime),
+        )
+        row = conn.execute(
+            "SELECT last_patched_at FROM skill_usage WHERE name=?",
+            (name,),
+        ).fetchone()
+        prev = row['last_patched_at'] if row and row['last_patched_at'] else 0
+        if mtime > prev:
+            conn.execute(
+                "UPDATE skill_usage SET last_patched_at=?, "
+                "patch_count=patch_count+1 WHERE name=?",
+                (mtime, name),
+            )
+            updates += 1
+    if updates:
+        conn.commit()
+    return updates
+
+
+def _watch_loop() -> None:
+    while True:
+        try:
+            conn = get_db()
+            try:
+                _scan_once(conn)
+            finally:
+                conn.close()
+        except Exception:
+            logger.debug("skill_watcher tick failed", exc_info=True)
+        time.sleep(_tick_interval_s)
+
+
+def start_skill_watcher() -> None:
+    """Start the daemon if not already running. Safe to call multiple times."""
+    global _started
+    if _started:
+        return
+    if _tick_interval_s <= 0:
+        return
+    t = threading.Thread(
+        target=_watch_loop, name='skill_watcher', daemon=True,
+    )
+    t.start()
+    _started = True