nexo-brain 2.6.5 → 2.6.7

package/src/cli.py

@@ -22,6 +22,7 @@ Entry points:
   nexo skills approve ID [--execution-level ...] [--approved-by ...] [--json]
   nexo skills featured [--limit N] [--json]
   nexo skills evolution [--json]
+  nexo contributor status|on|off [--json]
   nexo doctor [--tier boot|runtime|deep|all] [--json] [--fix]
 """
 from __future__ import annotations
@@ -451,9 +452,25 @@ def _update(args):
     - Packaged/runtime-only install: delegate to plugins.update handle_update()
     """
     from auto_update import manual_sync_update, _resolve_sync_source
-    from runtime_power import ensure_power_policy_choice, apply_power_policy, format_power_policy_label
+    from runtime_power import (
+        ensure_power_policy_choice,
+        apply_power_policy,
+        format_power_policy_label,
+        ensure_full_disk_access_choice,
+        format_full_disk_access_label,
+    )
+    from public_contribution import (
+        ensure_public_contribution_choice,
+        format_public_contribution_label,
+    )
 
     interactive = sys.stdin.isatty() and sys.stdout.isatty()
+    progress_messages: list[str] = []
+
+    def progress(message: str) -> None:
+        progress_messages.append(message)
+        if not args.json:
+            print(f"[NEXO] {message}", flush=True)
 
     dest = NEXO_HOME
     src_dir, repo_dir = _resolve_sync_source()
@@ -469,16 +486,25 @@ def _update(args):
             )
             return 1
 
-        result = handle_update()
+        result = handle_update(progress_fn=progress)
         choice = ensure_power_policy_choice(interactive=interactive, reason="update")
         power_result = apply_power_policy(choice.get("policy"))
+        fda_choice = ensure_full_disk_access_choice(interactive=interactive, reason="update")
+        contrib_choice = ensure_public_contribution_choice(interactive=interactive, reason="update")
         if args.json:
             print(json.dumps({
                 "mode": "packaged",
                 "message": result,
+                "progress": progress_messages,
                 "power_policy": choice.get("policy"),
                 "power_action": power_result.get("action"),
                 "power_details": power_result.get("details"),
+                "full_disk_access_status": fda_choice.get("status"),
+                "full_disk_access_reasons": fda_choice.get("reasons"),
+                "full_disk_access_message": fda_choice.get("message"),
+                "public_contribution_mode": contrib_choice.get("mode"),
+                "public_contribution_status": contrib_choice.get("status"),
+                "public_contribution_message": contrib_choice.get("message"),
             }, indent=2, ensure_ascii=False))
         else:
             print(result)
@@ -486,16 +512,35 @@ def _update(args):
                 print(f"Power policy: {format_power_policy_label(choice.get('policy'))}")
             if power_result.get("message"):
                 print(f"Power helper: {power_result.get('message')}")
+            if fda_choice.get("prompted"):
+                print(f"Full Disk Access: {format_full_disk_access_label(fda_choice.get('status'))}")
+            if fda_choice.get("message"):
+                print(f"Full Disk Access: {fda_choice.get('message')}")
+            if contrib_choice.get("prompted"):
+                print(f"Contributor mode: {format_public_contribution_label(contrib_choice)}")
+            if contrib_choice.get("message"):
+                print(f"Contributor mode: {contrib_choice.get('message')}")
         return 0 if "UPDATE SUCCESSFUL" in result or "Already up to date" in result else 1
 
     choice = ensure_power_policy_choice(interactive=interactive, reason="update")
     power_result = apply_power_policy(choice.get("policy"))
-    result = manual_sync_update(interactive=interactive, allow_source_pull=True)
+    fda_choice = ensure_full_disk_access_choice(interactive=interactive, reason="update")
+    contrib_choice = ensure_public_contribution_choice(interactive=interactive, reason="update")
+    result = manual_sync_update(interactive=interactive, allow_source_pull=True, progress_fn=progress)
     result["power_policy"] = choice.get("policy")
     result["power_action"] = power_result.get("action")
     result["power_details"] = power_result.get("details")
+    result["full_disk_access_status"] = fda_choice.get("status")
+    result["full_disk_access_reasons"] = fda_choice.get("reasons")
+    result["public_contribution_mode"] = contrib_choice.get("mode")
+    result["public_contribution_status"] = contrib_choice.get("status")
+    result["progress"] = progress_messages
     if power_result.get("message"):
         result["power_message"] = power_result.get("message")
+    if fda_choice.get("message"):
+        result["full_disk_access_message"] = fda_choice.get("message")
+    if contrib_choice.get("message"):
+        result["public_contribution_message"] = contrib_choice.get("message")
     if args.json:
         print(json.dumps(result, indent=2, ensure_ascii=False))
     else:
@@ -511,11 +556,84 @@ def _update(args):
                 print(f"  Power policy: {format_power_policy_label(choice.get('policy'))}")
             if power_result.get("message"):
                 print(f"  Power helper: {power_result.get('message')}")
+            if fda_choice.get("prompted"):
+                print(f"  Full Disk Access: {format_full_disk_access_label(fda_choice.get('status'))}")
+            if fda_choice.get("message"):
+                print(f"  Full Disk Access: {fda_choice.get('message')}")
+            if contrib_choice.get("prompted"):
+                print(f"  Contributor mode: {format_public_contribution_label(contrib_choice)}")
+            if contrib_choice.get("message"):
+                print(f"  Contributor mode: {contrib_choice.get('message')}")
         else:
             print(f"UPDATE FAILED: {result.get('error', 'sync failed')}", file=sys.stderr)
     return 0 if result.get("ok") else 1
 
 
+def _contributor_status(args):
+    from public_contribution import (
+        format_public_contribution_label,
+        load_public_contribution_config,
+        refresh_public_contribution_state,
+    )
+
+    config = refresh_public_contribution_state(load_public_contribution_config())
+    payload = {
+        "enabled": bool(config.get("enabled")),
+        "mode": config.get("mode"),
+        "status": config.get("status"),
+        "label": format_public_contribution_label(config),
+        "github_user": config.get("github_user"),
+        "fork_repo": config.get("fork_repo"),
+        "active_pr_url": config.get("active_pr_url"),
+        "active_branch": config.get("active_branch"),
+        "cooldown_until": config.get("cooldown_until"),
+        "last_result": config.get("last_result"),
+    }
+    if args.json:
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+    else:
+        print(f"Contributor mode: {payload['label']}")
+        if payload["github_user"]:
+            print(f"  GitHub user: {payload['github_user']}")
+        if payload["fork_repo"]:
+            print(f"  Fork: {payload['fork_repo']}")
+        if payload["active_pr_url"]:
+            print(f"  Active Draft PR: {payload['active_pr_url']}")
+        if payload["cooldown_until"]:
+            print(f"  Cooldown until: {payload['cooldown_until']}")
+        if payload["last_result"]:
+            print(f"  Last result: {payload['last_result']}")
+    return 0
+
+
+def _contributor_on(args):
+    from public_contribution import ensure_public_contribution_choice, format_public_contribution_label
+
+    interactive = sys.stdin.isatty() and sys.stdout.isatty()
+    if not interactive:
+        print("Contributor mode requires an interactive terminal to confirm GitHub Draft PR consent.", file=sys.stderr)
+        return 1
+    config = ensure_public_contribution_choice(interactive=True, reason="contributor", force_prompt=True)
+    if args.json:
+        print(json.dumps(config, indent=2, ensure_ascii=False))
+    else:
+        print(f"Contributor mode: {format_public_contribution_label(config)}")
+        if config.get("message"):
+            print(config.get("message"))
+    return 0 if config.get("mode") == "draft_prs" else 1
+
+
+def _contributor_off(args):
+    from public_contribution import disable_public_contribution, format_public_contribution_label
+
+    config = disable_public_contribution()
+    if args.json:
+        print(json.dumps(config, indent=2, ensure_ascii=False))
+    else:
+        print(f"Contributor mode: {format_public_contribution_label(config)}")
+    return 0
+
+
 def _service_control(service_name: str, action: str) -> int:
     """Control a LaunchAgent/systemd service: on, off, status."""
     import platform as plat
@@ -744,6 +862,7 @@ Commands:
                                                       Personal scripts
   nexo skills list|apply|sync|approve                  Executable skills
   nexo update                                          Update installed runtime
+  nexo contributor status|on|off                       Public Draft PR contribution mode
   nexo dashboard on|off|status                         Web dashboard control
 
 Run 'nexo <command> --help' for details.
@@ -838,6 +957,11 @@ def main():
     doctor_parser.add_argument("--json", action="store_true", help="JSON output")
     doctor_parser.add_argument("--fix", action="store_true", help="Apply deterministic fixes")
 
+    # -- contributor --
+    contributor_parser = sub.add_parser("contributor", help="Public Draft PR contribution mode")
+    contributor_parser.add_argument("action", choices=["status", "on", "off"], help="Manage contributor mode")
+    contributor_parser.add_argument("--json", action="store_true", help="JSON output")
+
     # -- skills --
     skills_parser = sub.add_parser("skills", help="Skills v2 runtime")
     skills_sub = skills_parser.add_subparsers(dest="skills_command")
@@ -923,6 +1047,15 @@ def main():
         return _update(args)
     elif args.command == "doctor":
         return _doctor(args)
+    elif args.command == "contributor":
+        if args.action == "status":
+            return _contributor_status(args)
+        elif args.action == "on":
+            return _contributor_on(args)
+        elif args.action == "off":
+            return _contributor_off(args)
+        contributor_parser.print_help()
+        return 0
     elif args.command == "skills":
         if args.skills_command == "list":
             return _skills_list(args)

package/src/db/_episodic.py

@@ -573,7 +573,7 @@ def read_session_diary(session_id: str = '', last_n: int = 3, last_day: bool = F
     """Read session diary entries.
 
     - session_id: returns entries for that specific session
-    - last_day: returns ALL entries from the most recent day (multi-terminal aware)
+    - last_day: returns the recent continuity window (~36h), including the previous evening
     - last_n: returns last N entries (default)
     - domain: filter by project context (nexo, other)
     - include_automated: if False (default), excludes automated sessions (auto-close,
@@ -605,21 +605,11 @@ def read_session_diary(session_id: str = '', last_n: int = 3, last_day: bool = F
             (session_id,) + domain_params
         ).fetchall()
     elif last_day:
-        # Get all entries from the most recent calendar day (human sessions only)
-        if domain:
-            latest = conn.execute(
-                f"SELECT date(created_at) as day FROM session_diary WHERE domain = ?{source_clause} ORDER BY created_at DESC LIMIT 1",
-                (domain,)
-            ).fetchone()
-        else:
-            latest = conn.execute(
-                f"SELECT date(created_at) as day FROM session_diary WHERE 1=1{source_clause} ORDER BY created_at DESC LIMIT 1"
-            ).fetchone()
-        if not latest:
-            return []
         rows = conn.execute(
-            f"SELECT * FROM session_diary WHERE date(created_at) = ?{domain_clause}{source_clause} ORDER BY created_at DESC",
-            (latest['day'],) + domain_params
+            f"SELECT * FROM session_diary "
+            f"WHERE created_at >= datetime('now', '-36 hours'){domain_clause}{source_clause} "
+            f"ORDER BY created_at DESC",
+            domain_params
         ).fetchall()
     else:
         rows = conn.execute(
@@ -770,4 +760,3 @@ def recall(query: str, days: int = 30) -> list[dict]:
     results.sort(key=lambda r: r.get('created_at', ''), reverse=True)
     return results[:20]
 
-

package/src/doctor/providers/runtime.py

@@ -747,6 +747,11 @@ def check_launchagent_integrity(fix: bool = False) -> DoctorCheck:
             "and treat recent 'Operation not permitted' against Documents/Desktop/Downloads as a TCC/runtime path issue."
         ),
     )
+    if tcc_risk:
+        check.repair_plan.append(
+            "On macOS, grant Full Disk Access manually if protected folders are required; "
+            "NEXO can only open the System Settings pane and verify best effort"
+        )
 
     if fix:
         sync_ok, sync_evidence = _sync_launchagents_from_manifest()

package/src/evolution_cycle.py

@@ -57,16 +57,20 @@ def normalize_objective(obj: dict | None) -> dict:
 
     if "evolution_mode" in source:
         mode = str(source.get("evolution_mode") or "auto").strip().lower()
+        if mode in {"public", "public_core", "contributor", "draft_prs"}:
+            mode = "public_core"
     else:
         legacy_mode = str(source.get("review_mode") or "").strip().lower()
         if legacy_mode in {"manual", "review"}:
             mode = "review"
         elif legacy_mode in {"managed", "hybrid", "owner", "core"}:
             mode = "managed"
+        elif legacy_mode in {"public", "public_core", "contributor", "draft_prs"}:
+            mode = "public_core"
         else:
             mode = "auto"
 
-    if mode not in {"auto", "review", "managed"}:
+    if mode not in {"auto", "review", "managed", "public_core"}:
         mode = "auto"
 
     dimensions = source.get("dimensions")
@@ -276,6 +280,10 @@ def build_evolution_prompt(week_data: dict, objective: dict) -> str:
         mode_desc = f"owner-managed, max {max_auto} auto-applied changes with rollback and followups"
         safe_zones = "~/.nexo/scripts/, ~/.nexo/plugins/, ~/.nexo/brain/, NEXO_CODE/src, repo bin/docs/templates/tests"
         immutable_files = "db.py, server.py, plugin_loader.py, storage_router.py, nexo-watchdog.sh, evolution_cycle.py, CLAUDE.md, personality.md, user-profile.md"
+    elif mode == "public_core":
+        mode_desc = "public core contribution via isolated checkout and Draft PR"
+        safe_zones = "isolated public repo checkout only"
+        immutable_files = "personal runtime, ~/.nexo/**, local DBs/logs, CLAUDE.md, user-profile.md"
     else:
         mode_desc = f"public auto, max {max_auto} auto-applied changes in personal safe zones"
         safe_zones = "~/.nexo/scripts/, ~/.nexo/plugins/"
@@ -340,6 +348,48 @@ Max 3 proposals. Quality over quantity. If nothing needs improving, say so."""
     return prompt
 
 
+def build_public_contribution_prompt(*, repo_root: str, cycle_number: int) -> str:
+    """Prompt for the public-core contributor mode.
+
+    This prompt must never rely on private runtime state. It should inspect only
+    the isolated public repo checkout, make one coherent improvement, and end
+    by returning machine-readable summary JSON.
+    """
+
+    return f"""You are NEXO Public Evolution.
+
+You are running inside an isolated checkout of the public NEXO repository.
+Your job is to make one technically coherent improvement to the public core and
+prepare it for a Draft PR.
+
+STRICT RULES:
+- Work only inside this repository checkout: {repo_root}
+- You may modify only public core surfaces: src/, bin/, tests/, templates/, hooks/, migrations/, .claude-plugin/
+- Do not read or use ~/.nexo, local DBs, personal scripts, emails, logs, prompts, secrets, or any user-identifying paths
+- Do not push, open PRs, or change git remotes yourself
+- Do not touch README, website, gh-pages, changelog, or release metadata in this mode
+- Focus on one concrete improvement only
+- Run validation for the files you touched
+
+What to do:
+1. Inspect the repo and find a real, self-contained improvement in reliability, install/update behavior, cron recovery, diagnostics, hooks, tests, or other core infrastructure.
+2. Implement the change directly in this checkout.
+3. Run the smallest relevant validation commands.
+4. Return ONLY valid JSON with this shape:
+
+{{
+  "title": "type: short title",
+  "problem": "what was wrong",
+  "summary": "what you changed",
+  "tests": ["command 1", "command 2"],
+  "risks": ["risk 1", "risk 2"]
+}}
+
+Cycle: #{cycle_number}
+Quality over quantity. One strong improvement is better than three weak ones.
+"""
+
+
 def max_auto_changes(total_evolutions: int) -> int:
     """Progressive trust: 1 for first 4 cycles, 2 for next 4, then 3."""
     if total_evolutions < 4:

package/src/plugins/episodic_memory.py

@@ -236,7 +236,7 @@ def handle_session_diary_read(session_id: str = '', last_n: int = 3, last_day: b
     Args:
         session_id: Specific session ID to read (optional)
         last_n: Number of recent entries to return (default 3)
-        last_day: If true, returns ALL entries from the most recent day (multi-terminal aware). Use this at startup.
+        last_day: If true, returns the recent continuity window (~36h), including the previous evening. Use this at startup.
         domain: Filter by project context: ecommerce, project-a, nexo, project-b, server, other
         brief: If true, returns ONLY the last diary entry with summary + mental_state + context_next.
                Use this at startup for fast context loading (~1K chars instead of full dump).

package/src/plugins/personal_plugins.py

@@ -0,0 +1,135 @@
+"""NEXO Personal Plugins — scaffold persistent MCP tools in NEXO_HOME/plugins."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from db import init_db
+from script_registry import create_script
+
+
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parents[1])))
+
+
+def _plugins_dir() -> Path:
+    path = NEXO_HOME / "plugins"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _safe_slug(value: str) -> str:
+    chars: list[str] = []
+    for ch in str(value or "").lower():
+        if ch.isalnum():
+            chars.append(ch)
+        elif ch in {"-", "_", " "}:
+            chars.append("-")
+    slug = "".join(chars).strip("-")
+    return slug or "plugin"
+
+
+def _template_path(name: str) -> Path | None:
+    candidates = [
+        NEXO_CODE.parent / "templates" / name,
+        NEXO_HOME / "templates" / name,
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _load_template() -> str:
+    template = _template_path("plugin-template.py")
+    if template:
+        return template.read_text()
+    return (
+        "from __future__ import annotations\n"
+        "import json\n\n"
+        "def handle_example_tool(payload_json: str = \"{}\") -> str:\n"
+        "    try:\n"
+        "        payload = json.loads(payload_json or \"{}\")\n"
+        "    except Exception as exc:\n"
+        "        return json.dumps({\"ok\": False, \"error\": f\"invalid json: {exc}\"}, ensure_ascii=False)\n"
+        "    return json.dumps({\"ok\": True, \"payload\": payload}, ensure_ascii=False)\n\n"
+        "TOOLS = [\n"
+        "    (handle_example_tool, \"nexo_example_tool\", \"Example personal MCP tool scaffold.\"),\n"
+        "]\n"
+    )
+
+
+def _render_plugin_template(*, plugin_stem: str, tool_name: str, description: str) -> str:
+    content = _load_template()
+    handler_name = f"handle_{plugin_stem.replace('-', '_')}"
+    content = content.replace("handle_example_tool", handler_name)
+    content = content.replace("nexo_example_tool", tool_name)
+    content = content.replace(
+        "Personal plugin scaffold created. Edit this handler in NEXO_HOME/plugins.",
+        description or f"Personal plugin scaffold for {plugin_stem}.",
+    )
+    content = content.replace(
+        "Example personal MCP tool scaffold. Edit it in NEXO_HOME/plugins.",
+        description or f"Personal MCP tool scaffold for {plugin_stem}.",
+    )
+    return content
+
+
+def handle_personal_plugin_create(
+    name: str,
+    description: str = "",
+    tool_name: str = "",
+    create_companion_script: bool = False,
+    script_runtime: str = "python",
+    force: bool = False,
+) -> str:
+    """Create a personal MCP plugin scaffold in NEXO_HOME/plugins.
+
+    Optionally also creates a companion script in NEXO_HOME/scripts.
+    """
+    init_db()
+    plugin_stem = _safe_slug(name)
+    filename = f"{plugin_stem}.py"
+    tool_name = (tool_name or f"nexo_{plugin_stem.replace('-', '_')}").strip()
+    plugin_path = _plugins_dir() / filename
+    if plugin_path.exists() and not force:
+        return json.dumps({
+            "ok": False,
+            "error": f"Plugin already exists: {plugin_path}",
+        }, ensure_ascii=False)
+
+    content = _render_plugin_template(
+        plugin_stem=plugin_stem,
+        tool_name=tool_name,
+        description=description or f"Personal MCP tool for {name}.",
+    )
+    plugin_path.write_text(content)
+
+    script_result = None
+    if create_companion_script:
+        script_result = create_script(
+            plugin_stem,
+            description=f"Companion script for plugin {plugin_stem}",
+            runtime=script_runtime,
+            force=force,
+        )
+
+    return json.dumps({
+        "ok": True,
+        "name": plugin_stem,
+        "tool_name": tool_name,
+        "plugin_path": str(plugin_path),
+        "companion_script": script_result,
+        "next_step": f"Load the plugin with nexo_plugin_load(filename='{filename}') after editing it.",
+    }, ensure_ascii=False)
+
+
+TOOLS = [
+    (
+        handle_personal_plugin_create,
+        "nexo_personal_plugin_create",
+        "Create a persistent personal MCP plugin scaffold in NEXO_HOME/plugins, optionally with a companion script in NEXO_HOME/scripts.",
+    ),
+]

package/src/plugins/update.py

@@ -341,11 +341,20 @@ def _rollback_npm_package(target_version: str) -> str | None:
     return None
 
 
-def _handle_packaged_update() -> str:
+def _emit_progress(progress_fn, message: str) -> None:
+    if callable(progress_fn):
+        try:
+            progress_fn(message)
+        except Exception:
+            pass
+
+
+def _handle_packaged_update(progress_fn=None) -> str:
     """Update a packaged (npm) install — no git repo available."""
     old_version = _read_version()
 
     # 1. Backup databases BEFORE any changes
+    _emit_progress(progress_fn, "Backing up runtime databases...")
     backup_dir, backup_err = _backup_databases()
     if backup_err:
         return f"ABORTED at backup: {backup_err}"
@@ -353,12 +362,14 @@ def _handle_packaged_update() -> str:
     # 2. Backup NEXO_HOME code tree BEFORE npm update
     #    postinstall copies hooks/core/plugins/scripts into NEXO_HOME,
     #    so we need a full snapshot to restore on failure.
+    _emit_progress(progress_fn, "Backing up runtime files...")
     code_backup_dir, code_err = _backup_code_tree()
     if code_err:
         return f"ABORTED at code tree backup: {code_err}"
 
     # 3. Run npm update (postinstall.js will migrate NEXO_HOME in-place)
     try:
+        _emit_progress(progress_fn, "Downloading and applying the latest npm package...")
         result = subprocess.run(
             ["npm", "update", "-g", "nexo-brain"],
             capture_output=True, text=True, timeout=120,
@@ -402,16 +413,19 @@ def _handle_packaged_update() -> str:
     errors = []
 
     # Reinstall pip deps for new version
+    _emit_progress(progress_fn, "Reconciling Python dependencies...")
     pip_err = _reinstall_pip_deps()
     if pip_err:
         errors.append(f"pip deps: {pip_err}")
 
     # Run migrations
+    _emit_progress(progress_fn, "Running runtime migrations...")
     mig_err = _run_migrations()
     if mig_err:
         errors.append(f"migrations: {mig_err}")
 
     # Verify server can still import
+    _emit_progress(progress_fn, "Verifying runtime import health...")
     verify_err = _verify_import()
     if verify_err:
         errors.append(f"verification: {verify_err}")
@@ -457,7 +471,7 @@ def _handle_packaged_update() -> str:
     return "\n".join(lines)
 
 
-def handle_update(remote: str = "origin", branch: str = "main") -> str:
+def handle_update(remote: str = "origin", branch: str = "main", progress_fn=None) -> str:
     """Pull latest NEXO code, backup databases, run migrations, and verify.
 
     Supports both git checkouts and packaged (npm) installs.
@@ -477,7 +491,7 @@ def handle_update(remote: str = "origin", branch: str = "main") -> str:
     """
     # Packaged install — no git repo
     if not _is_git_repo():
-        return _handle_packaged_update()
+        return _handle_packaged_update(progress_fn=progress_fn)
 
     steps_done = []
     old_commit = None
@@ -485,6 +499,7 @@ def handle_update(remote: str = "origin", branch: str = "main") -> str:
 
     try:
         # Step 1: Check dirty (full worktree)
+        _emit_progress(progress_fn, "Checking repository state...")
         dirty_err = _check_dirty()
         if dirty_err:
             return f"ABORTED: {dirty_err}"
@@ -498,12 +513,14 @@ def handle_update(remote: str = "origin", branch: str = "main") -> str:
             return "ABORTED: Not a git repository or git not available."
 
         # Step 2: Backup databases
+        _emit_progress(progress_fn, "Backing up runtime databases...")
         backup_dir, backup_err = _backup_databases()
         if backup_err:
             return f"ABORTED at backup: {backup_err}"
         steps_done.append("backup")
 
         # Step 3: git pull
+        _emit_progress(progress_fn, "Pulling latest source changes...")
         rc, pull_out, pull_err = _git("pull", remote, branch)
         if rc != 0:
             return f"ABORTED at git pull: {pull_err or pull_out}"
@@ -517,6 +534,7 @@ def handle_update(remote: str = "origin", branch: str = "main") -> str:
 
         # Step 5: Reinstall pip dependencies if requirements.txt changed
         if deps_changed or version_changed:
+            _emit_progress(progress_fn, "Reconciling Python dependencies...")
             pip_err = _reinstall_pip_deps()
             if pip_err:
                 raise RuntimeError(f"Pip install failed: {pip_err}")
@@ -524,12 +542,14 @@ def handle_update(remote: str = "origin", branch: str = "main") -> str:
 
         # Step 6: Run migrations if version changed
         if version_changed:
+            _emit_progress(progress_fn, "Running runtime migrations...")
             mig_err = _run_migrations()
             if mig_err:
                 raise RuntimeError(f"Migration failed: {mig_err}")
             steps_done.append("migrations")
 
         # Step 7: Verify import
+        _emit_progress(progress_fn, "Verifying runtime import health...")
         verify_err = _verify_import()
         if verify_err:
             raise RuntimeError(f"Verification failed: {verify_err}")
@@ -540,6 +560,7 @@ def handle_update(remote: str = "origin", branch: str = "main") -> str:
         try:
             cron_sync_path = SRC_DIR / "crons" / "sync.py"
             if cron_sync_path.exists():
+                _emit_progress(progress_fn, "Syncing core cron definitions...")
                 r = subprocess.run(
                     [sys.executable, str(cron_sync_path)],
                     capture_output=True, text=True, timeout=30,
@@ -557,6 +578,7 @@ def handle_update(remote: str = "origin", branch: str = "main") -> str:
 
         # Step 9: Sync hooks to NEXO_HOME
         try:
+            _emit_progress(progress_fn, "Syncing core Claude hooks...")
             _sync_hooks_to_home()
             steps_done.append("hook-sync")
         except Exception as e: