Fusion - the Fusion 360 Bridge

@@ -6431,11 +6431,18 @@ def _orchestrate_demo_tour(args: dict) -> dict:             pass      def _run():-        if not args.get("foreground"):+        fg = bool(args.get("foreground"))+        if not fg:             begin_background_envelope(float(est + 60))         done_est = 0         try:             for key, label, dur in steps:+                if not fg:+                    # RE-ARM per step: one est-sized envelope EXPIRED mid-tour on real runs+                    # (485-890s vs ~376s armed) and later steps stole the user's foreground+                    # while they typed in other threads (John, live during ab's demo,+                    # 2026-08-16). Nesting is refcounted, so re-arming is free.+                    begin_background_envelope(float(dur * 3 + 240))                 state.update(step=key, stepLabel=label,                              percent=int(100 * done_est / est),                              elapsedSec=int(time.time() - state["started"]))@@ -7724,19 +7731,52 @@ def dispatch_command(command: str, args: dict, caller_identity: dict = None) ->         "show_symbol", "show_footprint", "show_3d_package", "make_test_project",         "bind_library_3d", "show_library", "show_project",     }+    _ran_backgrounded = False     if command in _WINDOW_RAISING:         if (args or {}).get("foreground"):-            # The USER's choice, always honored (John, 2026-08-15): they may want to WATCH.-            # No envelope - the window may come to front and stay there.-            args = {k: v for k, v in args.items() if k != "foreground"}+            # Foreground is allowed but never free (John, 2026-08-16): the CALLER must say+            # WHY, and the user gets that reason as an ab caption for ~3s BEFORE the steal,+            # so they know what is happening and can yield (or object). No reason = refuse+            # with a teaching hint - same pattern as every reason-gated Adom verb.+            fg_reason = str(args.get("foregroundReason") or "").strip()+            if not fg_reason:+                return {"success": False, "errorCode": "foreground_reason_required",+                        "error": "foreground:true needs foregroundReason (a short user-facing sentence).",+                        "_hint": ("Fusion verbs ALWAYS run in the background so the user is never "+                                  "interrupted mid-typing. If the user genuinely wants to WATCH, re-call "+                                  "with foreground:true AND foregroundReason:\"<why, in words the user "+                                  "will read>\" - it is shown as an ab caption for 3 seconds before the "+                                  "window comes forward, so they can yield.")}+            try:+                ad_client.notify("Fusion is coming to the foreground",+                                 fg_reason + " (Requested by your AI - Fusion verbs otherwise always "+                                 "run in the background.)", level="info", reach_user=True)+                _time.sleep(3.0)   # the user's 3-second heads-up BEFORE any focus change+            except Exception:+                pass+            args = {k: v for k, v in args.items() if k not in ("foreground", "foregroundReason")}         else:             _sec = ADDIN_COMMAND_TIMEOUTS.get(command, 60) + 20             begin_background_envelope(float(_sec), minimize=(command == "start"))+            _ran_backgrounded = True++    def _annotate_background(res):+        # Tell the CALLING AI what just happened window-wise (John, 2026-08-16): the verb+        # ran under the background envelope - no focus was taken, nothing to apologize for,+        # and the AI should not "helpfully" foreground anything afterward.+        if _ran_backgrounded and isinstance(res, dict):+            res.setdefault("windowEtiquette", "background")+            note = ("Window opened/changed in the BACKGROUND - the user's focus was NOT touched. "+                    "Render results via fusion_state. Only pass foreground:true (with "+                    "foregroundReason) if the USER asked to watch.")+            h = res.get("_hint")+            res["_hint"] = (h + " " + note) if isinstance(h, str) and note not in h else (h or note)+        return res      # Direct handlers (don't need the add-in)     handler = COMMAND_HANDLERS.get(command)     if handler is not None:-        return handler(fusion_info, args)+        return _annotate_background(handler(fusion_info, args))      # Check if Fusion is installed and running before any add-in-dependent command.     # We do NOT auto-launch — that causes 60s+ hangs when Fusion isn't running.@@ -7941,7 +7981,7 @@ def dispatch_command(command: str, args: dict, caller_identity: dict = None) ->                 pass             _set_long_command(command)             try:-                return _proxy_to_addin(addin_cmd, args, timeout=proxy_timeout)+                return _annotate_background(_proxy_to_addin(addin_cmd, args, timeout=proxy_timeout))             finally:                 _clear_long_command()         result = _proxy_to_addin(addin_cmd, args, timeout=proxy_timeout)@@ -7950,7 +7990,7 @@ def dispatch_command(command: str, args: dict, caller_identity: dict = None) ->         # blind. Read-only verbs are excluded to avoid per-call screenshot latency.         if command in MUTATING_COMMANDS:             result = _merge_dialog_array(result)-        return result+        return _annotate_background(result)      # Unknown command — check installation/running status for helpful errors     if not fusion_info.get("installed"):