nexo-brain 7.15.0 → 7.15.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.15.0",
+  "version": "7.15.1",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -18,7 +18,9 @@
 
 [Watch the overview video](https://nexo-brain.com/watch/) · [Watch on YouTube](https://www.youtube.com/watch?v=i2lkGhKyVqI) · [Open the infographic](https://nexo-brain.com/assets/nexo-brain-infographic-v5.png)
 
-Version `7.15.0` is the current packaged-runtime line. Minor release over v7.14.0 — Brain unifies sent-email continuity across send paths, moves cognitive recall to multilingual embeddings, forces tagged learnings into context, hardens email loop guards and headless runners, exposes learning creation dates, and adds AUTO-N burst postmortems.
+Version `7.15.1` is the current packaged-runtime line. Patch release over v7.15.0 - Brain drains larger self-audit clusters, bounds hook history with update-time cleanup, filters normal Codex bootstrap reads, routes email-monitor effort by message complexity, and locks morning briefings by local date and recipient.
+
+Previously in `7.15.0`: minor release — Brain unifies sent-email continuity across send paths, moves cognitive recall to multilingual embeddings, forces tagged learnings into context, hardens email loop guards and headless runners, exposes learning creation dates, and adds AUTO-N burst postmortems.
 
 Previously in `7.14.0`: minor release — Brain closes the install/reliability loop with update-path venv recovery, platform-gated wheels, WSL Desktop-managed flag preservation, startup memory authority warnings, legacy MEMORY write blocking, post-action real-world verification, and stale followup triage.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.15.0",
+  "version": "7.15.1",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain — Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
   "homepage": "https://nexo-brain.com",

package/src/cli.py

@@ -19,6 +19,7 @@ Entry points:
   nexo scripts run NAME_OR_PATH [-- args...]
   nexo scripts doctor [NAME_OR_PATH] [--json]
   nexo scripts call TOOL --input JSON [--json-output]
+  nexo automations reactivate NAME [--test-run] [--json]
   nexo skills list [--level ...] [--source-kind ...] [--json]
   nexo skills get ID [--json]
   nexo skills apply ID [--params JSON] [--mode ...] [--dry-run] [--json]
@@ -688,6 +689,22 @@ def _automations_set_enabled(args, enabled):
     return 0
 
 
+def _automations_reactivate(args):
+    from script_registry import reactivate_automation
+
+    result = reactivate_automation(args.name, test_run=bool(getattr(args, "test_run", False)))
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0 if result.get("ok") else 1
+    if not result.get("ok"):
+        print(result.get("error", "Could not reactivate automation"), file=sys.stderr)
+        return 1
+    print(f"Automation {result['name']} enabled.")
+    if result.get("test_run"):
+        print("Test run completed.")
+    return 0
+
+
 def _automations_status(args):
     from script_registry import get_automation_status
 
@@ -2956,6 +2973,14 @@ def main():
     automations_disable_p.add_argument("name", help="Automation name or path")
     automations_disable_p.add_argument("--json", action="store_true", help="JSON output")
 
+    automations_reactivate_p = automations_sub.add_parser(
+        "reactivate",
+        help="Enable an automation and optionally run a check",
+    )
+    automations_reactivate_p.add_argument("name", help="Automation name or path")
+    automations_reactivate_p.add_argument("--test-run", action="store_true", help="Run the automation's check without sending")
+    automations_reactivate_p.add_argument("--json", action="store_true", help="JSON output")
+
     automations_status_p = automations_sub.add_parser("status", help="Read automation status")
     automations_status_p.add_argument("name", help="Automation name or path")
     automations_status_p.add_argument("--json", action="store_true", help="JSON output")
@@ -3439,6 +3464,8 @@ def main():
             return _automations_set_enabled(args, True)
         elif args.automations_command == "disable":
             return _automations_set_enabled(args, False)
+        elif args.automations_command == "reactivate":
+            return _automations_reactivate(args)
         elif args.automations_command == "status":
             return _automations_status(args)
         elif args.automations_command == "instructions":

package/src/db/_schema.py

@@ -1,4 +1,6 @@
 """NEXO DB — Schema module."""
+import time
+
 from db._core import get_db
 from db._fts import _migrate_add_column, _migrate_add_index
 
@@ -945,6 +947,70 @@ def _m56_session_correction_requirements(conn):
     conn.execute("CREATE INDEX IF NOT EXISTS idx_session_correction_requirements_detected ON session_correction_requirements(detected_at)")
 
 
+def _m57_hook_runs_retention(conn):
+    """Bound hook_runs so existing installs stop growing without manual cleanup."""
+    try:
+        table = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='hook_runs'"
+        ).fetchone()
+    except Exception:
+        table = None
+    if not table:
+        _m39_hook_runs(conn)
+
+    retention_days = 7
+    max_rows = 19000
+    cutoff = time.time() - (retention_days * 86400)
+    conn.execute("DELETE FROM hook_runs WHERE started_at < ?", (cutoff,))
+    row = conn.execute("SELECT COUNT(*) FROM hook_runs").fetchone()
+    total = int((row[0] if row else 0) or 0)
+    if total > max_rows:
+        conn.execute(
+            """
+            DELETE FROM hook_runs
+            WHERE id NOT IN (
+                SELECT id
+                FROM hook_runs
+                ORDER BY started_at DESC, id DESC
+                LIMIT ?
+            )
+            """,
+            (max_rows,),
+        )
+    try:
+        conn.commit()
+        conn.execute("VACUUM")
+    except Exception:
+        pass
+
+
+def _m58_morning_briefing_runs(conn):
+    """Atomic dedupe lock for daily morning briefings."""
+    conn.execute(
+        """CREATE TABLE IF NOT EXISTS morning_briefing_runs (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            local_date TEXT NOT NULL,
+            recipient TEXT NOT NULL,
+            status TEXT NOT NULL DEFAULT 'in_progress',
+            subject TEXT DEFAULT '',
+            send_output TEXT DEFAULT '',
+            error TEXT DEFAULT '',
+            started_at TEXT DEFAULT (datetime('now')),
+            finished_at TEXT DEFAULT NULL,
+            updated_at TEXT DEFAULT (datetime('now')),
+            UNIQUE(local_date, recipient)
+        )"""
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_morning_briefing_runs_date "
+        "ON morning_briefing_runs(local_date)"
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_morning_briefing_runs_status "
+        "ON morning_briefing_runs(status)"
+    )
+
+
 def _m39_hook_runs(conn):
     """Persist hook lifecycle observability — closes Fase 3 item 7.
 
@@ -1517,6 +1583,8 @@ MIGRATIONS = [
     (54, "continuity_snapshots", _m54_continuity_snapshots),
     (55, "cortex_critique_trace", _m55_cortex_critique_trace),
     (56, "session_correction_requirements", _m56_session_correction_requirements),
+    (57, "hook_runs_retention", _m57_hook_runs_retention),
+    (58, "morning_briefing_runs", _m58_morning_briefing_runs),
 ]
 
 

package/src/doctor/providers/runtime.py

@@ -503,6 +503,18 @@ def _extract_declared_file_targets(args: dict, cwd: str) -> set[str]:
     return resolved
 
 
+_CODEX_PRESTARTUP_READ_EXEMPT_FILENAMES = {"calibration.json", "project-atlas.json"}
+
+
+def _is_codex_prestartup_runtime_read_exempt(touched: str, operation: str, startup_seen: bool) -> bool:
+    if startup_seen or operation != "read":
+        return False
+    normalized = _normalize_path_token(touched)
+    if Path(normalized).name not in _CODEX_PRESTARTUP_READ_EXEMPT_FILENAMES:
+        return False
+    return "/.nexo/" in normalized
+
+
 def _load_active_conditioned_learnings() -> list[dict]:
     db_path = paths.db_path()
     if not db_path.is_file():
@@ -575,6 +587,7 @@ def _recent_codex_conditioned_file_discipline_status(*, days: int = 7, max_files
         protocol_files: set[str] = set()
         guard_files: set[str] = set()
         guard_ack = False
+        startup_seen = False
         session_touches = 0
         session_samples: list[dict] = []
 
@@ -601,6 +614,9 @@ def _recent_codex_conditioned_file_discipline_status(*, days: int = 7, max_files
                     name = str(payload.get("name", "") or "")
                     args = _parse_jsonish_arguments(payload.get("arguments"))
 
+                    if name in {"mcp__nexo__nexo_startup", "nexo_startup"}:
+                        startup_seen = True
+                        continue
                     if name in {"mcp__nexo__nexo_task_open", "nexo_task_open"}:
                         protocol_active = True
                         protocol_files.update(_extract_declared_file_targets(args, cwd))
@@ -628,6 +644,8 @@ def _recent_codex_conditioned_file_discipline_status(*, days: int = 7, max_files
                         continue
 
                     for touched, operation in touched_files:
+                        if _is_codex_prestartup_runtime_read_exempt(touched, operation, startup_seen):
+                            continue
                         matches = [row for row in conditioned if _applies_to_matches_file(str(row.get("applies_to", "")), touched)]
                         if not matches:
                             continue

package/src/hook_observability.py

@@ -33,6 +33,8 @@ from db import get_db
 
 
 _VALID_STATUS = {"ok", "error", "skipped", "timeout", "blocked"}
+HOOK_RUNS_RETENTION_DAYS = 7
+HOOK_RUNS_MAX_ROWS = 19000
 
 
 def _coerce_status(exit_code: int, status: str = "") -> str:
@@ -45,6 +47,71 @@ def _coerce_status(exit_code: int, status: str = "") -> str:
     return "error"
 
 
+def cleanup_hook_runs(
+    *,
+    retention_days: int = HOOK_RUNS_RETENTION_DAYS,
+    max_rows: int = HOOK_RUNS_MAX_ROWS,
+    now: float | None = None,
+    vacuum: bool = False,
+    conn=None,
+) -> dict:
+    """Keep hook_runs bounded by age and newest-row count.
+
+    This is deliberately best-effort: hook observability must never make
+    the hook path fail. ``started_at`` is stored as REAL epoch seconds, so
+    the comparison is numeric and works across SQLite versions.
+    """
+    try:
+        days = max(1, int(retention_days))
+    except (TypeError, ValueError):
+        days = HOOK_RUNS_RETENTION_DAYS
+    try:
+        limit = max(1, int(max_rows))
+    except (TypeError, ValueError):
+        limit = HOOK_RUNS_MAX_ROWS
+    now_epoch = float(time.time() if now is None else now)
+    cutoff = now_epoch - (days * 86400)
+    try:
+        db_conn = conn or get_db()
+        old_cur = db_conn.execute("DELETE FROM hook_runs WHERE started_at < ?", (cutoff,))
+        deleted_old = int(old_cur.rowcount or 0)
+        count_row = db_conn.execute("SELECT COUNT(*) FROM hook_runs").fetchone()
+        remaining = int((count_row[0] if count_row else 0) or 0)
+        deleted_overflow = 0
+        if remaining > limit:
+            overflow_cur = db_conn.execute(
+                """
+                DELETE FROM hook_runs
+                WHERE id NOT IN (
+                    SELECT id
+                    FROM hook_runs
+                    ORDER BY started_at DESC, id DESC
+                    LIMIT ?
+                )
+                """,
+                (limit,),
+            )
+            deleted_overflow = int(overflow_cur.rowcount or 0)
+            remaining = limit
+        try:
+            db_conn.commit()
+        except Exception:
+            pass
+        if vacuum and (deleted_old or deleted_overflow):
+            try:
+                db_conn.execute("VACUUM")
+            except Exception:
+                pass
+        return {
+            "ok": True,
+            "deleted_old": deleted_old,
+            "deleted_overflow": deleted_overflow,
+            "remaining": remaining,
+        }
+    except Exception as exc:
+        return {"ok": False, "error": str(exc), "deleted_old": 0, "deleted_overflow": 0, "remaining": 0}
+
+
 def record_hook_run(
     hook_name: str,
     *,
@@ -98,6 +165,10 @@ def record_hook_run(
     now_epoch = time.time()
     try:
         conn = get_db()
+        try:
+            cleanup_hook_runs(conn=conn)
+        except Exception:
+            pass
         cur = conn.execute(
             "INSERT INTO hook_runs (hook_name, started_at, duration_ms, exit_code, "
             "status, session_id, summary, metadata, created_at) "

package/src/script_registry.py

@@ -14,6 +14,7 @@ import re
 import shutil
 import stat
 import subprocess
+import sys
 import time
 from pathlib import Path
 import paths
@@ -2361,6 +2362,73 @@ def get_automation_status(name_or_path: str) -> dict:
     return get_personal_script_status(name_or_path)
 
 
+def _script_execution_command(script: dict) -> list[str]:
+    path = str(script.get("path") or "").strip()
+    runtime = str(script.get("runtime") or "").strip().lower()
+    if runtime == "python" or path.endswith(".py"):
+        return [sys.executable, path]
+    if runtime == "shell" or path.endswith((".sh", ".bash", ".zsh")):
+        return ["/bin/bash", path]
+    return [path]
+
+
+def reactivate_automation(name_or_path: str, *, test_run: bool = False, timeout_seconds: int = 180) -> dict:
+    """Enable an operator automation and optionally run its built-in check."""
+    enable_result = set_automation_enabled(name_or_path, True)
+    if not enable_result.get("ok"):
+        return enable_result
+
+    status_result = get_automation_status(name_or_path)
+    result = {
+        "ok": bool(status_result.get("ok", True)),
+        "name": enable_result.get("name") or name_or_path,
+        "enabled": True,
+        "changed": bool(enable_result.get("changed")),
+        "status": status_result,
+    }
+    if not test_run:
+        return result
+
+    resolved = resolve_script_reference(str(result["name"])) or resolve_script_reference(name_or_path)
+    if not resolved:
+        result.update({"ok": False, "error": "Automation enabled, but the test run could not be started."})
+        return result
+    if str(resolved.get("name") or "").strip() != "morning-agent":
+        result.update({"ok": False, "error": "Test run is available for morning-agent only."})
+        return result
+
+    command = _script_execution_command(resolved) + ["--dry-run"]
+    env = os.environ.copy()
+    env["NEXO_HEADLESS"] = "1"
+    try:
+        completed = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            timeout=max(30, int(timeout_seconds)),
+            env=env,
+        )
+    except Exception as exc:
+        result.update({
+            "ok": False,
+            "error": "Test run could not start.",
+            "test_run": {"ok": False, "error": str(exc)},
+        })
+        return result
+
+    test_payload = {
+        "ok": completed.returncode == 0,
+        "exit_code": completed.returncode,
+        "stdout_tail": (completed.stdout or "")[-2000:],
+        "stderr_tail": (completed.stderr or "")[-2000:],
+    }
+    result["test_run"] = test_payload
+    if completed.returncode != 0:
+        result["ok"] = False
+        result["error"] = "Test run did not complete."
+    return result
+
+
 def set_script_extra_instructions(name_or_path: str, instructions: str) -> dict:
     """Persist operator-side prompt additions without touching the core prompt."""
     from automation_controls import supports_operator_extra_instructions

package/src/scripts/nexo-daily-self-audit.py

@@ -88,6 +88,7 @@ AUDIT_HISTORY_DIR = LOG_DIR / "self-audit"
 AUDIT_HISTORY_DIR.mkdir(parents=True, exist_ok=True)
 LOG_FILE = LOG_DIR / "self-audit.log"
 NEXO_DB = data_dir() / "nexo.db"
+SELF_AUDIT_INLINE_BATCH_LIMIT = 50
 # Configure your main project repo to check for uncommitted changes (optional)
 PROJECT_REPO_DIR = None  # e.g., Path.home() / "projects" / "my-repo"
 HASH_REGISTRY = core_scripts_dir() / ".watchdog-hashes"
@@ -1228,7 +1229,7 @@ def check_error_memory_loop():
     if repeated:
         resolved = 0
         completed_followups = 0
-        for signature, items in list(repeated.items())[:5]:
+        for signature, items in list(repeated.items())[:SELF_AUDIT_INLINE_BATCH_LIMIT]:
             description = (
                 f"Mine a canonical prevention learning from repeated failed/blocked protocol tasks around {signature}"
             )
@@ -1433,7 +1434,7 @@ def check_unformalized_mentions():
     if loose_topics:
         resolved = 0
         completed_followups = 0
-        for (area, signature), items in list(loose_topics.items())[:5]:
+        for (area, signature), items in list(loose_topics.items())[:SELF_AUDIT_INLINE_BATCH_LIMIT]:
             sample_goal = str(items[0]["goal"] or "").strip()[:120]
             description = (
                 f"Formalize repeated unresolved theme in {area}: '{sample_goal}' "
@@ -1523,7 +1524,7 @@ def check_automation_opportunities():
     }
     if repeated:
         finding("INFO", "opportunities", f"{len(repeated)} repeated manual pattern(s) are good candidates for skills/scripts")
-        for (area, signature), items in list(repeated.items())[:5]:
+        for (area, signature), items in list(repeated.items())[:SELF_AUDIT_INLINE_BATCH_LIMIT]:
             sample_goal = str(items[0]["goal"] or "").strip()[:120]
             description = (
                 f"Extract a reusable automation for repeated {area} work around '{sample_goal}' "

package/src/scripts/nexo-email-monitor.py

@@ -2102,6 +2102,48 @@ def build_processing_prompt(
     )
 
 
+_EMAIL_MONITOR_COMPLEXITY_HIGH_TERMS = (
+    "urgent", "urgente", "complaint", "queja", "reclamacion", "reclamación",
+    "legal", "contract", "contrato", "invoice", "factura", "payment", "pago",
+    "refund", "devolucion", "devolución", "booking", "reserva", "reservation",
+    "cancel", "cancelacion", "cancelación", "cancellation", "deadline",
+    "plazo", "claim", "dispute", "incidencia", "broken", "error",
+)
+_EMAIL_MONITOR_COMPLEXITY_SIMPLE_TERMS = (
+    "thanks", "thank you", "gracias", "ok", "okay", "received", "recibido",
+    "confirmado", "confirmation", "confirmacion", "confirmación", "perfecto",
+    "noted", "anotado",
+)
+
+
+def _email_monitor_complexity_tier(target_emails=None, *, needs_interactive=None, debt_block: str = "") -> str:
+    emails = list(target_emails or [])
+    interactive = list(needs_interactive or [])
+    if str(debt_block or "").strip() or interactive:
+        return "alto"
+    if len(emails) >= 3:
+        return "alto"
+
+    text_parts: list[str] = []
+    attempts = 0
+    for em in emails:
+        getter = em.get if hasattr(em, "get") else lambda key, default=None: default
+        attempts = max(attempts, _safe_int(getter("attempts", 0), 0))
+        for key in ("subject", "from_addr", "snippet", "body", "body_text"):
+            value = str(getter(key, "") or "").strip()
+            if value:
+                text_parts.append(value)
+    if attempts > 0:
+        return "alto"
+
+    joined = " ".join(text_parts).lower()
+    if any(term in joined for term in _EMAIL_MONITOR_COMPLEXITY_HIGH_TERMS):
+        return "alto"
+    if emails and len(emails) <= 1 and any(term in joined for term in _EMAIL_MONITOR_COMPLEXITY_SIMPLE_TERMS):
+        return "bajo"
+    return "medio"
+
+
 def launch_nexo(config, debt_block="", target_emails=None):
     """Launch NEXO through the configured automation backend to process emails.
     target_emails: optional list of dicts with message_id, subject, attempts."""
@@ -2137,6 +2179,11 @@ def launch_nexo(config, debt_block="", target_emails=None):
             f"Resuming from checkpoint(s) for {len(target_message_ids)} email(s); "
             "previous attempt context attached to prompt."
         )
+    email_tier = _email_monitor_complexity_tier(
+        target_emails=target_emails,
+        needs_interactive=needs_interactive,
+        debt_block=debt_block,
+    )
     prompt = build_processing_prompt(
         config=config,
         operator_name=operator_name,
@@ -2175,7 +2222,7 @@ def launch_nexo(config, debt_block="", target_emails=None):
     try:
         from resonance_map import resolve_model_and_effort
 
-        mapped_model, mapped_effort = resolve_model_and_effort("email_monitor", backend)
+        mapped_model, mapped_effort = resolve_model_and_effort("email_monitor", backend, explicit_tier=email_tier)
         profile_label = mapped_model or "default"
         if mapped_effort:
             profile_label = f"{profile_label}/{mapped_effort}"
@@ -2217,6 +2264,7 @@ def launch_nexo(config, debt_block="", target_emails=None):
             timeout=effective_timeout,
             output_format="text",
             allowed_tools="Read,Write,Edit,Glob,Grep,Bash,mcp__nexo__*",
+            tier=email_tier,
         )
 
         if result.stdout.strip():

package/src/scripts/nexo-morning-agent.py

@@ -71,6 +71,7 @@ CLI_TIMEOUT = 1800
 MAX_DUE_ITEMS = 8
 MAX_ACTIVE_ITEMS = 8
 MAX_DIARY_ITEMS = 6
+MORNING_BRIEFING_STALE_HOURS = 12
 
 
 def log(message: str) -> None:
@@ -96,6 +97,184 @@ def save_state(state: dict) -> None:
     STATE_FILE.write_text(json.dumps(state, indent=2, ensure_ascii=False) + "\n")
 
 
+def _morning_db_connection():
+    nexo_db.init_db()
+    return nexo_db.get_db()
+
+
+def _ensure_morning_briefing_runs_table(conn) -> None:
+    conn.execute(
+        """CREATE TABLE IF NOT EXISTS morning_briefing_runs (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            local_date TEXT NOT NULL,
+            recipient TEXT NOT NULL,
+            status TEXT NOT NULL DEFAULT 'in_progress',
+            subject TEXT DEFAULT '',
+            send_output TEXT DEFAULT '',
+            error TEXT DEFAULT '',
+            started_at TEXT DEFAULT (datetime('now')),
+            finished_at TEXT DEFAULT NULL,
+            updated_at TEXT DEFAULT (datetime('now')),
+            UNIQUE(local_date, recipient)
+        )"""
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_morning_briefing_runs_date "
+        "ON morning_briefing_runs(local_date)"
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_morning_briefing_runs_status "
+        "ON morning_briefing_runs(status)"
+    )
+
+
+def _row_dict(row) -> dict:
+    if row is None:
+        return {}
+    try:
+        return dict(row)
+    except Exception:
+        return {}
+
+
+def _briefing_run_is_stale(row: dict) -> bool:
+    started_raw = str(row.get("started_at") or "").strip()
+    if not started_raw:
+        return True
+    try:
+        started = datetime.fromisoformat(started_raw.replace("Z", "+00:00"))
+        now = datetime.now(started.tzinfo) if started.tzinfo else datetime.now()
+        return (now - started).total_seconds() > (MORNING_BRIEFING_STALE_HOURS * 3600)
+    except Exception:
+        return True
+
+
+def _claim_morning_briefing_send(local_date: str, recipient: str, *, force: bool = False) -> dict:
+    clean_date = str(local_date or "").strip()
+    clean_recipient = str(recipient or "").strip()
+    if not clean_date or not clean_recipient:
+        return {"ok": False, "acquired": False, "reason": "missing recipient"}
+    now = datetime.now().astimezone().isoformat()
+    conn = _morning_db_connection()
+    _ensure_morning_briefing_runs_table(conn)
+    if force:
+        conn.execute(
+            """
+            INSERT INTO morning_briefing_runs
+                (local_date, recipient, status, subject, send_output, error, started_at, finished_at, updated_at)
+            VALUES (?, ?, 'in_progress', '', '', '', ?, NULL, ?)
+            ON CONFLICT(local_date, recipient) DO UPDATE SET
+                status = 'in_progress',
+                subject = '',
+                send_output = '',
+                error = '',
+                started_at = excluded.started_at,
+                finished_at = NULL,
+                updated_at = excluded.updated_at
+            """,
+            (clean_date, clean_recipient, now, now),
+        )
+        conn.commit()
+        return {"ok": True, "acquired": True, "reason": "force"}
+
+    cur = conn.execute(
+        """
+        INSERT OR IGNORE INTO morning_briefing_runs
+            (local_date, recipient, status, started_at, updated_at)
+        VALUES (?, ?, 'in_progress', ?, ?)
+        """,
+        (clean_date, clean_recipient, now, now),
+    )
+    conn.commit()
+    if int(cur.rowcount or 0) == 1:
+        return {"ok": True, "acquired": True, "reason": "new"}
+
+    row = _row_dict(conn.execute(
+        "SELECT * FROM morning_briefing_runs WHERE local_date = ? AND recipient = ?",
+        (clean_date, clean_recipient),
+    ).fetchone())
+    status = str(row.get("status") or "").strip().lower()
+    if status == "failed" or (status == "in_progress" and _briefing_run_is_stale(row)):
+        conn.execute(
+            """
+            UPDATE morning_briefing_runs
+            SET status = 'in_progress',
+                subject = '',
+                send_output = '',
+                error = '',
+                started_at = ?,
+                finished_at = NULL,
+                updated_at = ?
+            WHERE local_date = ? AND recipient = ?
+            """,
+            (now, now, clean_date, clean_recipient),
+        )
+        conn.commit()
+        return {"ok": True, "acquired": True, "reason": "retry"}
+    return {"ok": True, "acquired": False, "reason": status or "already claimed", "run": row}
+
+
+def _record_existing_morning_briefing_sent(local_date: str, recipient: str, state: dict) -> None:
+    now = datetime.now().astimezone().isoformat()
+    conn = _morning_db_connection()
+    _ensure_morning_briefing_runs_table(conn)
+    conn.execute(
+        """
+        INSERT OR IGNORE INTO morning_briefing_runs
+            (local_date, recipient, status, subject, send_output, error, started_at, finished_at, updated_at)
+        VALUES (?, ?, 'sent', ?, ?, '', ?, ?, ?)
+        """,
+        (
+            str(local_date or "").strip(),
+            str(recipient or "").strip(),
+            str(state.get("last_subject") or ""),
+            str(state.get("last_send_output") or ""),
+            str(state.get("last_sent_at") or now),
+            str(state.get("last_sent_at") or now),
+            now,
+        ),
+    )
+    conn.commit()
+
+
+def _mark_morning_briefing_sent(local_date: str, recipient: str, *, subject: str, send_output: str) -> None:
+    now = datetime.now().astimezone().isoformat()
+    conn = _morning_db_connection()
+    _ensure_morning_briefing_runs_table(conn)
+    conn.execute(
+        """
+        UPDATE morning_briefing_runs
+        SET status = 'sent',
+            subject = ?,
+            send_output = ?,
+            error = '',
+            finished_at = ?,
+            updated_at = ?
+        WHERE local_date = ? AND recipient = ?
+        """,
+        (str(subject or ""), str(send_output or ""), now, now, str(local_date or ""), str(recipient or "")),
+    )
+    conn.commit()
+
+
+def _mark_morning_briefing_failed(local_date: str, recipient: str, *, error: str) -> None:
+    now = datetime.now().astimezone().isoformat()
+    conn = _morning_db_connection()
+    _ensure_morning_briefing_runs_table(conn)
+    conn.execute(
+        """
+        UPDATE morning_briefing_runs
+        SET status = 'failed',
+            error = ?,
+            finished_at = ?,
+            updated_at = ?
+        WHERE local_date = ? AND recipient = ?
+        """,
+        (str(error or "")[:1000], now, now, str(local_date or ""), str(recipient or "")),
+    )
+    conn.commit()
+
+
 def resolve_recipient(profile: dict | None = None, *, explicit_to: str = "") -> str:
     override = str(explicit_to or "").strip()
     if override:
@@ -411,8 +590,15 @@ def main(argv: list[str] | None = None) -> int:
     today = date.today().isoformat()
     if not args.force and not args.dry_run:
         if state.get("last_sent_date") == today and state.get("last_recipient") == recipient:
+            _record_existing_morning_briefing_sent(today, recipient, state)
             log(f"Morning briefing already sent today to {recipient}; use --force to resend.")
             return 0
+        claim = _claim_morning_briefing_send(today, recipient)
+        if not claim.get("acquired"):
+            log(f"Morning briefing already handled today for {recipient}.")
+            return 0
+    elif args.force and not args.dry_run:
+        _claim_morning_briefing_send(today, recipient, force=True)
 
     try:
         context = collect_context(profile)
@@ -430,6 +616,7 @@ def main(argv: list[str] | None = None) -> int:
 
         log(f"Sending morning briefing to {recipient}...")
         send_output = send_briefing(recipient=recipient, subject=subject, body=body)
+        _mark_morning_briefing_sent(today, recipient, subject=subject, send_output=send_output)
         save_state({
             "last_sent_date": today,
             "last_sent_at": datetime.now().astimezone().isoformat(),
@@ -440,9 +627,13 @@ def main(argv: list[str] | None = None) -> int:
         log("Morning briefing sent.")
         return 0
     except AutomationBackendUnavailableError as exc:
+        if not args.dry_run and recipient:
+            _mark_morning_briefing_failed(today, recipient, error=str(exc))
         log(f"Automation backend unavailable: {exc}")
         return 1
     except Exception as exc:
+        if not args.dry_run and recipient:
+            _mark_morning_briefing_failed(today, recipient, error=str(exc))
         log(f"Morning agent failed: {exc}")
         return 1