nexo-brain 2.7.0 → 3.0.0

package/src/dashboard/app.py

@@ -240,6 +240,12 @@ def _summarize_engineering_loop(weekly: dict, monthly: dict) -> dict:
     protocol_delta = trend.get("protocol_compliance_delta")
     if isinstance(protocol_delta, (int, float)) and protocol_delta > 0:
         improving.append({"title": "Protocol", "detail": f"{protocol_delta:+.1f}%", "tone": "healthy", "meta": "vs previous window"})
+    duplicate_followup_delta = trend.get("followup_duplicate_open_delta")
+    if isinstance(duplicate_followup_delta, int) and duplicate_followup_delta < 0:
+        improving.append({"title": "Followup duplication", "detail": f"{duplicate_followup_delta:+d}", "tone": "healthy", "meta": "open duplicates"})
+    learning_noise_delta = trend.get("learning_noise_delta")
+    if isinstance(learning_noise_delta, int) and learning_noise_delta < 0:
+        improving.append({"title": "Learning noise", "detail": f"{learning_noise_delta:+d}", "tone": "healthy", "meta": "active noise pressure"})
     corrections_delta = trend.get("total_corrections_delta")
     if isinstance(corrections_delta, int) and corrections_delta < 0:
         improving.append({"title": "Corrections", "detail": f"{corrections_delta:+d}", "tone": "healthy", "meta": "lower is better"})
@@ -247,6 +253,13 @@ def _summarize_engineering_loop(weekly: dict, monthly: dict) -> dict:
     if isinstance(mood_delta, (int, float)) and mood_delta > 0:
         improving.append({"title": "Mood", "detail": f"{mood_delta:+.3f}", "tone": "healthy", "meta": "vs previous window"})
 
+    duplicate_followup_rate_delta = trend.get("followup_duplicate_rate_delta")
+    if isinstance(duplicate_followup_rate_delta, (int, float)) and duplicate_followup_rate_delta > 0:
+        drifting.append({"title": "followup_duplicates", "detail": f"{duplicate_followup_rate_delta:+.1f}%", "tone": "critical" if duplicate_followup_rate_delta >= 5 else "watch", "meta": "open duplicate rate"})
+    learning_noise_rate_delta = trend.get("learning_noise_rate_delta")
+    if isinstance(learning_noise_rate_delta, (int, float)) and learning_noise_rate_delta > 0:
+        drifting.append({"title": "learning_noise", "detail": f"{learning_noise_rate_delta:+.1f}%", "tone": "critical" if learning_noise_rate_delta >= 5 else "watch", "meta": "active noise rate"})
+
     return {
         "weekly": weekly,
         "monthly": monthly,
@@ -256,6 +269,120 @@ def _summarize_engineering_loop(weekly: dict, monthly: dict) -> dict:
     }
 
 
+def _safe_json(value, default):
+    if value in (None, ""):
+        return default
+    if isinstance(value, (list, dict)):
+        return value
+    try:
+        return json.loads(value)
+    except Exception:
+        return default
+
+
+def _protocol_explainability_snapshot(limit: int = 20) -> dict:
+    db = _db()
+    conn = db.get_db()
+    max_limit = max(5, min(int(limit or 20), 100))
+
+    protocol_summary = db.protocol_compliance_summary(7)
+    recent_tasks = []
+    for row in conn.execute(
+        """SELECT * FROM protocol_tasks
+           ORDER BY opened_at DESC
+           LIMIT ?""",
+        (max_limit,),
+    ).fetchall():
+        item = dict(row)
+        for field in (
+            "files",
+            "plan",
+            "known_facts",
+            "unknowns",
+            "constraints",
+            "evidence_refs",
+            "response_reasons",
+        ):
+            item[field] = _safe_json(item.get(field), [])
+        item["has_evidence"] = bool(str(item.get("close_evidence") or "").strip())
+        item["guarded_open"] = bool(item.get("opened_with_guard") or item.get("opened_with_rules"))
+        recent_tasks.append(item)
+
+    recent_debts = [dict(row) for row in conn.execute(
+        """SELECT * FROM protocol_debt
+           ORDER BY created_at DESC
+           LIMIT ?""",
+        (max_limit,),
+    ).fetchall()]
+
+    debt_summary = {"open_total": 0, "by_severity": {}, "by_type": {}}
+    for debt in recent_debts:
+        if debt.get("status") != "open":
+            continue
+        debt_summary["open_total"] += 1
+        severity = str(debt.get("severity") or "warn")
+        debt_type = str(debt.get("debt_type") or "unknown")
+        debt_summary["by_severity"][severity] = debt_summary["by_severity"].get(severity, 0) + 1
+        debt_summary["by_type"][debt_type] = debt_summary["by_type"].get(debt_type, 0) + 1
+
+    recent_runs = db.list_workflow_runs(include_closed=True, limit=max_limit)
+    workflow_summary = {
+        "total": len(recent_runs),
+        "open_runs": sum(1 for run in recent_runs if run.get("status") not in {"completed", "failed", "cancelled"}),
+        "blocked_runs": sum(1 for run in recent_runs if run.get("status") == "blocked"),
+        "waiting_approval": sum(1 for run in recent_runs if run.get("status") == "waiting_approval"),
+    }
+
+    recent_goals = db.list_workflow_goals(include_closed=True, limit=max_limit)
+    goal_summary = {
+        "total": len(recent_goals),
+        "active": sum(1 for goal in recent_goals if goal.get("status") == "active"),
+        "blocked": sum(1 for goal in recent_goals if goal.get("status") == "blocked"),
+        "closed": sum(1 for goal in recent_goals if goal.get("status") in {"completed", "cancelled", "abandoned"}),
+    }
+
+    guard_checks = [dict(row) for row in conn.execute(
+        """SELECT area, files, learnings_returned, blocking_rules_returned, created_at
+           FROM guard_checks
+           ORDER BY created_at DESC
+           LIMIT ?""",
+        (max_limit,),
+    ).fetchall()]
+    areas = {}
+    blocking_hits = 0
+    for check in guard_checks:
+        area = str(check.get("area") or "unknown")
+        areas[area] = areas.get(area, 0) + 1
+        blocking_hits += int(check.get("blocking_rules_returned") or 0)
+
+    conditioned_learnings = [dict(row) for row in conn.execute(
+        """SELECT id, title, applies_to, priority, status, weight, guard_hits, updated_at
+           FROM learnings
+           WHERE status = 'active' AND applies_to IS NOT NULL AND TRIM(applies_to) != ''
+           ORDER BY COALESCE(guard_hits, 0) DESC, updated_at DESC
+           LIMIT ?""",
+        (max_limit,),
+    ).fetchall()]
+
+    return {
+        "protocol_summary": protocol_summary,
+        "debt_summary": debt_summary,
+        "recent_tasks": recent_tasks,
+        "recent_debts": recent_debts,
+        "workflow_summary": workflow_summary,
+        "recent_runs": recent_runs,
+        "goal_summary": goal_summary,
+        "recent_goals": recent_goals,
+        "guard_summary": {
+            "recent_checks": len(guard_checks),
+            "blocking_hits": blocking_hits,
+            "areas": areas,
+        },
+        "guard_checks": guard_checks,
+        "conditioned_learnings": conditioned_learnings,
+    }
+
+
 # ---------------------------------------------------------------------------
 # HTML page routes — Jinja2 with fallback to plain file
 # ---------------------------------------------------------------------------
@@ -321,6 +448,10 @@ async def page_trust():
 async def page_guard():
     return _render("guard.html")
 
+@app.get("/protocol", response_class=HTMLResponse)
+async def page_protocol():
+    return _render("protocol.html", snapshot=_protocol_explainability_snapshot())
+
 @app.get("/cortex", response_class=HTMLResponse)
 async def page_cortex():
     return _render("cortex.html")
@@ -1297,6 +1428,15 @@ async def api_trust_events(limit: int = Query(50, ge=1, le=200)):
     return {"events": [dict(r) for r in rows]}
 
 
+# ---------------------------------------------------------------------------
+# Protocol Explainability
+# ---------------------------------------------------------------------------
+
+@app.get("/api/protocol")
+async def api_protocol(limit: int = Query(20, ge=5, le=100)):
+    return _protocol_explainability_snapshot(limit=limit)
+
+
 # ---------------------------------------------------------------------------
 # Guard Heatmap
 # ---------------------------------------------------------------------------

package/src/dashboard/templates/base.html

@@ -162,6 +162,10 @@
             <svg class="w-4 h-4 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M3.055 11H5a2 2 0 012 2v1a2 2 0 002 2 2 2 0 012 2v2.945M8 3.935V5.5A2.5 2.5 0 0010.5 8h.5a2 2 0 012 2 2 2 0 104 0 2 2 0 012-2h1.064M15 20.488V18a2 2 0 012-2h3.064M21 12a9 9 0 11-18 0 9 9 0 0118 0z"/></svg>
             Guard Heatmap
           </a>
+          <a href="/protocol" class="nav-item flex items-center gap-2.5 px-3 py-1.5 rounded-md text-xs text-slate-400 transition-colors" data-page="protocol">
+            <svg class="w-4 h-4 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M9 12h6m-6 4h6M7 4h10a2 2 0 012 2v12a2 2 0 01-2 2H7a2 2 0 01-2-2V6a2 2 0 012-2z"/></svg>
+            Protocol Explainability
+          </a>
           <a href="/cortex" class="nav-item flex items-center gap-2.5 px-3 py-1.5 rounded-md text-xs text-slate-400 transition-colors" data-page="cortex">
             <svg class="w-4 h-4 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z"/><path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M2.458 12C3.732 7.943 7.523 5 12 5c4.478 0 8.268 2.943 9.542 7-1.274 4.057-5.064 7-9.542 7-4.477 0-8.268-2.943-9.542-7z"/></svg>
             Cortex Monitor

package/src/dashboard/templates/protocol.html

@@ -0,0 +1,199 @@
+{% extends "base.html" %}
+
+{% block title %}Protocol Explainability{% endblock %}
+
+{% block page_title %}Protocol Explainability{% endblock %}
+{% block page_subtitle %}
+<span class="text-xs text-slate-500 ml-2">Why the runtime acted, blocked, drifted, or asked for evidence</span>
+{% endblock %}
+
+{% block header_actions %}
+<a href="/api/protocol" class="text-xs text-slate-400 hover:text-slate-200 transition-colors px-2 py-1 rounded hover:bg-slate-800 font-mono">
+  /api/protocol
+</a>
+{% endblock %}
+
+{% block content %}
+{% set compliance = snapshot.protocol_summary or {} %}
+{% set overall = compliance.overall_compliance_pct or 0 %}
+{% set debt = snapshot.debt_summary or {} %}
+{% set workflow = snapshot.workflow_summary or {} %}
+{% set goals = snapshot.goal_summary or {} %}
+{% set conditioned = snapshot.conditioned_learnings or [] %}
+
+<div class="grid grid-cols-5 gap-4 mb-6">
+  <div class="bg-slate-900/50 border border-slate-800/50 rounded-xl p-5 card">
+    <p class="text-xs uppercase tracking-wider text-slate-500 font-semibold mb-1">Compliance 7d</p>
+    <p class="text-2xl font-display font-bold {{ 'text-emerald-400' if overall >= 80 else 'text-amber-400' if overall >= 60 else 'text-red-400' }}">{{ "%.1f"|format(overall) }}%</p>
+  </div>
+  <div class="bg-slate-900/50 border border-slate-800/50 rounded-xl p-5 card">
+    <p class="text-xs uppercase tracking-wider text-slate-500 font-semibold mb-1">Open Debt</p>
+    <p class="text-2xl font-display font-bold {{ 'text-emerald-400' if (debt.open_total or 0) == 0 else 'text-red-400' }}">{{ debt.open_total or 0 }}</p>
+  </div>
+  <div class="bg-slate-900/50 border border-slate-800/50 rounded-xl p-5 card">
+    <p class="text-xs uppercase tracking-wider text-slate-500 font-semibold mb-1">Open Runs</p>
+    <p class="text-2xl font-display font-bold text-slate-100">{{ workflow.open_runs or 0 }}</p>
+  </div>
+  <div class="bg-slate-900/50 border border-slate-800/50 rounded-xl p-5 card">
+    <p class="text-xs uppercase tracking-wider text-slate-500 font-semibold mb-1">Blocked Goals</p>
+    <p class="text-2xl font-display font-bold {{ 'text-red-400' if (goals.blocked or 0) else 'text-emerald-400' }}">{{ goals.blocked or 0 }}</p>
+  </div>
+  <div class="bg-slate-900/50 border border-slate-800/50 rounded-xl p-5 card">
+    <p class="text-xs uppercase tracking-wider text-slate-500 font-semibold mb-1">Conditioned Files</p>
+    <p class="text-2xl font-display font-bold text-nexo-400">{{ conditioned|length }}</p>
+  </div>
+</div>
+
+<div class="grid grid-cols-2 gap-5 mb-6">
+  <section class="bg-slate-900/50 border border-slate-800/50 rounded-xl p-5 card">
+    <h2 class="text-xs uppercase tracking-wider text-slate-500 font-semibold mb-4">Protocol Requirements</h2>
+    <div class="space-y-3">
+      {% for key, label in [('guard_check', 'Guard before action'), ('heartbeat', 'Heartbeat with context'), ('change_log', 'Change log after edits'), ('learning_capture', 'Learning capture after correction'), ('done_evidence', 'Evidence before done')] %}
+      {% set item = compliance.get(key, {}) %}
+      <div class="flex items-center justify-between gap-4">
+        <div>
+          <p class="text-sm text-slate-200">{{ label }}</p>
+          <p class="text-[11px] text-slate-500 font-mono">
+            {% if item.required is defined %}required {{ item.required }}{% endif %}
+            {% if item.total is defined %}total {{ item.total }}{% endif %}
+            {% if item.executed is defined %} • executed {{ item.executed }}{% endif %}
+            {% if item.logged is defined %} • logged {{ item.logged }}{% endif %}
+            {% if item.captured is defined %} • captured {{ item.captured }}{% endif %}
+            {% if item.done_tasks is defined %} • done {{ item.done_tasks }}{% endif %}
+          </p>
+        </div>
+        <span class="text-sm font-mono {{ 'text-emerald-400' if (item.compliance_pct or 0) >= 80 else 'text-amber-400' if (item.compliance_pct or 0) >= 60 else 'text-red-400' }}">
+          {{ "%.1f"|format(item.compliance_pct or 0) }}%
+        </span>
+      </div>
+      {% endfor %}
+    </div>
+  </section>
+
+  <section class="bg-slate-900/50 border border-slate-800/50 rounded-xl p-5 card">
+    <h2 class="text-xs uppercase tracking-wider text-slate-500 font-semibold mb-4">Debt Pressure</h2>
+    <div class="grid grid-cols-3 gap-3 mb-4">
+      {% for severity in ['error', 'warn', 'info'] %}
+      <div class="rounded-lg border border-slate-800/60 bg-slate-950/50 p-3">
+        <p class="text-[10px] uppercase tracking-wider text-slate-500">{{ severity }}</p>
+        <p class="text-xl font-display font-bold text-slate-100">{{ debt.by_severity.get(severity, 0) }}</p>
+      </div>
+      {% endfor %}
+    </div>
+    <div class="space-y-2 max-h-56 overflow-y-auto pr-1">
+      {% for item in snapshot.recent_debts[:10] %}
+      <div class="rounded-lg border border-slate-800/60 bg-slate-950/50 p-3">
+        <div class="flex items-center justify-between gap-3 mb-1">
+          <span class="text-xs font-semibold {{ 'text-red-400' if item.severity == 'error' else 'text-amber-400' if item.severity == 'warn' else 'text-slate-400' }}">{{ item.debt_type }}</span>
+          <span class="text-[10px] text-slate-500 font-mono">{{ item.status }}</span>
+        </div>
+        <p class="text-xs text-slate-300">{{ item.evidence or 'No evidence summary recorded.' }}</p>
+      </div>
+      {% else %}
+      <p class="text-sm text-slate-500">No protocol debt recorded.</p>
+      {% endfor %}
+    </div>
+  </section>
+</div>
+
+<div class="grid grid-cols-2 gap-5 mb-6">
+  <section class="bg-slate-900/50 border border-slate-800/50 rounded-xl p-5 card">
+    <h2 class="text-xs uppercase tracking-wider text-slate-500 font-semibold mb-4">Recent Protocol Tasks</h2>
+    <div class="space-y-3 max-h-[420px] overflow-y-auto pr-1">
+      {% for item in snapshot.recent_tasks[:12] %}
+      <div class="rounded-lg border border-slate-800/60 bg-slate-950/50 p-3">
+        <div class="flex items-center justify-between gap-3 mb-1">
+          <p class="text-sm text-slate-100">{{ item.goal }}</p>
+          <span class="text-[10px] font-mono px-2 py-0.5 rounded bg-slate-800 text-slate-400">{{ item.status }}</span>
+        </div>
+        <p class="text-[11px] text-slate-500 font-mono mb-2">{{ item.task_type }} • cortex={{ item.cortex_mode or 'n/a' }} • response={{ item.response_mode or 'n/a' }}</p>
+        <div class="flex flex-wrap gap-2 text-[10px]">
+          {% if item.guarded_open %}<span class="px-2 py-0.5 rounded bg-nexo-500/15 text-nexo-300">guarded open</span>{% endif %}
+          {% if item.must_verify %}<span class="px-2 py-0.5 rounded bg-amber-500/15 text-amber-300">must verify</span>{% endif %}
+          {% if item.must_change_log %}<span class="px-2 py-0.5 rounded bg-blue-500/15 text-blue-300">must change-log</span>{% endif %}
+          {% if item.has_evidence %}<span class="px-2 py-0.5 rounded bg-emerald-500/15 text-emerald-300">evidence attached</span>{% endif %}
+          {% if item.guard_has_blocking %}<span class="px-2 py-0.5 rounded bg-red-500/15 text-red-300">blocking risk</span>{% endif %}
+        </div>
+      </div>
+      {% else %}
+      <p class="text-sm text-slate-500">No protocol tasks yet.</p>
+      {% endfor %}
+    </div>
+  </section>
+
+  <section class="bg-slate-900/50 border border-slate-800/50 rounded-xl p-5 card">
+    <h2 class="text-xs uppercase tracking-wider text-slate-500 font-semibold mb-4">Durable Workflow State</h2>
+    <div class="grid grid-cols-3 gap-3 mb-4">
+      <div class="rounded-lg border border-slate-800/60 bg-slate-950/50 p-3">
+        <p class="text-[10px] uppercase tracking-wider text-slate-500">Open Runs</p>
+        <p class="text-xl font-display font-bold text-slate-100">{{ workflow.open_runs or 0 }}</p>
+      </div>
+      <div class="rounded-lg border border-slate-800/60 bg-slate-950/50 p-3">
+        <p class="text-[10px] uppercase tracking-wider text-slate-500">Blocked Runs</p>
+        <p class="text-xl font-display font-bold {{ 'text-red-400' if (workflow.blocked_runs or 0) else 'text-slate-100' }}">{{ workflow.blocked_runs or 0 }}</p>
+      </div>
+      <div class="rounded-lg border border-slate-800/60 bg-slate-950/50 p-3">
+        <p class="text-[10px] uppercase tracking-wider text-slate-500">Waiting Approval</p>
+        <p class="text-xl font-display font-bold {{ 'text-amber-400' if (workflow.waiting_approval or 0) else 'text-slate-100' }}">{{ workflow.waiting_approval or 0 }}</p>
+      </div>
+    </div>
+    <div class="space-y-3 max-h-[420px] overflow-y-auto pr-1">
+      {% for item in snapshot.recent_runs[:10] %}
+      <div class="rounded-lg border border-slate-800/60 bg-slate-950/50 p-3">
+        <div class="flex items-center justify-between gap-3 mb-1">
+          <p class="text-sm text-slate-100">{{ item.goal }}</p>
+          <span class="text-[10px] font-mono px-2 py-0.5 rounded bg-slate-800 text-slate-400">{{ item.status }}</span>
+        </div>
+        <p class="text-[11px] text-slate-500 font-mono">{{ item.workflow_kind }}{% if item.current_step_key %} • step={{ item.current_step_key }}{% endif %}{% if item.next_action %} • next={{ item.next_action }}{% endif %}</p>
+      </div>
+      {% else %}
+      <p class="text-sm text-slate-500">No workflow runs recorded.</p>
+      {% endfor %}
+    </div>
+  </section>
+</div>
+
+<div class="grid grid-cols-2 gap-5">
+  <section class="bg-slate-900/50 border border-slate-800/50 rounded-xl p-5 card">
+    <h2 class="text-xs uppercase tracking-wider text-slate-500 font-semibold mb-4">Conditioned Learnings</h2>
+    <div class="space-y-3 max-h-[420px] overflow-y-auto pr-1">
+      {% for item in conditioned[:12] %}
+      <div class="rounded-lg border border-slate-800/60 bg-slate-950/50 p-3">
+        <div class="flex items-center justify-between gap-3 mb-1">
+          <p class="text-sm text-slate-100">{{ item.title }}</p>
+          <span class="text-[10px] font-mono px-2 py-0.5 rounded bg-slate-800 text-slate-400">{{ item.priority or 'normal' }}</span>
+        </div>
+        <p class="text-xs text-slate-400 break-all">{{ item.applies_to }}</p>
+        <p class="text-[11px] text-slate-500 font-mono mt-1">guard_hits={{ item.guard_hits or 0 }} • weight={{ "%.2f"|format(item.weight or 0) }}</p>
+      </div>
+      {% else %}
+      <p class="text-sm text-slate-500">No conditioned learnings active.</p>
+      {% endfor %}
+    </div>
+  </section>
+
+  <section class="bg-slate-900/50 border border-slate-800/50 rounded-xl p-5 card">
+    <h2 class="text-xs uppercase tracking-wider text-slate-500 font-semibold mb-4">Guard Pressure</h2>
+    <div class="grid grid-cols-2 gap-3 mb-4">
+      <div class="rounded-lg border border-slate-800/60 bg-slate-950/50 p-3">
+        <p class="text-[10px] uppercase tracking-wider text-slate-500">Recent Checks</p>
+        <p class="text-xl font-display font-bold text-slate-100">{{ snapshot.guard_summary.recent_checks or 0 }}</p>
+      </div>
+      <div class="rounded-lg border border-slate-800/60 bg-slate-950/50 p-3">
+        <p class="text-[10px] uppercase tracking-wider text-slate-500">Blocking Hits</p>
+        <p class="text-xl font-display font-bold {{ 'text-red-400' if (snapshot.guard_summary.blocking_hits or 0) else 'text-slate-100' }}">{{ snapshot.guard_summary.blocking_hits or 0 }}</p>
+      </div>
+    </div>
+    <div class="space-y-2">
+      {% for area, count in snapshot.guard_summary.areas.items() %}
+      <div class="flex items-center justify-between rounded-lg border border-slate-800/60 bg-slate-950/50 px-3 py-2">
+        <span class="text-sm text-slate-300">{{ area }}</span>
+        <span class="text-xs font-mono text-slate-500">{{ count }} checks</span>
+      </div>
+      {% else %}
+      <p class="text-sm text-slate-500">No guard pressure recorded.</p>
+      {% endfor %}
+    </div>
+  </section>
+</div>
+{% endblock %}

package/src/db/__init__.py

@@ -44,7 +44,7 @@ from db._reminders import (
 
 # Learnings
 from db._learnings import (
-    create_learning, update_learning, delete_learning,
+    create_learning, update_learning, supersede_learning, delete_learning,
     search_learnings, list_learnings,
     extract_keywords, find_similar_learnings,
 )
@@ -93,6 +93,28 @@ from db._cron_runs import (
     cron_run_start, cron_run_end, cron_runs_recent, cron_runs_summary,
 )
 
+# Protocol discipline runtime
+from db._protocol import (
+    create_protocol_task, get_protocol_task, close_protocol_task,
+    create_protocol_debt, resolve_protocol_debts, list_protocol_debts,
+    protocol_compliance_summary,
+)
+
+# Durable workflow runtime
+from db._workflow import (
+    create_workflow_run, get_workflow_run, list_workflow_runs,
+    list_workflow_steps, record_workflow_transition,
+    get_workflow_replay, get_workflow_resume_state,
+    create_workflow_goal, get_workflow_goal, list_workflow_goals,
+    update_workflow_goal,
+)
+
+# State watchers
+from db._watchers import (
+    create_state_watcher, get_state_watcher, list_state_watchers,
+    update_state_watcher, update_state_watcher_result,
+)
+
 # Personal scripts registry
 from db._personal_scripts import (
     upsert_personal_script, list_personal_scripts, get_personal_script,

package/src/db/_learnings.py

@@ -13,6 +13,7 @@ def create_learning(
     reasoning: str = '',
     prevention: str = '',
     applies_to: str = '',
+    supersedes_id: int | None = None,
     status: str = 'active',
     review_due_at: float | None = None,
     last_reviewed_at: float | None = None,
@@ -22,11 +23,11 @@ def create_learning(
     now = now_epoch()
     cursor = conn.execute(
         "INSERT INTO learnings "
-        "(category, title, content, reasoning, prevention, applies_to, status, review_due_at, last_reviewed_at, created_at, updated_at) "
-        "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        "(category, title, content, reasoning, prevention, applies_to, supersedes_id, status, review_due_at, last_reviewed_at, created_at, updated_at) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
         (
             category, title, content, reasoning, prevention, applies_to,
-            status, review_due_at, last_reviewed_at, now, now,
+            supersedes_id, status, review_due_at, last_reviewed_at, now, now,
         )
     )
     conn.commit()
@@ -60,6 +61,33 @@ def update_learning(id: int, **kwargs) -> dict:
     return r
 
 
+def supersede_learning(old_id: int, new_id: int, note: str = '') -> dict:
+    """Mark an older learning as superseded by a newer canonical learning."""
+    conn = get_db()
+    old_row = conn.execute("SELECT * FROM learnings WHERE id = ?", (old_id,)).fetchone()
+    new_row = conn.execute("SELECT * FROM learnings WHERE id = ?", (new_id,)).fetchone()
+    if not old_row:
+        return {"error": f"Learning {old_id} not found"}
+    if not new_row:
+        return {"error": f"Learning {new_id} not found"}
+
+    old_reasoning = str(old_row["reasoning"] or "")
+    suffix = note.strip() if note.strip() else f"Superseded by learning #{new_id}."
+    combined_reasoning = f"{old_reasoning}\n{suffix}".strip() if old_reasoning else suffix
+    updated_at = now_epoch()
+    conn.execute(
+        "UPDATE learnings SET status = 'superseded', updated_at = ?, reasoning = ? WHERE id = ?",
+        (updated_at, combined_reasoning, old_id),
+    )
+    conn.execute(
+        "UPDATE learnings SET supersedes_id = ?, updated_at = ? WHERE id = ?",
+        (old_id, updated_at, new_id),
+    )
+    conn.commit()
+    row = conn.execute("SELECT * FROM learnings WHERE id = ?", (old_id,)).fetchone()
+    return dict(row)
+
+
 def delete_learning(id: int) -> bool:
     """Delete a learning entry."""
     conn = get_db()
@@ -166,4 +194,3 @@ def find_similar_learnings(new_id: int, title: str, content: str, category: str)
     results.sort(key=lambda x: x[1], reverse=True)
     return results[:5]
 
-

package/src/db/_personal_scripts.py

@@ -517,6 +517,18 @@ def get_personal_script_health_report(*, fix: bool = False) -> dict:
 
     for schedule in audit.get("schedules", []):
         checked += 1
+        if schedule.get("schedule_managed") and schedule.get("schedule_type") == "keep_alive":
+            runtime_state = str(schedule.get("runtime_state", "") or "")
+            runtime_summary = str(schedule.get("runtime_summary", "") or runtime_state or "runtime issue")
+            if runtime_state in {"degraded", "stale", "duplicated"}:
+                severity = "error" if runtime_state == "duplicated" else "warn"
+                issues.append({
+                    "script_id": schedule.get("script_name") or schedule.get("script_path") or schedule.get("cron_id"),
+                    "severity": severity,
+                    "message": (
+                        f"keep_alive runtime {schedule['cron_id']}: {runtime_summary}"
+                    ),
+                })
         if schedule.get("schedule_managed"):
             continue