nexo-brain 5.3.10 → 5.3.12

package/src/hook_guardrails.py

@@ -14,6 +14,21 @@ from protocol_settings import get_protocol_strictness
 READ_LIKE_TOOLS = {"Read"}
 WRITE_LIKE_TOOLS = {"Edit", "MultiEdit", "Write"}
 DELETE_LIKE_TOOLS = {"Delete"}
+NON_TRIVIAL_PROTOCOL_TOOLS = {"Read", "Bash", "Grep", "Glob", "Edit", "MultiEdit", "Write", "Delete"}
+PROTOCOL_SKIP_TOOLS = {
+    "nexo_startup",
+    "nexo_smart_startup",
+    "nexo_stop",
+    "nexo_heartbeat",
+    "nexo_task_open",
+    "nexo_task_close",
+    "nexo_workflow_open",
+    "nexo_workflow_update",
+    "nexo_guard_check",
+    "nexo_guard_file_check",
+    "nexo_rules_check",
+}
+ACTION_TASK_TYPES = {"edit", "execute", "delegate"}
 NEXO_CODE_ROOT = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent))).expanduser().resolve()
 LIVE_REPO_ROOT = NEXO_CODE_ROOT.parent if NEXO_CODE_ROOT.name == "src" else NEXO_CODE_ROOT
 PUBLIC_REPO_DIRS = {
@@ -50,6 +65,11 @@ def _operation_kind(tool_name: str) -> str:
     return "other"
 
 
+def _short_tool_name(tool_name: str) -> str:
+    clean = str(tool_name or "").strip()
+    return clean.rsplit("__", 1)[-1] if "__" in clean else clean
+
+
 def _normalize_file_path(path: str) -> str:
     return _normalize_path_token(str(Path(path)))
 
@@ -154,7 +174,8 @@ def _resolve_nexo_sid(conn, external_session_id: str) -> str:
 def _find_open_task_for_file(conn, sid: str, filepath: str) -> dict | None:
     target = _normalize_file_path(filepath)
     rows = conn.execute(
-        """SELECT task_id, files, guard_has_blocking
+        """SELECT task_id, files, guard_has_blocking, task_type, plan, unknowns,
+                  verification_step, opened_with_guard, must_change_log, must_verify
            FROM protocol_tasks
            WHERE session_id = ? AND status = 'open'
            ORDER BY opened_at DESC""",
@@ -173,7 +194,8 @@ def _find_open_task_for_file(conn, sid: str, filepath: str) -> dict | None:
 
 def _find_any_open_task(conn, sid: str) -> dict | None:
     row = conn.execute(
-        """SELECT task_id, files, guard_has_blocking
+        """SELECT task_id, files, guard_has_blocking, task_type, plan, unknowns,
+                  verification_step, opened_with_guard, must_change_log, must_verify
            FROM protocol_tasks
            WHERE session_id = ? AND status = 'open'
            ORDER BY opened_at DESC
@@ -183,6 +205,26 @@ def _find_any_open_task(conn, sid: str) -> dict | None:
     return dict(row) if row else None
 
 
+def _find_any_open_workflow(conn, sid: str) -> dict | None:
+    row = conn.execute(
+        """SELECT run_id, protocol_task_id, current_step_key
+           FROM workflow_runs
+           WHERE session_id = ? AND status IN ('open', 'running', 'blocked', 'waiting_approval')
+           ORDER BY updated_at DESC, run_id DESC
+           LIMIT 1""",
+        (sid,),
+    ).fetchone()
+    return dict(row) if row else None
+
+
+def _session_has_guard_check(conn, sid: str) -> bool:
+    row = conn.execute(
+        "SELECT 1 FROM guard_checks WHERE session_id = ? LIMIT 1",
+        (sid,),
+    ).fetchone()
+    return bool(row)
+
+
 def _find_open_debt(conn, *, session_id: str, task_id: str, debt_type: str, file_token: str) -> dict | None:
     row = conn.execute(
         """SELECT *
@@ -241,6 +283,98 @@ def _ensure_protocol_debt(
     )
 
 
+def _task_list_field(task: dict | None, key: str) -> list:
+    if not task:
+        return []
+    try:
+        parsed = json.loads(task.get(key) or "[]")
+    except Exception:
+        return []
+    return parsed if isinstance(parsed, list) else []
+
+
+def _task_needs_workflow(task: dict | None) -> bool:
+    if not task:
+        return False
+    if str(task.get("task_type") or "").strip() not in ACTION_TASK_TYPES:
+        return False
+    if len(_task_list_field(task, "plan")) > 1:
+        return True
+    if len(_task_list_field(task, "unknowns")) > 0:
+        return True
+    if len(_task_list_field(task, "files")) > 1:
+        return True
+    return bool(str(task.get("verification_step") or "").strip())
+
+
+def _append_protocol_warning(warnings: list[dict], message: str) -> None:
+    clean = (message or "").strip()
+    if not clean:
+        return
+    if any((item.get("message") or "").strip() == clean for item in warnings):
+        return
+    warnings.append({"message": clean})
+
+
+def _collect_protocol_warnings(conn, *, sid: str, tool_name: str) -> list[dict]:
+    short_name = _short_tool_name(tool_name)
+    if short_name in PROTOCOL_SKIP_TOOLS or short_name not in NON_TRIVIAL_PROTOCOL_TOOLS:
+        return []
+
+    warnings: list[dict] = []
+    if not sid:
+        _append_protocol_warning(
+            warnings,
+            "Trabajo no trivial detectado antes de `nexo_startup(...)`. Arranca NEXO, abre `nexo_task_open(...)`, y si esto va a durar varias fases abre también `nexo_workflow_open(...)` antes de seguir.",
+        )
+        return warnings
+
+    task = _find_any_open_task(conn, sid)
+    has_guard = _session_has_guard_check(conn, sid)
+    if not task:
+        guard_note = (
+            " Ejecuta `nexo_guard_check(...)` antes de leer código condicionado o compartido."
+            if short_name in {"Read", "Bash", "Grep", "Glob"} and not has_guard
+            else ""
+        )
+        _append_protocol_warning(
+            warnings,
+            "Trabajo no trivial detectado sin `nexo_task_open(...)`. Ábrelo ahora y, si esto va a cruzar varios pasos o mensajes, añade `nexo_workflow_open(...)`." + guard_note,
+        )
+        _append_protocol_warning(
+            warnings,
+            "Recordatorio protocolario: mantén `nexo_heartbeat(...)` al día y no cierres en optimista; si hay cambios reales, registra `nexo_change_log(...)` o cierra con `nexo_task_close(...)` más evidencia.",
+        )
+        return warnings
+
+    task_id = str(task.get("task_id") or "").strip()
+    if str(task.get("task_type") or "").strip() in ACTION_TASK_TYPES and not (task.get("opened_with_guard") or has_guard):
+        _append_protocol_warning(
+            warnings,
+            f"La tarea {task_id} está activa sin guard visible. Ejecuta `nexo_guard_check(...)` antes de tocar código condicionado o compartido.",
+        )
+
+    workflow = _find_any_open_workflow(conn, sid)
+    if _task_needs_workflow(task) and not workflow:
+        _append_protocol_warning(
+            warnings,
+            f"La tarea {task_id} ya tiene pinta de multi-step y sigue sin `nexo_workflow_open(...)`. Ábrelo para que checkpoints, resume y replay no dependan de memoria implícita.",
+        )
+
+    if str(task.get("task_type") or "").strip() in ACTION_TASK_TYPES and short_name in {"Bash", "Edit", "MultiEdit", "Write", "Delete"}:
+        change_note = (
+            " Si editas de verdad y no vas a usar `nexo_task_close(...)` inmediatamente, captura `nexo_change_log(...)`."
+            if task.get("must_change_log")
+            else ""
+        )
+        _append_protocol_warning(
+            warnings,
+            f"Recordatorio protocolario para {task_id}: mantén `nexo_heartbeat(...)` al día y ciérrala con `nexo_task_close(...)` más evidencia antes de decir que está resuelta.{change_note}",
+        )
+
+    return warnings
+
+
 def _collect_automation_live_repo_blocks(
     conn,
     *,
@@ -429,21 +563,20 @@ def process_pre_tool_event(payload: dict) -> dict:
 def process_tool_event(payload: dict) -> dict:
     tool_name = str(payload.get("tool_name", "")).strip()
     op = _operation_kind(tool_name)
-    if op == "other":
-        return {"ok": True, "skipped": True, "reason": "tool not monitored"}
-
     tool_input = payload.get("tool_input")
     files = _extract_touched_files(tool_input)
-    if not files:
-        return {"ok": True, "skipped": True, "reason": "no touched files found"}
-
     conn = get_db()
     sid = _resolve_nexo_sid(conn, str(payload.get("session_id", "")))
-    if not sid:
+    warnings = _collect_protocol_warnings(conn, sid=sid, tool_name=tool_name)
+
+    if op == "other" and not warnings:
+        return {"ok": True, "skipped": True, "reason": "tool not monitored"}
+    if not files and op in {"read", "write", "delete"} and not warnings:
+        return {"ok": True, "skipped": True, "reason": "no touched files found"}
+    if not sid and not warnings:
         return {"ok": True, "skipped": True, "reason": "session not mapped to nexo"}
 
-    conditioned = _load_conditioned_learnings(conn, files)
-    warnings: list[dict] = []
+    conditioned = _load_conditioned_learnings(conn, files) if sid else {}
     violations: list[dict] = []
 
     for filepath in files:
@@ -545,6 +678,9 @@ def format_hook_message(result: dict) -> str:
         return ""
     lines = ["NEXO DISCIPLINE:"]
     for item in result.get("warnings", []):
+        if item.get("message") and not item.get("learning_ids"):
+            lines.append(f"- PROTOCOL REMINDER: {item['message']}")
+            continue
         if item.get("debt_id"):
             lines.append(
                 f"- REVIEW FILE RULES: {item['file']} -> learnings {item['learning_ids']}. "

package/src/plugins/cortex.py

@@ -22,6 +22,8 @@ import time
 from datetime import datetime, timedelta
 from pathlib import Path
 
+from db import VALID_IMPACT_LEVELS, VALID_TASK_TYPES, validate_impact_level, validate_task_type
+
 
 def _get_db():
     from db import get_db
@@ -734,9 +736,19 @@ def handle_cortex_check(
     Returns:
         Mode (ask/propose/act), available tools, warnings, and relevant Core Rules
     """
+    try:
+        clean_type = validate_task_type(task_type)
+    except ValueError as exc:
+        return "\n".join(
+            [
+                f"ERROR: {exc}",
+                f"Valid task types: {', '.join(sorted(VALID_TASK_TYPES))}",
+            ]
+        )
+
     state = {
         "goal": goal.strip() if goal else "",
-        "task_type": task_type if task_type in ("answer", "analyze", "edit", "execute", "delegate") else "answer",
+        "task_type": clean_type,
         "plan": _parse_json_list(plan),
         "known_facts": _parse_json_list(known_facts),
         "unknowns": _parse_json_list(unknowns),
@@ -860,8 +872,30 @@ def handle_cortex_decide(
             indent=2,
         )
 
-    clean_type = task_type if task_type in {"answer", "analyze", "edit", "execute", "delegate"} else "execute"
-    clean_level = impact_level if impact_level in {"medium", "high", "critical"} else "high"
+    try:
+        clean_type = validate_task_type(task_type)
+    except ValueError as exc:
+        return json.dumps(
+            {
+                "ok": False,
+                "error": str(exc),
+                "valid_task_types": sorted(VALID_TASK_TYPES),
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    try:
+        clean_level = validate_impact_level(impact_level)
+    except ValueError as exc:
+        return json.dumps(
+            {
+                "ok": False,
+                "error": str(exc),
+                "valid_impact_levels": sorted(VALID_IMPACT_LEVELS),
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
     parsed_constraints = _parse_json_list(constraints)
     parsed_evidence = _parse_json_list(evidence_refs)
     try:

package/src/plugins/doctor.py

@@ -11,13 +11,14 @@ if str(SRC_DIR) not in sys.path:
     sys.path.insert(0, str(SRC_DIR))
 
 
-def handle_doctor(tier: str = "boot", fix: bool = False, output: str = "text") -> str:
+def handle_doctor(tier: str = "boot", fix: bool = False, output: str = "text", plane: str = "") -> str:
     """Unified diagnostic report for boot/runtime/deep health.
 
     Args:
         tier: Diagnostic tier — boot, runtime, deep, or all (default: boot)
         fix: Apply deterministic fixes (default: False)
         output: Output format — text or json (default: text)
+        plane: Diagnostic plane — runtime_personal, installation_live, or database_real
     """
     from doctor.orchestrator import run_doctor
     from doctor.formatters import format_report
@@ -27,7 +28,7 @@ def handle_doctor(tier: str = "boot", fix: bool = False, output: str = "text") -
     if output not in ("text", "json"):
         return f"Invalid output '{output}'. Use: text, json"
 
-    report = run_doctor(tier=tier, fix=fix)
+    report = run_doctor(tier=tier, fix=fix, plane=plane)
     return format_report(report, fmt=output)
 
 

package/src/plugins/protocol.py

@@ -10,6 +10,8 @@ import secrets
 import time
 
 from db import (
+    VALID_TASK_TYPES,
+    VALID_CLOSE_OUTCOMES,
     close_protocol_task,
     create_followup,
     latest_cortex_evaluation_for_task,
@@ -28,6 +30,8 @@ from db import (
     resolve_protocol_debts,
     search_learnings,
     task_has_cortex_evaluation,
+    validate_close_outcome,
+    validate_task_type,
 )
 from plugins.cortex import evaluate_cortex_state
 from plugins.guard import handle_guard_check
@@ -651,7 +655,18 @@ def handle_confidence_check(
     clean_goal = (goal or "").strip()
     if not clean_goal:
         return json.dumps({"ok": False, "error": "goal is required"}, ensure_ascii=False, indent=2)
-    clean_type = task_type if task_type in {"answer", "analyze", "edit", "execute", "delegate"} else "answer"
+    try:
+        clean_type = validate_task_type(task_type)
+    except ValueError as exc:
+        return json.dumps(
+            {
+                "ok": False,
+                "error": str(exc),
+                "valid_task_types": sorted(VALID_TASK_TYPES),
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
     result = evaluate_response_confidence(
         goal=clean_goal,
         task_type=clean_type,
@@ -693,7 +708,18 @@ def handle_task_open(
     if not clean_goal:
         return json.dumps({"ok": False, "error": "goal is required"}, ensure_ascii=False, indent=2)
 
-    clean_type = task_type if task_type in {"answer", "analyze", "edit", "execute", "delegate"} else "answer"
+    try:
+        clean_type = validate_task_type(task_type)
+    except ValueError as exc:
+        return json.dumps(
+            {
+                "ok": False,
+                "error": str(exc),
+                "valid_task_types": sorted(VALID_TASK_TYPES),
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
     files_list = _parse_list(files)
     protocol_strictness = get_protocol_strictness()
     if protocol_strictness in {"strict", "learning"} and clean_type == "edit" and not files_list:
@@ -949,7 +975,19 @@ def handle_task_close(
             indent=2,
         )
 
-    clean_outcome = outcome if outcome in {"done", "partial", "blocked", "failed", "cancelled"} else "failed"
+    try:
+        clean_outcome = validate_close_outcome(outcome)
+    except ValueError as exc:
+        return json.dumps(
+            {
+                "ok": False,
+                "error": str(exc),
+                "task_id": task_id,
+                "valid_outcomes": sorted(VALID_CLOSE_OUTCOMES),
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
     clean_evidence = (evidence or "").strip()
     files_changed_list = _parse_list(files_changed)
     planned_files = _parse_list(task.get("files") or "[]")

package/src/plugins/schedule.py

@@ -20,6 +20,9 @@ from script_registry import (
     get_declared_schedule,
 )
 
+LEGACY_BACKUP_CRON_ID = "backup"
+LEGACY_BACKUP_SUMMARY = "legacy backup file evidence"
+
 
 def handle_schedule_status(hours: int = 24, cron_id: str = '') -> str:
     """Show cron execution status — what ran, what failed, durations.
@@ -30,6 +33,8 @@ def handle_schedule_status(hours: int = 24, cron_id: str = '') -> str:
     """
     if cron_id:
         runs = cron_runs_recent(hours, cron_id)
+        if cron_id == LEGACY_BACKUP_CRON_ID:
+            runs = _select_backup_runs(runs, hours)
         if not runs:
             return f"No runs for '{cron_id}' in the last {hours}h."
         schedule_meta = get_personal_script_schedule(cron_id) or {}
@@ -53,7 +58,7 @@ def handle_schedule_status(hours: int = 24, cron_id: str = '') -> str:
         return "\n".join(lines)
 
     # Summary view — one line per cron
-    summary = cron_runs_summary(hours)
+    summary = _merge_legacy_summaries(cron_runs_summary(hours), hours)
     if not summary:
         return f"No cron executions recorded in the last {hours}h."
 
@@ -82,6 +87,119 @@ def handle_schedule_status(hours: int = 24, cron_id: str = '') -> str:
     return "\n".join(lines)
 
 
+def _select_backup_runs(db_runs: list[dict], hours: int) -> list[dict]:
+    legacy_runs = _legacy_backup_runs(hours)
+    if _prefer_legacy_over_db(db_runs, legacy_runs):
+        return legacy_runs
+    return db_runs
+
+
+def _merge_legacy_summaries(summary_rows: list[dict], hours: int) -> list[dict]:
+    rows = [dict(row) for row in (summary_rows or [])]
+    legacy_summary = _legacy_backup_summary(hours)
+    if not legacy_summary:
+        return rows
+    by_cron_id = {row["cron_id"]: row for row in rows}
+    existing = by_cron_id.get(LEGACY_BACKUP_CRON_ID)
+    if _prefer_legacy_summary(existing, legacy_summary):
+        by_cron_id[LEGACY_BACKUP_CRON_ID] = legacy_summary
+    return sorted(
+        by_cron_id.values(),
+        key=lambda row: row.get("last_run") or "",
+        reverse=True,
+    )
+
+
+def _prefer_legacy_over_db(db_runs: list[dict], legacy_runs: list[dict]) -> bool:
+    if not legacy_runs:
+        return False
+    if not db_runs:
+        return True
+    latest_db = _parse_db_timestamp(db_runs[0].get("started_at"))
+    latest_legacy = _parse_db_timestamp(legacy_runs[0].get("started_at"))
+    if latest_legacy is None:
+        return False
+    if latest_db is None:
+        return True
+    return latest_legacy > latest_db
+
+
+def _prefer_legacy_summary(existing: dict | None, legacy: dict) -> bool:
+    if not legacy:
+        return False
+    if not existing:
+        return True
+    latest_existing = _parse_db_timestamp(existing.get("last_run"))
+    latest_legacy = _parse_db_timestamp(legacy.get("last_run"))
+    if latest_legacy is None:
+        return False
+    if latest_existing is None:
+        return True
+    return latest_legacy > latest_existing
+
+
+def _legacy_backup_summary(hours: int) -> dict | None:
+    runs = _legacy_backup_runs(hours)
+    if not runs:
+        return None
+    return _build_summary_from_runs(LEGACY_BACKUP_CRON_ID, runs)
+
+
+def _legacy_backup_runs(hours: int) -> list[dict]:
+    nexo_home = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+    backup_dir = nexo_home / "backups"
+    if not backup_dir.exists():
+        return []
+    cutoff = _now_utc().timestamp() - (hours * 3600)
+    runs: list[dict] = []
+    for backup_file in backup_dir.glob("nexo-*.db"):
+        try:
+            stat = backup_file.stat()
+        except OSError:
+            continue
+        if stat.st_mtime < cutoff:
+            continue
+        started = datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc).replace(microsecond=0)
+        started_at = started.strftime("%Y-%m-%d %H:%M:%S")
+        runs.append(
+            {
+                "cron_id": LEGACY_BACKUP_CRON_ID,
+                "started_at": started_at,
+                "ended_at": started_at,
+                "exit_code": 0,
+                "summary": LEGACY_BACKUP_SUMMARY,
+                "error": "",
+                "duration_secs": 1.0,
+            }
+        )
+    runs.sort(key=lambda row: row["started_at"], reverse=True)
+    return runs
+
+
+def _build_summary_from_runs(cron_id: str, runs: list[dict]) -> dict:
+    completed_runs = [
+        row for row in runs if row.get("exit_code") is not None and row.get("ended_at")
+    ]
+    duration_values = [
+        float(row["duration_secs"])
+        for row in completed_runs
+        if row.get("duration_secs") is not None
+    ]
+    return {
+        "cron_id": cron_id,
+        "total_runs": len(runs),
+        "succeeded": sum(1 for row in completed_runs if row.get("exit_code") == 0),
+        "completed_runs": len(completed_runs),
+        "failed": sum(1 for row in completed_runs if row.get("exit_code") not in (None, 0)),
+        "open_runs": len(runs) - len(completed_runs),
+        "avg_duration": round(sum(duration_values) / len(duration_values), 1) if duration_values else None,
+        "last_run": runs[0].get("started_at"),
+        "last_exit_code": runs[0].get("exit_code"),
+        "last_ended_at": runs[0].get("ended_at"),
+        "last_summary": next((row.get("summary") for row in runs if row.get("summary")), ""),
+    }
+
+
 def _summary_has_warning(summary: str = "") -> bool:
     lowered = str(summary or "").strip().lower()
     if not lowered:

package/src/runtime_power.py

@@ -67,8 +67,9 @@ MACOS_FDA_PROBE_PATHS = (
 )
 DEFAULT_CLAUDE_CODE_MODEL = "claude-opus-4-6[1m]"
 DEFAULT_CLAUDE_CODE_REASONING_EFFORT = ""
-DEFAULT_CODEX_MODEL = "gpt-5.4"
-DEFAULT_CODEX_REASONING_EFFORT = "xhigh"
+# Codex defaults mirror the user's primary model — no hardcoded third-party models.
+DEFAULT_CODEX_MODEL = DEFAULT_CLAUDE_CODE_MODEL
+DEFAULT_CODEX_REASONING_EFFORT = ""
 
 
 def _schedule_defaults() -> dict:

package/src/scripts/nexo-cortex-cycle.py

@@ -18,9 +18,9 @@ What this script does (idempotent and best-effort):
 3. Detects degradation signals on the 7-day window. The criteria are
    intentionally conservative to avoid false alarms on small samples:
      a. recommendation_accept_rate < 50% AND total_evaluations >= 10
-     b. linked_outcome_success_rate < 50% AND linked_outcomes_total >= 5
+     b. linked_outcome_success_rate < 50% AND linked_outcomes_resolved >= 5
      c. override_success_rate > recommended_success_rate by >= 20pp
-        AND linked_outcomes_total >= 5
+        AND linked_outcomes_resolved >= 5
 4. Opens (or refreshes) NF-CORTEX-QUALITY-DROP followup with the offending
    metrics when degradation is detected. Idempotent: if a non-PENDING /
    resolved followup of the same id already exists, it is updated in
@@ -96,6 +96,13 @@ def detect_quality_signals(summary: dict) -> list[dict]:
     total = int(summary.get("total_evaluations") or 0)
     accept_rate = float(summary.get("recommendation_accept_rate") or 0.0)
     linked_total = int(summary.get("linked_outcomes_total") or 0)
+    linked_met = int(summary.get("linked_outcomes_met") or 0)
+    linked_missed = int(summary.get("linked_outcomes_missed") or 0)
+    linked_pending = int(summary.get("linked_outcomes_pending") or 0)
+    linked_resolved = linked_met + linked_missed
+    if linked_resolved <= 0 and linked_total > 0:
+        # Older callers may omit the met/missed counters; fall back to total minus pending.
+        linked_resolved = max(0, linked_total - linked_pending)
     linked_success = float(summary.get("linked_outcome_success_rate") or 0.0)
     recommended_success = float(summary.get("recommended_success_rate") or 0.0)
     override_success = float(summary.get("override_success_rate") or 0.0)
@@ -114,21 +121,25 @@ def detect_quality_signals(summary: dict) -> list[dict]:
             ),
         })
 
-    if linked_total >= LINKED_MIN_SAMPLE and linked_success < LINKED_SUCCESS_FLOOR:
+    linked_scope = f"{linked_resolved} resolved linked outcomes"
+    if linked_pending > 0:
+        linked_scope += f" ({linked_total} total, {linked_pending} pending)"
+
+    if linked_resolved >= LINKED_MIN_SAMPLE and linked_success < LINKED_SUCCESS_FLOOR:
         signals.append({
             "kind": "linked_success",
             "severity": "warn",
             "metric_value": linked_success,
             "threshold": LINKED_SUCCESS_FLOOR,
-            "sample_size": linked_total,
+            "sample_size": linked_resolved,
             "message": (
                 f"Cortex linked-outcome success rate {linked_success:.1f}% on "
-                f"{linked_total} linked outcomes is below the "
+                f"{linked_scope} is below the "
                 f"{LINKED_SUCCESS_FLOOR:.0f}% floor."
             ),
         })
 
-    if linked_total >= LINKED_MIN_SAMPLE:
+    if linked_resolved >= LINKED_MIN_SAMPLE:
         gap = override_success - recommended_success
         if gap >= OVERRIDE_GAP_THRESHOLD:
             signals.append({
@@ -136,12 +147,12 @@ def detect_quality_signals(summary: dict) -> list[dict]:
                 "severity": "error",
                 "metric_value": gap,
                 "threshold": OVERRIDE_GAP_THRESHOLD,
-                "sample_size": linked_total,
+                "sample_size": linked_resolved,
                 "message": (
                     f"Cortex overrides outperform recommendations by {gap:.1f}pp "
                     f"(override {override_success:.1f}% vs recommended "
-                    f"{recommended_success:.1f}% on {linked_total} linked "
-                    "outcomes). The recommender is mis-ranking choices."
+                    f"{recommended_success:.1f}% on {linked_scope}). The "
+                    "recommender is mis-ranking choices."
                 ),
             })
 
@@ -171,15 +182,37 @@ def _upsert_quality_followup(signals: list[dict]) -> str:
     resolved, a fresh row is inserted with the same id (REPLACE) so the
     new degradation pattern is visible.
     """
-    if not signals:
-        return "no_signal"
-
     try:
-        from db import get_followup, get_db
+        from db import complete_followup, get_followup, get_db
     except Exception as e:
         _log(f"WARN: cannot import db helpers: {e}")
         return "skipped_no_db"
 
+    try:
+        existing = get_followup(FOLLOWUP_ID)
+    except Exception as e:
+        _log(f"WARN: get_followup raised: {e}")
+        existing = None
+
+    if not signals:
+        if not existing:
+            return "no_signal"
+        status = str(existing.get("status") or "").upper()
+        if status.startswith("COMPLETED") or status in {"DELETED", "ARCHIVED", "BLOCKED", "WAITING", "CANCELLED"}:
+            return "no_signal"
+        try:
+            complete_followup(
+                FOLLOWUP_ID,
+                result=(
+                    "Auto-resolved by cortex-cycle: no active degradation signals in the "
+                    "current 7d window."
+                ),
+            )
+        except Exception as e:
+            _log(f"WARN: failed to close followup: {e}")
+            return "failed_close"
+        return "closed"
+
     summary_lines = ["Cortex continuous validation found quality degradation:"]
     for sig in signals:
         summary_lines.append(
@@ -197,12 +230,6 @@ def _upsert_quality_followup(signals: list[dict]) -> str:
     )
     now_epoch = datetime.now().timestamp()
 
-    try:
-        existing = get_followup(FOLLOWUP_ID)
-    except Exception as e:
-        _log(f"WARN: get_followup raised: {e}")
-        existing = None
-
     try:
         conn = get_db()
         conn.execute(
@@ -255,8 +282,8 @@ def run() -> int:
             f"signals={len(signals)}"
         )
 
-    if signals:
-        action = _upsert_quality_followup(signals)
+    action = _upsert_quality_followup(signals)
+    if signals or action not in {"no_signal"}:
         _log(f"Cortex cycle: followup {FOLLOWUP_ID} {action} ({len(signals)} signal(s))")
 
     return 0