threadkeeper 0.4.0__py3-none-any.whl

threadkeeper/tools/pickup.py

@@ -0,0 +1,148 @@
+"""Self-initiated pickup of stale unresolved threads.
+
+Surfaces idle, unclaimed threads as candidates for autonomous work, lets a
+caller claim one (optionally spawning a headless child to advance it), and
+releases the claim when done.
+"""
+
+import sqlite3
+import time
+from typing import Optional
+
+from .._mcp import mcp
+from ..db import get_db
+from ..helpers import fmt_age, q
+from .. import identity
+from ..identity import _ensure_session, _detect_self_cid, _emit
+from ..embeddings import _embed
+from .spawn import spawn
+
+
+@mcp.tool()
+def pickup_candidates(min_idle_days: int = 3, max_n: int = 5) -> str:
+    """Surface unresolved threads that are stale and unclaimed — candidates
+    for self-initiated pickup when context is free.
+
+    Ranks by oldest last_touched_at among active+idle threads with no current
+    claim. Adds a one-line summary so caller can decide which to claim."""
+    conn = get_db()
+    _ensure_session(conn)
+    now_t = int(time.time())
+    cutoff = now_t - max(0, int(min_idle_days)) * 86400
+    rows = conn.execute(
+        "SELECT id, question, state, last_touched_at, last_move "
+        "FROM threads "
+        "WHERE state IN ('active','idle') "
+        "AND last_touched_at <= ? AND claimed_at IS NULL "
+        "ORDER BY last_touched_at ASC LIMIT ?",
+        (cutoff, max(1, int(max_n))),
+    ).fetchall()
+    if not rows:
+        return f"no_candidates (no unclaimed thread idle >= {min_idle_days}d)"
+    lines = [f"candidates n={len(rows)} idle>={min_idle_days}d"]
+    for t in rows:
+        idle = fmt_age(now_t - t["last_touched_at"])
+        last_move_short = (t["last_move"] or "(no notes)")[:80]
+        lines.append(
+            f"  {t['id']} [{t['state']}] q={q(t['question'][:90])} "
+            f"idle={idle} last={q(last_move_short)}"
+        )
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def claim_pickup(thread_id: str, plan: str = "",
+                 spawn_role: str = "", auto_spawn: bool = False) -> str:
+    """Claim a thread for self-initiated work. Marks it claimed by my cid.
+
+    If `auto_spawn=True`, immediately spawns a headless child with the
+    thread context (question + recent notes + plan) for parallel work.
+    `spawn_role` defaults to 'executor' when auto_spawn is on."""
+    conn = get_db()
+    _ensure_session(conn)
+    self_cid = _detect_self_cid()
+    if not self_cid:
+        return "ERR cannot_detect_self_cid"
+    tid = thread_id.strip()
+    t = conn.execute(
+        "SELECT id, question, state, claimed_at, claimed_by_cid "
+        "FROM threads WHERE id=?",
+        (tid,),
+    ).fetchone()
+    if not t:
+        return f"ERR thread_not_found={tid}"
+    if t["claimed_at"] and t["claimed_by_cid"] != self_cid:
+        return (
+            f"ERR already_claimed by={(t['claimed_by_cid'] or '')[:8]} "
+            f"at={fmt_age(int(time.time()) - t['claimed_at'])}_ago"
+        )
+    now_t = int(time.time())
+    conn.execute(
+        "UPDATE threads SET claimed_at=?, claimed_by_cid=?, "
+        "last_touched_at=? WHERE id=?",
+        (now_t, self_cid, now_t, tid),
+    )
+    if plan:
+        emb = _embed(plan)
+        conn.execute(
+            "INSERT INTO notes (thread_id, content, kind, created_at, "
+            "session_id, embedding) VALUES (?,?,?,?,?,?)",
+            (tid, f"PICKUP plan: {plan}", "move", now_t, identity._session_id, emb),
+        )
+    _emit(conn, "claim_pickup", target=tid,
+          summary=plan[:140] if plan else (t["question"] or ""))
+    conn.commit()
+
+    spawn_info = ""
+    if auto_spawn:
+        notes = conn.execute(
+            "SELECT kind, content FROM notes WHERE thread_id=? "
+            "ORDER BY created_at DESC LIMIT 8",
+            (tid,),
+        ).fetchall()
+        notes_block = "\n".join(
+            f"  [{n['kind']}] {n['content'][:240]}" for n in notes
+        ) or "  (no notes yet)"
+        child_prompt = (
+            f"Pickup task — make progress on a stale unresolved thread.\n\n"
+            f"Thread question: {t['question']}\n\n"
+            f"Recent notes:\n{notes_block}\n\n"
+            f"Plan from caller: {plan or '(infer one and proceed)'}\n\n"
+            f"Make ONE concrete advance. Add a note to the thread "
+            f"(mcp__thread-keeper__note with thread_id={tid}, kind='move'). "
+            f"When done, broadcast 'pickup-{tid}: <one-line result>'."
+        )
+        result = spawn(
+            prompt=child_prompt,
+            visible=False,
+            permission_mode="auto",
+            role=spawn_role or "executor",
+            extra_allowed_tools="Read,Bash,Grep,Glob",
+        )
+        spawn_info = f" | spawn: {result}"
+    return f"ok claimed thread={tid}{spawn_info}"
+
+
+@mcp.tool()
+def release_pickup(thread_id: str) -> str:
+    """Release a claim. Only the claimant can release."""
+    conn = get_db()
+    _ensure_session(conn)
+    self_cid = _detect_self_cid()
+    if not self_cid:
+        return "ERR cannot_detect_self_cid"
+    tid = thread_id.strip()
+    t = conn.execute(
+        "SELECT claimed_by_cid FROM threads WHERE id=?", (tid,),
+    ).fetchone()
+    if not t or not t["claimed_by_cid"]:
+        return "not_claimed"
+    if t["claimed_by_cid"] != self_cid:
+        return f"ERR not_my_claim by={t['claimed_by_cid'][:8]}"
+    conn.execute(
+        "UPDATE threads SET claimed_at=NULL, claimed_by_cid=NULL WHERE id=?",
+        (tid,),
+    )
+    _emit(conn, "release_pickup", target=tid)
+    conn.commit()
+    return f"ok released thread={tid}"

threadkeeper/tools/probes.py

@@ -0,0 +1,251 @@
+"""Self-diagnostic probes: claude-shape weak-spot tracking.
+
+Probes encode known reliability sags (counting in long context, date math,
+verbatim recall, format compliance, etc.). Each attempt → probe_results;
+rolling stats → reliability cache; brief surfaces weak_spots.
+"""
+
+import sqlite3
+import time
+from typing import Optional
+
+from .._mcp import mcp
+from ..db import get_db
+from ..helpers import fmt_age, q, gen_probe_id
+from .. import identity
+from ..identity import _ensure_session, _detect_self_cid, _emit
+
+
+def _grade_probe(grader: str, expected_pattern: Optional[str],
+                 response: str) -> bool:
+    """Apply grader to a response. 'manual' always returns False — caller
+    confirms correctness via record_attempt(success=True)."""
+    if grader == "manual" or not expected_pattern:
+        return False
+    if grader == "exact":
+        return expected_pattern in response
+    if grader == "regex":
+        try:
+            import re as _re
+            return _re.search(expected_pattern, response, _re.DOTALL) is not None
+        except Exception:
+            return False
+    return False
+
+
+def _recompute_reliability(conn: sqlite3.Connection, category: str) -> dict:
+    """Recompute aggregate stats for one category from probe_results.
+    UPSERTs the reliability row. Returns the new aggregate as a dict."""
+    now_t = int(time.time())
+    overall = conn.execute(
+        "SELECT COUNT(*) c, SUM(success) s, MAX(created_at) last "
+        "FROM probe_results WHERE category=?",
+        (category,),
+    ).fetchone()
+    attempts = overall["c"] or 0
+    successes = overall["s"] or 0
+    last_at = overall["last"]
+
+    def _fail_rate(window_s: int) -> Optional[float]:
+        cutoff = now_t - window_s
+        r = conn.execute(
+            "SELECT COUNT(*) c, SUM(success) s "
+            "FROM probe_results WHERE category=? AND created_at >= ?",
+            (category, cutoff),
+        ).fetchone()
+        n = r["c"] or 0
+        if n == 0:
+            return None
+        s = r["s"] or 0
+        return (n - s) / n
+
+    fr_7 = _fail_rate(7 * 86400)
+    fr_30 = _fail_rate(30 * 86400)
+    conn.execute(
+        "INSERT INTO reliability (category, attempts, successes, last_at, "
+        "fail_rate_7d, fail_rate_30d, updated_at) VALUES (?,?,?,?,?,?,?) "
+        "ON CONFLICT(category) DO UPDATE SET "
+        "  attempts=excluded.attempts, successes=excluded.successes, "
+        "  last_at=excluded.last_at, fail_rate_7d=excluded.fail_rate_7d, "
+        "  fail_rate_30d=excluded.fail_rate_30d, updated_at=excluded.updated_at",
+        (category, attempts, successes, last_at, fr_7, fr_30, now_t),
+    )
+    return {
+        "category": category, "attempts": attempts, "successes": successes,
+        "last_at": last_at, "fail_rate_7d": fr_7, "fail_rate_30d": fr_30,
+    }
+
+
+@mcp.tool()
+def register_probe(category: str, prompt: str,
+                   expected_pattern: str = "",
+                   grader: str = "regex") -> str:
+    """Register a self-test probe: a known weak-spot task with a verifier.
+
+    `grader`: 'regex' (pattern match in response), 'exact' (substring), or
+    'manual' (claude self-grades — always counts as failure unless caller
+    explicitly confirms success via record_attempt). `expected_pattern`
+    optional for 'manual'.
+
+    Categories should be claude-shape: 'count_long_context',
+    'date_arithmetic', 'recall_verbatim_block', 'detect_contradiction',
+    'follow_negative_instruction', 'preserve_list_order',
+    'respect_length_limit', 'needle_mid_context', 'fact_vs_inference',
+    'notice_absence', 'strict_format_compliance', 'uncertainty_acknowledgment'."""
+    if grader not in ("regex", "exact", "manual"):
+        return f"ERR bad_grader={grader}"
+    if not category.strip() or not prompt.strip():
+        return "ERR empty_category_or_prompt"
+    conn = get_db()
+    _ensure_session(conn)
+    pid = gen_probe_id(conn)
+    conn.execute(
+        "INSERT INTO probes (id, category, prompt, expected_pattern, "
+        "grader, created_at) VALUES (?,?,?,?,?,?)",
+        (pid, category.strip(), prompt, expected_pattern or None,
+         grader, int(time.time())),
+    )
+    _emit(conn, "probe_register", target=pid, summary=category)
+    conn.commit()
+    return f"ok id={pid} cat={category}"
+
+
+@mcp.tool()
+def run_probe(probe_id: str) -> str:
+    """Surface a registered probe for self-attempt. Returns the prompt and
+    the grader hint. After attempting, call record_attempt(category,
+    success=true/false, probe_id=...) — the harness doesn't auto-grade
+    because attempting and judging are the same model."""
+    conn = get_db()
+    _ensure_session(conn)
+    p = conn.execute(
+        "SELECT id, category, prompt, expected_pattern, grader, enabled "
+        "FROM probes WHERE id=?",
+        (probe_id.strip(),),
+    ).fetchone()
+    if not p:
+        return f"ERR probe_not_found={probe_id}"
+    if not p["enabled"]:
+        return f"ERR probe_disabled={probe_id}"
+    parts = [
+        f"probe={p['id']} cat={p['category']} grader={p['grader']}",
+    ]
+    if p["expected_pattern"]:
+        parts.append(f"expect={p['expected_pattern']}")
+    parts.append(f"prompt={p['prompt']}")
+    return "\n".join(parts)
+
+
+@mcp.tool()
+def record_attempt(category: str, success: bool, note: str = "",
+                   probe_id: str = "", latency_ms: int = 0) -> str:
+    """Record a self-test outcome. Updates reliability aggregates.
+
+    Use for both registered probes (pass `probe_id`) and ad-hoc self-
+    observations — e.g. you noticed yourself miscounting items in this
+    very turn → record_attempt('count_long_context', false, note='said 32, actual 47')."""
+    if not category.strip():
+        return "ERR empty_category"
+    conn = get_db()
+    _ensure_session(conn)
+    cat = category.strip()
+    pid = probe_id.strip() or None
+    if pid:
+        if not conn.execute("SELECT 1 FROM probes WHERE id=?", (pid,)).fetchone():
+            return f"ERR probe_not_found={pid}"
+    now_t = int(time.time())
+    cid = _detect_self_cid()
+    cur = conn.execute(
+        "INSERT INTO probe_results (probe_id, category, session_id, cid, "
+        "success, latency_ms, note, created_at) VALUES (?,?,?,?,?,?,?,?)",
+        (pid, cat, identity._session_id, cid, 1 if success else 0,
+         latency_ms or None, note or None, now_t),
+    )
+    agg = _recompute_reliability(conn, cat)
+    _emit(conn, "probe_attempt", target=cat,
+          summary=f"{'pass' if success else 'fail'}: {note[:120]}")
+    conn.commit()
+    fr_7 = agg["fail_rate_7d"]
+    fr_str = f"{fr_7:.2f}" if fr_7 is not None else "?"
+    return (
+        f"ok rid={cur.lastrowid} cat={cat} "
+        f"attempts={agg['attempts']} successes={agg['successes']} "
+        f"fail7d={fr_str}"
+    )
+
+
+@mcp.tool()
+def reliability_for(category: str, window_days: int = 30) -> str:
+    """Reliability stats for one category over a window."""
+    if not category.strip():
+        return "ERR empty_category"
+    conn = get_db()
+    cat = category.strip()
+    now_t = int(time.time())
+    cutoff = now_t - max(1, window_days) * 86400
+    win = conn.execute(
+        "SELECT COUNT(*) c, SUM(success) s, MAX(created_at) last "
+        "FROM probe_results WHERE category=? AND created_at >= ?",
+        (cat, cutoff),
+    ).fetchone()
+    n = win["c"] or 0
+    if n == 0:
+        return f"cat={cat} no_data window={window_days}d"
+    s = win["s"] or 0
+    rate = s / n
+    last = win["last"]
+    cached = conn.execute(
+        "SELECT fail_rate_7d, fail_rate_30d FROM reliability WHERE category=?",
+        (cat,),
+    ).fetchone()
+    fr7 = (
+        f"{cached['fail_rate_7d']:.2f}"
+        if cached and cached["fail_rate_7d"] is not None
+        else "?"
+    )
+    fr30 = (
+        f"{cached['fail_rate_30d']:.2f}"
+        if cached and cached["fail_rate_30d"] is not None
+        else "?"
+    )
+    return (
+        f"cat={cat} window={window_days}d attempts={n} success={s} "
+        f"rate={rate:.2f} fail7d={fr7} fail30d={fr30} "
+        f"last={fmt_age(now_t - last)}_ago"
+    )
+
+
+@mcp.tool()
+def weak_spots(top_n: int = 5) -> str:
+    """List categories ranked by recent failure rate (min 3 attempts in 30d),
+    plus registered probe categories with no attempts yet (= unknown,
+    equally important to test)."""
+    conn = get_db()
+    now_t = int(time.time())
+    weak = conn.execute(
+        "SELECT category, fail_rate_7d, fail_rate_30d, attempts, last_at "
+        "FROM reliability WHERE fail_rate_30d IS NOT NULL AND attempts >= 3 "
+        "ORDER BY COALESCE(fail_rate_7d, fail_rate_30d) DESC LIMIT ?",
+        (max(1, top_n),),
+    ).fetchall()
+    unknown = conn.execute(
+        "SELECT DISTINCT p.category FROM probes p "
+        "LEFT JOIN reliability r ON r.category = p.category "
+        "WHERE p.enabled = 1 AND (r.category IS NULL OR r.attempts = 0)"
+    ).fetchall()
+    out = [f"weak n={len(weak)}"]
+    for r in weak:
+        age = fmt_age(now_t - r["last_at"]) if r["last_at"] else "?"
+        f7 = f"{r['fail_rate_7d']:.2f}" if r["fail_rate_7d"] is not None else "?"
+        f30 = f"{r['fail_rate_30d']:.2f}" if r["fail_rate_30d"] is not None else "?"
+        out.append(
+            f"  {r['category']} fail7d={f7} fail30d={f30} "
+            f"n={r['attempts']} last={age}_ago"
+        )
+    if unknown:
+        out.append(f"unknown n={len(unknown)}")
+        for r in unknown:
+            out.append(f"  {r['category']} (never_tested)")
+    if not weak and not unknown:
+        return "no_data (register probes via register_probe)"
+    return "\n".join(out)

threadkeeper/tools/process_health.py

@@ -0,0 +1,90 @@
+"""MCP tools for inspecting and pruning orphaned thread-keeper processes.
+
+Each Claude client spawns its own thread-keeper subprocess. Crashed clients
+leave orphan processes that hold RAM (especially with sentence-transformers
+loaded). These tools surface the situation and let you clean up.
+"""
+
+from .._mcp import mcp
+from .. import process_health
+
+
+@mcp.tool()
+def mp_health() -> str:
+    """Diagnostic snapshot of every running thread-keeper server process
+    on this machine. Shows pid, parent status, RSS, heartbeat age, and
+    whether each is classified as orphaned (parent gone + no fresh
+    heartbeat from its session).
+
+    Self (the process answering this call) is always marked is_self=true
+    and never flagged as orphan."""
+    procs = process_health.scan()
+    if not procs:
+        return "no_mp_processes_running"
+
+    total_kb = sum(p["rss_kb"] for p in procs)
+    orphans = [p for p in procs if p.get("is_orphaned")]
+    live = [p for p in procs if not p.get("is_orphaned")]
+    out = [
+        f"total={len(procs)} live={len(live)} orphans={len(orphans)} "
+        f"rss_total={total_kb // 1024}MB"
+    ]
+    for p in procs:
+        flag = "self" if p["is_self"] else ("ORPHAN" if p["is_orphaned"] else "live")
+        hb = p["heartbeat_age_s"]
+        hb_disp = f"{hb}s" if hb is not None else "?"
+        parent = "alive" if p["parent_alive"] else "dead"
+        rss_mb = p["rss_kb"] // 1024
+        out.append(
+            f"  pid={p['pid']:<6} ppid={p['ppid']:<6} ({parent})  "
+            f"rss={rss_mb}MB  hb={hb_disp}  etime={p['etime']}  "
+            f"[{flag}]  {p.get('orphan_reason','-')}"
+        )
+    if orphans:
+        out.append(
+            f"\nCleanup plan: mp_cleanup(dry_run=False) would SIGTERM "
+            f"{len(orphans)} orphan(s); add force=True for SIGKILL."
+        )
+    return "\n".join(out)
+
+
+@mcp.tool()
+def mp_cleanup(dry_run: bool = True, force: bool = False) -> str:
+    """Kill orphaned thread-keeper processes (parent gone AND heartbeat
+    stale for > 5 minutes). Defaults to dry-run — pass dry_run=False to
+    actually send signals. force=True uses SIGKILL instead of SIGTERM.
+
+    Never touches the current process or processes whose parent is still
+    alive. Safe to run repeatedly."""
+    result = process_health.cleanup(dry_run=dry_run, force=force)
+    procs = result["all_procs"]
+    orphans = result["orphans"]
+    if not orphans:
+        return (
+            f"nothing_to_do: {len(procs)} mp process(es) running, "
+            "all healthy"
+        )
+    if dry_run:
+        lines = [f"plan dry_run=True orphans={len(orphans)}"]
+        for p in orphans:
+            rss_mb = p["rss_kb"] // 1024
+            lines.append(
+                f"  would SIGTERM pid={p['pid']} rss={rss_mb}MB "
+                f"reason={p['orphan_reason']}"
+            )
+        free_mb = sum(p["rss_kb"] for p in orphans) // 1024
+        lines.append(
+            f"\napprox {free_mb}MB to be freed; call "
+            "mp_cleanup(dry_run=False) to apply."
+        )
+        return "\n".join(lines)
+    # Apply
+    lines = [
+        f"applied {'SIGKILL' if force else 'SIGTERM'}: "
+        f"killed={len(result['killed'])} failed={len(result['failed'])}"
+    ]
+    for pid in result["killed"]:
+        lines.append(f"  ok pid={pid}")
+    for f in result["failed"]:
+        lines.append(f"  ERR pid={f['pid']} {f['err']}")
+    return "\n".join(lines)

threadkeeper/tools/session.py

@@ -0,0 +1,34 @@
+"""Session lifecycle close-out: mark the active session ended and optionally
+record a terse summary note for future briefs."""
+
+import sqlite3
+import time
+
+from .._mcp import mcp
+from ..db import get_db
+from ..helpers import fmt_age
+from ..embeddings import _embed
+from .. import identity
+
+
+@mcp.tool()
+def session_end(summary: str = "") -> str:
+    """Mark current session ended with optional terse summary."""
+    if identity._session_id is None:
+        return "no_active_session"
+    conn = get_db()
+    now = int(time.time())
+    sid = identity._session_id
+    started = identity._session_start or now
+    conn.execute("UPDATE sessions SET ended_at=? WHERE id=?", (now, sid))
+    if summary:
+        emb = _embed(summary)
+        conn.execute(
+            "INSERT INTO notes (thread_id, content, kind, created_at, session_id, embedding) "
+            "VALUES (NULL,?,?,?,?,?)",
+            (summary, "session_summary", now, sid, emb),
+        )
+    conn.commit()
+    identity._session_id = None
+    identity._session_start = None
+    return f"closed sess={sid} dur={fmt_age(now - started)}"

threadkeeper/tools/shadow_review.py

@@ -0,0 +1,106 @@
+"""MCP tools for the shadow-review machinery.
+
+  shadow_review_run(force=False, dry_run=False)
+    Trigger one shadow pass NOW. `force=True` overrides the
+    SHADOW_REVIEW_INTERVAL_S=0 disable. `dry_run=True` returns the prompt
+    that WOULD be spawned (no actual spawn) — useful for inspecting
+    candidate windows or building tests.
+
+  shadow_review_status()
+    Diagnostic snapshot: env config, cursor position, last 5 passes.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+from .._mcp import mcp
+from ..db import get_db
+from ..identity import _ensure_session
+from ..shadow_review import (
+    SHADOW_REVIEW_PROMPT,
+    _collect_window,
+    _last_shadow_ts,
+    _record_shadow_pass,
+    run_shadow_pass,
+)
+from ..config import (
+    SHADOW_REVIEW_INTERVAL_S,
+    SHADOW_REVIEW_MIN_CHARS,
+    SHADOW_REVIEW_WINDOW_S,
+)
+
+
+@mcp.tool()
+def shadow_review_run(force: bool = False, dry_run: bool = False) -> str:
+    """Fire one shadow-review pass.
+
+    `force=True` runs even when the daemon is disabled (interval=0). Used
+    by tests and one-shot triage.
+
+    `dry_run=True` short-circuits before the spawn — returns the dialog
+    dump that WOULD be evaluated, plus n_chars and high-water cursor. No
+    spawn. No cursor advance. Use this to inspect candidate windows
+    before paying for an evaluator child.
+    """
+    conn = get_db()
+    _ensure_session(conn)
+    if dry_run:
+        floor = _last_shadow_ts(conn)
+        dump, high_water, n_chars = _collect_window(
+            conn, floor, SHADOW_REVIEW_WINDOW_S,
+        )
+        if n_chars == 0:
+            return "dry_run: no_window (nothing new since last cursor)"
+        head = dump[:2000]
+        suffix = "…(truncated for display)" if len(dump) > 2000 else ""
+        return (
+            f"dry_run: n_chars={n_chars} high_water_ts={high_water} "
+            f"min_chars={SHADOW_REVIEW_MIN_CHARS} "
+            f"would_spawn={'yes' if n_chars >= SHADOW_REVIEW_MIN_CHARS else 'no'}\n\n"
+            f"--- prompt preview ---\n"
+            f"{SHADOW_REVIEW_PROMPT[:400]}…\n\n"
+            f"--- dialog window head ---\n{head}{suffix}"
+        )
+    return run_shadow_pass(force=force)
+
+
+@mcp.tool()
+def shadow_review_status() -> str:
+    """Show shadow-review configuration + last 5 passes.
+
+    Snapshot for sanity-checking that the daemon is alive and
+    advancing its cursor. Counts how many spawned passes vs how many
+    were skipped for being too short or empty."""
+    conn = get_db()
+    _ensure_session(conn)
+    floor = _last_shadow_ts(conn)
+    now = int(time.time())
+    age_s = (now - floor) if floor else None
+    lines = [
+        f"interval_s={SHADOW_REVIEW_INTERVAL_S:.0f} "
+        f"window_s={SHADOW_REVIEW_WINDOW_S} "
+        f"min_chars={SHADOW_REVIEW_MIN_CHARS}",
+        f"cursor_ts={floor} (age={age_s}s)" if floor
+        else "cursor_ts=0 (no prior pass)",
+        "",
+        "recent passes (newest first):",
+    ]
+    try:
+        rows = conn.execute(
+            "SELECT created_at, summary FROM events "
+            "WHERE kind='shadow_review_pass' "
+            "ORDER BY id DESC LIMIT 5"
+        ).fetchall()
+    except Exception:
+        rows = []
+    if not rows:
+        lines.append("  (none)")
+    else:
+        for r in rows:
+            ts = r["created_at"]
+            age = now - int(ts) if ts else 0
+            snip = (r["summary"] or "")[:120]
+            lines.append(f"  {age}s_ago  {snip}")
+    return "\n".join(lines)