Fusion - the Fusion 360 Bridge

@@ -3,6 +3,38 @@ All notable changes to the Adom Bridge Fusion 360 bridge, newest first. Canonical: https://wiki.adom.inc/adom/fusion-bridge · GitHub backup: `adom-inc/fusion-bridge` +## 1.12.9 (unreleased)++The bridge no longer restarts Fusion over a busy add-in, and a restart it does need no longer kills Fusion over+unsaved work.++- A busy add-in is never mistaken for a missing one. While a long native Fusion call holds the add-in's main+  thread, not even `/status` or `/health` answers, and the gate read that silence as "the add-in was installed+  while Fusion was running" and restarted Fusion. On a person's own PC that killed Fusion with their documents+  open six times between 2026-10-14 and 2026-10-28 (a 93 s script was in flight on 10-28). Now silence counts as+  work whenever there is evidence the add-in is loaded: one of the exe's own requests to it is still in flight,+  or it answered earlier inside the same Fusion process and its port still takes connections. The verb gate, the+  timeout diagnosis, the readiness launch observer (which restarted Fusion after about 3 minutes of silence) and+  a warm `fusion_start` all ask for that evidence first and answer `fusion_addin_busy`. `fusion_readiness` and+  `fusion_state` report it as `addinBusy`, and the dashboard no longer restarts over it. A request in flight also+  counts as a long operation for the hang verdict.+- `restartPolicy` `auto` (the default) stops short of losing work. When the add-in cannot save, Fusion is closed+  the way a person closes it instead of killed: it closes at once when nothing is unsaved, and a save prompt for+  a document the bridge did not make (or a never-saved document) ends the restart with `restart_needs_decision`,+  with nothing killed or discarded. For 30 minutes after that the restart is asked for instead of retried. A stop+  that did not finish is no longer escalated to a kill. The old behaviour is `restartPolicy: force`, for a machine+  only an AI drives. The ledger's restart summary now says what happened: it said "Documents were saved first"+  when the save step had failed and Fusion was killed.+- `fusion_stop` waits for heavy designs: up to `closeTimeoutSec` (default 120; it was 15 s). A save prompt for a+  document the bridge made is answered Don't Save; one for anyone else's work is cancelled and the stop fails+  with `unsaved_work`.+- Documents a caller opens are no longer registered as bridge scratch. Any document that appeared during a+  window-raising verb was registered, so a user's assembly reopened with `fusion_open_by_urn` became "the+  bridge's": its save prompt would be answered Don't Save and a restart could discard it. Now only documents a+  verb made (not saved cloud documents, which were opened) and the bridge's own Save As are registered, and+  nothing Fusion opens at launch. The registry evicts its oldest entry when full; it used to evict the+  alphabetically first.+ ## 1.12.8 (2026-10-28, insiders)  KiCad's remaining core and app proposals, and a close that never saves unasked. 271 verbs.

@@ -98,7 +98,7 @@ Short entries, newest behavior first in each guide. The [changelog](CHANGELOG.md | Native viewport frame | `fusion_state` | The reply carries `nativeViewport`, `geometry` and `windowPixels`, so a blank window capture is reported as blank and the frame Fusion itself renders is there to use. | | APS zero-result fallback | `fusion_aps_search` | A zero from the server index never stands alone. The reply carries `data.fallback` and `data.completeness`, and sibling folders are listed through the Data API. | | Caller-aware prove | `fusion_create_library`, `fusion_install_library_bundle`, `fusion_prove_result` | An AI thread binds and places only (`verdict: bound_not_proven`). Web control proves. `prove:true` or `prove:false` always wins. |-| Restart policy | `restartPolicy`, `allowRestart`, `fusion_restart_for_addin` | Under the default `auto` the bridge restarts Fusion itself when the add-in needs it. Chains never restart Fusion unless the caller passes `allowRestart:true`. |+| Restart policy | `restartPolicy`, `allowRestart`, `fusion_restart_for_addin` | Under the default `auto` the bridge restarts Fusion itself when the add-in needs it, never for a busy add-in and never over unsaved work it could not save. Chains never restart Fusion unless the caller passes `allowRestart:true`. | | Sign-in short-circuit | `needs_signin` | Every add-in verb answers `errorCode: needs_signin` in under a second while Fusion is signing in. |  ### The schematic front door: `fusion_schematic`@@ -154,9 +154,11 @@ and expired like any other, and Fusion's own tool windows do not count as dialog  - `restartPolicy` (in `~/.adom/fusion-bridge/prefs.json`, or the env var   `ADOM_FUSION_RESTART_POLICY`) defaults to `auto`: the bridge restarts Fusion in the background-  when the add-in needs it (`addin_restarting`), saves what Fusion can save, and records the-  restart in the action ledger (`fusion_action_ledger`). `ask` keeps the confirmation toast and-  the wait, for a machine a person shares with the AI.+  when the add-in needs it (`addin_restarting`), saves what Fusion can save, stops short of any+  unsaved work it could not save (`restart_needs_decision`), and records the restart in the action+  ledger (`fusion_action_ledger`). `ask` keeps the confirmation toast and the wait, for a machine a+  person shares with the AI. `force` discards and kills when that is what it takes, for a machine+  only an AI drives. A busy add-in (`fusion_addin_busy`, readiness `addinBusy`) is never restarted. - Chains (`fusion_create_library`, `fusion_install_library_bundle`) never restart Fusion on their   own. `allowRestart:true` with `restartReason` is the only way, and the restart is recorded in   `restarts[]` on `fusion_prove_result`. A long operation in flight answers `fusion_addin_busy`

@@ -3967,7 +3967,7 @@         "tookSec": "float"       },       "statusVerb": null,-      "summary": "ASYNC: returns immediately (started:true) and restarts Fusion in the background, SAVING the user's open documents first; poll fusion_readiness until ready with the new addinVersion (a restart takes 60-120s, longer than the relay budget; pass wait:true for the old blocking form). Finish add-in setup by restarting Fusion. Call this when any verb returns errorCode addin_restart_required (the add-in was installed/updated while Fusion was already open, and Fusion only loads add-ins at launch). ASK THE USER FIRST when a human is present - the failing verb's payload carries userMessage plus openDocuments/unsavedDocuments so you can show them what is open. Refuses with unsaved_named_document rather than discarding a never-saved document.",+      "summary": "ASYNC: returns immediately (started:true) and restarts Fusion in the background, SAVING the user's open documents first; poll fusion_readiness until ready with the new addinVersion (a restart takes 60-120s, longer than the relay budget; pass wait:true for the old blocking form). Finish add-in setup by restarting Fusion. Call this when any verb returns errorCode addin_restart_required (the add-in was installed/updated while Fusion was already open, and Fusion only loads add-ins at launch). A busy add-in (errorCode fusion_addin_busy, readiness addinBusy) is NOT a reason: it is loaded and working. ASK THE USER FIRST when a human is present - the failing verb's payload carries userMessage plus openDocuments/unsavedDocuments so you can show them what is open. Refuses with unsaved_named_document rather than discarding a never-saved document, and with restart_needs_decision (nothing killed or discarded) when Fusion asks to save work the bridge did not make; restartPolicy force (an AI-only machine) discards and kills instead.",       "timeoutSeconds": 300     },     {@@ -5520,17 +5520,19 @@     {       "example": {},       "input": {+        "closeTimeoutSec": "optional number, default 120: how long to wait for Fusion's windows to close",         "skipCleanClose": "optional bool"       },       "longRunning": false,       "name": "fusion_stop",       "output": {         "output": "str",-        "success": "bool"+        "success": "bool",+        "unsavedWork": "[{window, prompt}] when unsaved work stopped it"       },       "statusVerb": null,-      "summary": "Gracefully STOP Fusion 360: close docs cleanly + WM_CLOSE, then wait. NO force-kill - the clean opposite of fusion_start. If a window will not close it returns failure; use fusion_kill then.",-      "timeoutSeconds": 60+      "summary": "Gracefully STOP Fusion 360: close docs cleanly + WM_CLOSE, then wait up to closeTimeoutSec (default 120; heavy designs take minutes to close). NO force-kill - the clean opposite of fusion_start. A save prompt for a document the bridge made is answered Don't Save; one for anyone else's unsaved work is cancelled and the stop fails with errorCode unsaved_work (nothing saved or lost). If a window will not close it returns failure; use fusion_kill then.",+      "timeoutSeconds": 300     },     {       "example": {},

@@ -667,7 +667,9 @@ fn wait_ready_with_heal(app: &Arc<App>, target: &str, max_wait_s: u64) -> bool {             }             if !restarted && t0.elapsed() > Duration::from_secs(90)                 && st["running"].as_bool().unwrap_or(false)-                && !st["addinResponding"].as_bool().unwrap_or(false) {+                && !st["addinResponding"].as_bool().unwrap_or(false)+                // a loaded add-in that is busy is not "did not start": never restart over it+                && st["addinBusy"].is_null() {                 restarted = true;                 app.hub.broadcast("toast", &serde_json::json!({                     "message": "Fusion is up but its bridge add-in did not start - restarting Fusion for you", "kind": ""}));

@@ -354,8 +354,8 @@ _T = [     ("fusion_create_library", "ONE-CALL library creation for web-control (one call = one consent). EVERY LIBRARY IS MULTI-PART - a single-part library is simply parts:[one entry], and there is no separate single-part verb to choose. Pass parts:[{package, lbrPath, modelPath}] for any number of parts; the older {libraryPath, stepPath} shape still works and is normalised into a one-element parts list, so both run the identical code path and the ETA scales with the part count either way. TWO entry shapes: A) {libraryPath, stepPath} - a ready .lbr plus the 3D; B) {kicadSymbolPath, kicadFootprintPath, stepPath, pinMap?} - KiCad sources; needs adom-lbr, which is Linux-container-only by platform rule, so on Windows/Mac boxes shape B refuses IMMEDIATELY (adom_lbr_unavailable, before any staging or Fusion launch - fusion_readiness reports kicadIngest up front). Convert at AUTHORING time in a container and use shape A. pinMap = explicit {pinName: padName} for when pin numbers do not match pad names (BGA-style). Chains convert -> bind 3D -> prove (four evidence frames + verdict) in the BACKGROUND and returns immediately; poll fusion_prove_result (stage narrates; top-level `verdict` proven/not_proven is the score - `stage:done` only means the chain finished). EVERY PART IS PROVED, not just the first: a 10-component library streams 40 evidence frames, FOUR per component (symbol, footprint, 3d, ganged) in assembly order, each tagged with `part` so a front end can group them as they arrive, and `provedParts[]` reports per-part pass/fail. The library is proven only if EVERY part is - one good part does not vouch for nine unchecked ones. On the FINAL fetch pass {inlineFrames:true} to get each evidence frame as a base64 thumbnailDataUrl a browser can render (plain polls return box paths only). The chain closes its library document on success AND failure - batches need no between-part sweeping. stepPath is required for a PROVEN library - no real 3D body without it.", {"parts": "optional [{package, lbrPath, modelPath}] - THE canonical shape, any count", "libraryPath": "optional str (shape A, or output path for B)", "kicadSymbolPath": "optional str", "kicadFootprintPath": "optional str", "stepPath": "optional str (required for proven)", "pinMap": "optional {pinName: padName}", "name": "optional str"}, {"started": "bool", "statusVerb": "str"}, 30, "fusion_prove_result", True, {"libraryPath": "C:/Temp/PART.lbr", "stepPath": "C:/Temp/PART.step"}),     ("fusion_start", "Launch Fusion 360 (if needed) and wait for the AdomBridge add-in to be ready.",      {"prove": "optional bool. Default from the CALLER: an AI thread (caller headers set) binds and places only; web control / anonymous callers prove (four evidence frames per part, about 300 s per library). Explicit true/false always wins. From an AI thread, look at one part later with fusion_capture_library_views {packages} (issue #88)", "allowRestart": "optional bool (default false). The chain NEVER relaunches Fusion or restarts the add-in on its own: when the add-in does not answer it surfaces addin_restart_required and waits (resumable). allowRestart:true with restartReason lets it restart, recorded in restarts[] on fusion_prove_result (issue #87)", "restartReason": "optional str shown to the human when allowRestart is used"}, {"success": "bool", "addinReady": "bool", "status": "str"}, 150, None, True, {}),-    ("fusion_stop", "Gracefully STOP Fusion 360: close docs cleanly + WM_CLOSE, then wait. NO force-kill - the clean opposite of fusion_start. If a window will not close it returns failure; use fusion_kill then.",-     {"skipCleanClose": "optional bool"}, {"success": "bool", "output": "str"}, 60, None, False, {}),+    ("fusion_stop", "Gracefully STOP Fusion 360: close docs cleanly + WM_CLOSE, then wait up to closeTimeoutSec (default 120; heavy designs take minutes to close). NO force-kill - the clean opposite of fusion_start. A save prompt for a document the bridge made is answered Don't Save; one for anyone else's unsaved work is cancelled and the stop fails with errorCode unsaved_work (nothing saved or lost). If a window will not close it returns failure; use fusion_kill then.",+     {"skipCleanClose": "optional bool", "closeTimeoutSec": "optional number, default 120: how long to wait for Fusion's windows to close"}, {"success": "bool", "output": "str", "unsavedWork": "[{window, prompt}] when unsaved work stopped it"}, 300, None, False, {}),     ("fusion_kill", "Force-KILL Fusion 360 (taskkill /F) - the desperate path for when fusion_stop cannot close it (stuck modal / wedged process). Closes docs cleanly first when reachable.",      {"skipCleanClose": "optional bool"}, {"success": "bool", "output": "str"}, 30, None, False, {}),     ("fusion_close_window", "Close a DIALOG window by hwnd (WM_CLOSE, like clicking X) - for dialogs without Cancel/Escape handling (e.g. Recovered Documents). NOT a document closer; refuses without hwnd. Get the hwnd from a screenshot's dialogs array or desktop_list_windows. (Doc drift caught by the verb test suite 2026-08-14: this was described as 'close the active document' while the handler required hwnd.)",@@ -679,7 +679,7 @@ _T = [     ("fusion_live_feed", "A ~1 fps look INTO Fusion while the bridge drives it, kept as a BOX-SIDE ring buffer (~10 min). Each tick records the Fusion main window (kind:main - the video) and every owned popup over it (kind:popup - dialogs, Browser/tool panels, the Adom banner; Fusion draws these as separate windows a main capture omits), each a path on this machine tied to its tick. Drain from the container with {action:frames, since:<tick>}, read_file each path, and publish where a human looks - tools/live_feed_drain.py does exactly that into shotlog. Proof frames are NOT here: fusion_prove_result evidence[] carries kind:proof with step labels, so the three kinds are distinguishable at the source. Exists so a human can see open tabs and dialogs during boot or a restart instead of guessing.",      {"action": "start|stop|status|frames", "intervalSec": "optional float (default 1.0)", "maxSec": "optional float (default 600)", "since": "frames only: return ticks newer than this"},      {"success": "bool", "running": "bool", "tick": "int", "frames": "[{tick, kind:main|popup, path, title, at}]"}, 15, None, True, {"action": "frames", "since": 0}),-    ("fusion_restart_for_addin", "ASYNC: returns immediately (started:true) and restarts Fusion in the background, SAVING the user's open documents first; poll fusion_readiness until ready with the new addinVersion (a restart takes 60-120s, longer than the relay budget; pass wait:true for the old blocking form). Finish add-in setup by restarting Fusion. Call this when any verb returns errorCode addin_restart_required (the add-in was installed/updated while Fusion was already open, and Fusion only loads add-ins at launch). ASK THE USER FIRST when a human is present - the failing verb's payload carries userMessage plus openDocuments/unsavedDocuments so you can show them what is open. Refuses with unsaved_named_document rather than discarding a never-saved document.",+    ("fusion_restart_for_addin", "ASYNC: returns immediately (started:true) and restarts Fusion in the background, SAVING the user's open documents first; poll fusion_readiness until ready with the new addinVersion (a restart takes 60-120s, longer than the relay budget; pass wait:true for the old blocking form). Finish add-in setup by restarting Fusion. Call this when any verb returns errorCode addin_restart_required (the add-in was installed/updated while Fusion was already open, and Fusion only loads add-ins at launch). A busy add-in (errorCode fusion_addin_busy, readiness addinBusy) is NOT a reason: it is loaded and working. ASK THE USER FIRST when a human is present - the failing verb's payload carries userMessage plus openDocuments/unsavedDocuments so you can show them what is open. Refuses with unsaved_named_document rather than discarding a never-saved document, and with restart_needs_decision (nothing killed or discarded) when Fusion asks to save work the bridge did not make; restartPolicy force (an AI-only machine) discards and kills instead.",      {"save": "optional bool (default true) - save open documents before restarting"},      {"success": "bool", "addinReady": "bool", "tookSec": "float", "steps": "[{step, ok}]"},      300, None, False, {"save": True}),

@@ -19,21 +19,35 @@ where Fusion had been removed.  **Never ask the user to restart Fusion or enable the add-in.** That is the bridge's job. -### `restartPolicy`: auto or ask+### `restartPolicy`: auto, ask or force  Fusion loads add-ins only at launch, so an add-in that was installed or updated while Fusion was open needs a restart. Who decides is a pref: `restartPolicy` in `~/.adom/fusion-bridge/prefs.json`, or the env var `ADOM_FUSION_RESTART_POLICY`. The default is `auto`. -- **`auto`**: the AI is the only thing driving Fusion on that box, so the open documents are the-  AI's documents. The bridge restarts Fusion in the background and answers `addin_restarting`.-  No confirmation toast is raised. `fusion_restart_for_addin` never refuses under auto: documents-  Fusion can save are saved, never-saved scratch is discarded (named in `discarded` and in the-  action ledger), and when the add-in cannot save at all the restart is a kill plus a start. The-  restart is recorded in the action ledger (`fusion_action_ledger`) with its summary.+**A busy add-in never needs a restart.** While a long native Fusion call holds the add-in's main+thread, not even its status probe answers. The bridge treats that silence as work, not as an add-in+Fusion never loaded, whenever it has evidence: one of its own requests to the add-in is still in+flight, or the add-in answered earlier inside the same Fusion process (and its port still takes+connections). Every restart path asks for that evidence first: the verb gate, the timeout+diagnosis, the readiness launch observer and a warm `fusion_start`. The reply is+`fusion_addin_busy` with the evidence, and readiness reports it as `addinBusy`. Before this, a+93-second script read as a missing add-in and the bridge restarted Fusion with the user's+documents open.++- **`auto`**: the bridge restarts Fusion in the background and answers `addin_restarting`. No+  confirmation toast is raised. Documents Fusion can save are saved first. It stops short of losing+  work: when the add-in cannot save, Fusion is closed the way a person closes it (it closes at once+  when nothing is unsaved), and a never-saved document or a save prompt for a document the bridge+  did not make ends the restart with `restart_needs_decision`. Nothing is killed or discarded, and+  for the next 30 minutes a restart is asked for (the toast) instead of tried again. The restart is+  recorded in the action ledger (`fusion_action_ledger`) with a summary of what each step did. - **`ask`**: for a machine a person shares with the AI. A verb that needs the restart answers   `addin_restart_required` with `userMessage`, `openDocuments` and `unsavedDocuments`, the   confirmation toast is raised, and the bridge waits for the person.+- **`force`**: the behaviour `auto` had from 1.10.6 to 1.12.7, for a machine only an AI drives:+  never-saved documents are discarded (named in `discarded` and in the ledger), and when the+  add-in cannot save at all the restart is a kill plus a start.  **The bridge never restarts Fusion over a dialog.** A dialog in front of Fusion is read through UIA (title, text, button names) and expired safely: the known ones through their rule, the unknown

@@ -149,11 +149,19 @@ pub fn addin_restart_info(ctx: &Ctx, args: &Value, pass: &dyn Fn(&str, Value) ->     let yours: Vec<String> = match &unames { Some(u) => { let y = user_unsaved_docs(&ctx.state_dir, u); info["userUnsaved"] = json!(y); info["autoRestart"] = json!(y.is_empty()); y } None => { info["autoRestart"] = json!(false); vec![] } };     let policy = crate::lifecycle::restart_policy(&ctx.state_dir);     info["restartPolicy"] = json!(policy);-    let yours = if policy == "auto" {-        // every open document is the AI's own on an Adom box: nothing to ask, the bridge restarts+    let declined = crate::lifecycle::auto_restart_declined_recently(&ctx.state_dir);+    if declined { info["autoRestartDeclinedRecently"] = json!(true); }+    let yours = if policy == "force" {+        // an AI-only machine: every open document is the AI's own, nothing to ask         if !yours.is_empty() { info["userUnsavedIgnored"] = json!(yours); info["userUnsaved"] = json!([]); }         info["autoRestart"] = json!(true);-        info["userMessage"] = json!("Fusion is restarting itself to load the Adom add-in (restartPolicy auto). Open documents are saved where Fusion can save them; never-saved scratch is discarded.");+        info["userMessage"] = json!("Fusion is restarting itself to load the Adom add-in (restartPolicy force). Open documents are saved where Fusion can save them; never-saved documents are discarded.");+        Vec::new()+    } else if policy == "auto" && yours.is_empty() && !declined {+        // no unsaved work that is not the bridge's (or none known): restart without asking; the+        // restart itself stops short of any unsaved work it meets and asks then+        info["autoRestart"] = json!(true);+        info["userMessage"] = json!("Fusion is restarting itself to load the Adom add-in (restartPolicy auto). Open documents are saved first; nobody's unsaved work is discarded.");         Vec::new()     } else { yours };     if fire_toast && info["autoRestart"].as_bool() != Some(true) {

@@ -131,9 +131,9 @@ fn note_bridge_doc(state_dir: &std::path::Path, name: &str) {     let p = state_dir.join("prefs.json");     let mut d: Value = std::fs::read_to_string(&p).ok().and_then(|t| serde_json::from_str(t.trim_start_matches('\u{feff}')).ok()).unwrap_or(json!({}));     let mut docs: Vec<String> = d["bridgeDocs"].as_array().map(|a| a.iter().filter_map(|v| v.as_str().map(str::to_string)).collect()).unwrap_or_default();+    // oldest first: a sorted list evicted the alphabetically first name, not the oldest one     if !docs.contains(&n) { docs.push(n); }     while docs.len() > 24 { docs.remove(0); }-    docs.sort();     d["bridgeDocs"] = json!(docs);     let tmp = p.with_extension("json.tmp");     if std::fs::write(&tmp, serde_json::to_string_pretty(&d).unwrap_or_default()).is_ok() { let _ = std::fs::rename(&tmp, &p); }

@@ -72,6 +72,23 @@ pub fn snapshot_open_docs(call: &dyn Fn(&str, Value, u64) -> Value) -> Vec<Strin     v.sort(); v.dedup(); v } +/// Each open document's lowercase name and whether it is a saved cloud document (empty on failure).+fn snapshot_open_docs_detail(call: &dyn Fn(&str, Value, u64) -> Value) -> Vec<(String, bool)> {+    let r = call("document_info", json!({}), 5);+    if r["success"].as_bool() != Some(true) { return vec![]; }+    r["data"]["openDocuments"].as_array().map(|a| a.iter().filter_map(|d| {+        let n = d["name"].as_str().filter(|n| !n.is_empty())?.trim_end_matches('*').trim().to_lowercase();+        Some((n, d["isCloudDocument"].as_bool() == Some(true)))+    }).collect()).unwrap_or_default()+}++/// Is a document that appeared while `cmd` ran the bridge's own scratch? A saved cloud document+/// that appeared was OPENED (open_by_urn, a script's documents.open): it is its owner's work, and+/// registering it let the save-prompt sentinel answer Don't Save for it and the restart discard+/// it. So were the documents Fusion opens at launch (recovered work). Only a document the verb+/// made, or a Save As the bridge itself did, is scratch.+pub fn appeared_doc_is_scratch(cmd: &str, cloud: bool) -> bool { cmd != "start" && (!cloud || cmd == "save_to_cloud") }+ fn bridge_docs(state_dir: &Path) -> Vec<String> {     crate::small_verbs::get_pref(state_dir, "bridgeDocs").and_then(|v| v.as_array().map(|a| a.iter().filter_map(|x| x.as_str().map(str::to_string)).filter(|s| s.len() >= 3).collect())).unwrap_or_default() }@@ -280,7 +297,11 @@ pub fn post(state_dir: &Path, caller: &Caller, cmd: &str, args: &Value, mut res:         // call plus a 14 s timeout diagnosis (2026-09-07, the routing test's 60 s relay window)         let quick = |verb: &str, a: Value, _t: u64| crate::addin::addin_http(verb, &a, 3);         let _ = call;-        for name in snapshot_open_docs(&quick) { if !before.contains(&name) && !name.is_empty() && name != "untitled" { crate::chains::note_bridge_doc_pub(state_dir, &name); eprintln!("[fusion-bridge] registered {name:?} as a bridge doc (it appeared while we drove)"); } }+        for (name, cloud) in snapshot_open_docs_detail(&quick) {+            if before.contains(&name) || name.is_empty() || name == "untitled" { continue; }+            if appeared_doc_is_scratch(cmd, cloud) { crate::chains::note_bridge_doc_pub(state_dir, &name); eprintln!("[fusion-bridge] registered {name:?} as a bridge doc (it appeared while we drove)"); }+            else { eprintln!("[fusion-bridge] {name:?} appeared during {cmd} but is an existing document someone opened, not bridge scratch"); }+        }     }     if SHOW_SURFACE_VERBS.contains(&cmd) {         for k in ["name", "deviceset", "libraryPath", "fileName", "query"] { if let Some(v) = args[k].as_str().filter(|s| !s.is_empty()) { crate::chains::note_bridge_doc_pub(state_dir, v); } }@@ -364,5 +385,18 @@ mod tests {         let _ = std::fs::remove_dir_all(&d);     }     #[test]+    fn opened_documents_are_not_bridge_scratch() {+        use super::appeared_doc_is_scratch as scratch;+        // 2026-10-28: four of the user's assemblies, reopened with open_by_urn, were registered+        assert!(!scratch("open_by_urn", true));+        assert!(!scratch("run_modeling_script", true));+        // Fusion's own launch (recovered documents) is never the bridge's+        assert!(!scratch("start", false));+        // what a verb made is scratch, and so is the bridge's own Save As+        assert!(scratch("import_step", false));+        assert!(scratch("make_3d_package", false));+        assert!(scratch("save_to_cloud", true));+    }+    #[test]     fn b64_matches_python() { assert_eq!(super::b64(b"hello"), "aGVsbG8="); assert_eq!(super::b64(b""), ""); assert_eq!(super::b64(b"ab"), "YWI="); } }

@@ -13,7 +13,27 @@ use fusion_core::ab::{AbClient, Loopback};  fn now_f() -> f64 { std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_secs_f64()).unwrap_or(0.0) } -fn health_probe(timeout: Duration) -> bool { ureq::get("http://127.0.0.1:8774/health").timeout(timeout).call().is_ok() }+fn health_probe(timeout: Duration) -> bool {+    let ok = ureq::get("http://127.0.0.1:8774/health").timeout(timeout).call().is_ok();+    if ok { crate::addin::note_answered(); }+    ok+}++static BUSY_NOTED_AT: std::sync::Mutex<f64> = std::sync::Mutex::new(0.0);++/// The reply for a silent add-in that is loaded and working, ledgered at most once a minute.+pub fn busy_not_missing(state_dir: &std::path::Path, cmd: &str, ev: &Value) -> Value {+    let mut at = BUSY_NOTED_AT.lock().unwrap();+    if now_f() - *at > 60.0 {+        *at = now_f();+        crate::fusion_prefs::action_ledger(state_dir, "addin_busy_not_restarted", json!({"forCommand": cmd, "evidence": ev}));+    }+    let mut r = json!({"success": false, "errorCode": "fusion_addin_busy", "hostResponding": true, "addinLoaded": true,+        "error": "The Adom add-in is loaded but not answering right now: it is working. A long command or a heavy Fusion operation holds its main thread and starves even its status probe. It was not installed while Fusion was running, so a restart would not help.",+        "_hint": "WAIT and re-poll fusion_readiness; do not restart Fusion (a restart closes every open document and loses the work in flight). The add-in answers again when the operation in front of it finishes."});+    if let Some(o) = ev.as_object() { for (k, v) in o { r[k] = v.clone(); } }+    r+}  /// `wait_for_addin(timeout)`: the health endpoint, once a second. pub fn wait_for_addin(seconds: u64) -> bool {@@ -148,6 +168,13 @@ pub fn start(ctx: &Ctx, _args: &Value) -> Value {             }         }         if !addin_ok {+            // silent is not missing: an add-in that answered inside this Fusion, or holds one of+            // our requests, is working, and a kill would lose that work and every open document+            if let Some(ev) = crate::addin::loaded_evidence(&ctx.pids) {+                let mut r = busy_not_missing(&sd, "start", &ev);+                r["alreadyRunning"] = json!(true); r["startKind"] = json!("warm");+                return r;+            }             eprintln!("[fusion-bridge] warm start found NO add-in after a ~30s persistence window (never busy, never answered) - restarting Fusion so the add-in loads (issue #39, #41 busy guard, + the 2026-08-22 library-matrix persistence gate)");             let _ = crate::lifecycle::kill(ctx, &json!({}));             std::thread::sleep(Duration::from_secs(3));@@ -343,6 +370,10 @@ pub fn gate(ctx: &Ctx, cmd: &str, args: &Value) -> Option<Value> {         }         crate::lifecycle::DialogGate::Clear => {}     }+    // Silence alone never means "not loaded": an add-in that answered inside this Fusion, or that+    // holds one of our requests, is loaded and working. Only an add-in with no such evidence goes+    // on to the restart below.+    if let Some(ev) = crate::addin::loaded_evidence(&ctx.pids) { return Some(busy_not_missing(&ctx.state_dir, cmd, &ev)); }     let ri = crate::chainexec::addin_restart_info(ctx, &json!({"fireToast": true}), &|v, a| crate::addin::addin_http(v, &a, 8));     if ri["autoRestart"].as_bool() == Some(true) {         let started = begin_auto_addin_restart(ctx);

@@ -273,8 +273,10 @@ struct Snapshot { at: Instant, body: Value } static SNAPSHOT: Mutex<Option<Snapshot>> = Mutex::new(None);  fn addin_probe() -> Value {-    ureq::get("http://127.0.0.1:8774/status").timeout(Duration::from_millis(1500)).call().ok()-        .and_then(|r| r.into_json::<Value>().ok()).unwrap_or(Value::Null)+    let v = ureq::get("http://127.0.0.1:8774/status").timeout(Duration::from_millis(1500)).call().ok()+        .and_then(|r| r.into_json::<Value>().ok()).unwrap_or(Value::Null);+    if v.is_object() { addin::note_answered(); }+    v }  fn native_status(h: &dyn HostBoth) -> Value {@@ -1517,6 +1519,13 @@ fn gather_readiness_inputs(h: &dyn HostBoth, caller: &Caller) -> fusion_core::re     let aps_signed = aps.valid_access_token().is_some();     let mcp = std::net::TcpStream::connect_timeout(&"127.0.0.1:27182".parse().unwrap(), Duration::from_millis(400)).is_ok();     let addin_ok = addin.is_object();+    // a loaded add-in at work: its /status says busy, or it is starved silent while one of our+    // requests is in flight or after it answered in this Fusion (never a launch to heal)+    let pids: Vec<u32> = if running { h.fusion_processes().iter().map(|p| p.pid).collect() } else { vec![] };+    let addin_busy = if !running { None }+        else if addin["busy"].as_bool() == Some(true) { Some(json!({"evidence": "status_busy", "busyCommand": addin["busyCommand"], "elapsedSeconds": addin["elapsedSeconds"]})) }+        else if !addin_ok { addin::loaded_evidence(&pids) }+        else { None };     let provisional_ready = installed_raw && running && addin_ok && !facts.needs_signin && facts.licensing_dialog.is_none();     let roundtrip_ok = if provisional_ready {         ureq::post("http://127.0.0.1:8774/command").timeout(Duration::from_secs(4)).send_json(json!({"command": "get_app_state", "args": {}})).ok()@@ -1540,6 +1549,7 @@ fn gather_readiness_inputs(h: &dyn HostBoth, caller: &Caller) -> fusion_core::re         fusion_user: None, modeling_orientation: None, bridge_version: VERSION.into(), prefs, now, now_iso,         timings_launch: timings_summary(&timings)["launch"].clone(), launch_stats: timings_stats(&timings, "launch", "cold"),         progress_override: None, addin_start_failed, crash_dialogs_cleared: 0, update_applied_button: None, update_offered: false,+        addin_busy,     };     *WINDOW_FACTS_DEGRADED.lock().unwrap() = (facts.degraded, facts.error.clone());     inputs@@ -1588,10 +1598,13 @@ impl chains::ChainHost for ExeChainHost { /// The chain in flight (busy: true on /status, like the Python bridge's _LONG_OP). static LONG_OP: Mutex<Option<String>> = Mutex::new(None); static LONG_OP_SINCE: Mutex<f64> = Mutex::new(0.0);-/// (name, since) of the long op in flight: a chain, else a walk/search on the pass-through.+/// (name, since) of the long op in flight: a chain, else a walk/search on the pass-through, else+/// any add-in request this exe has waited on for 5 s or more (a long script, an import, a close). pub(crate) fn long_op_marker() -> Option<(String, f64)> {     if let Some(n) = LONG_OP.lock().unwrap().clone() { return Some((n, *LONG_OP_SINCE.lock().unwrap())); }-    addin::long_command_active().and_then(|v| Some((v["command"].as_str()?.to_string(), v["startedAt"].as_f64()?)))+    if let Some(m) = addin::long_command_active().and_then(|v| Some((v["command"].as_str()?.to_string(), v["startedAt"].as_f64()?))) { return Some(m); }+    let now = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_secs_f64()).unwrap_or(0.0);+    addin::oldest_in_flight().filter(|(_, secs)| *secs >= 5.0).map(|(c, secs)| (c, now - secs)) }  fn chains_owner_is_exe(h: &dyn HostBoth) -> bool { owner_is_exe(h, "chainsOwner") }

@@ -699,6 +699,8 @@ pub fn fusion_state(ctx: &Ctx, args: &Value) -> Value {     let busy = st.as_ref().filter(|s| s["busy"].as_bool() == Some(true)).map(|s| json!({"command": s["busyCommand"], "elapsedSeconds": s["elapsedSeconds"]}));     result["addinResponding"] = json!(st.is_some());     result["mainThreadBusy"] = busy.clone().unwrap_or(Value::Null);+    // silent but loaded (a long native call starves even /status): say so, so no caller restarts it+    result["addinBusy"] = if st.is_none() { crate::addin::loaded_evidence(&ctx.pids).unwrap_or(Value::Null) } else { Value::Null };     if let Some(lsa) = crate::small_verbs::get_pref(&sd, "launchStartedAt").and_then(|v| v.as_f64()) {         if st.is_none() && now_f() - lsa < 900.0 {             let stats = fusion_core::readiness::timings_stats(&crate::timings::load(&sd), "launch", "cold");

@@ -58,6 +58,10 @@ pub struct Inputs {     pub update_applied_button: Option<String>,     /// Fusion is offering an update right now (the sidecar's `_LAST_UPDATE_OFFER`).     pub update_offered: bool,+    /// Why a not-ready add-in is loaded and working rather than missing (its /status says busy, or+    /// it is starved silent with one of our requests in flight or after answering in this Fusion).+    /// A busy add-in is not a launch: the launch observer neither starts nor heals over it.+    pub addin_busy: Option<Value>, }  /// The side effects the Python handler would have taken, for the owner to run.@@ -158,6 +162,9 @@ pub fn compute(i: &Inputs) -> Outcome {     let mut note: Option<String> = None;     if ready && !i.roundtrip_ok { ready = false; note = Some(hint("roundtrip_note")); }     if let Some(n) = &note { hint_text = format!("{hint_text}{}{n}", hint("roundtrip_note_prefix")); }+    // a loaded add-in that is working is not a launch in progress, and never a reason to restart+    let busy = running && !ready && !needs_signin && !licensing && i.addin_busy.is_some();+    if busy { hint_text = hint("addin_busy"); }     let orient_note = if i.modeling_orientation.as_deref() == Some("yup") {         " ⚠ Default Modeling Orientation is Y-UP on this account, but Adom is a Z-UP environment (a fresh Autodesk account defaults to Y-up). Set it with fusion_set_preference {\"modelingOrientation\":\"zup\"} - no restart needed." } else { "" };     let mut result = Map::new();@@ -175,17 +182,19 @@ pub fn compute(i: &Inputs) -> Outcome {     result.insert("_hint".into(), json!(format!("{hint_text}{orient_note}")));     // the launch observer     result.insert("timings".into(), i.timings_launch.clone());+    if busy { result.insert("addinBusy".into(), i.addin_busy.clone().unwrap_or(Value::Null)); }     let now = i.now;     let mut lsa = prefs.get("launchStartedAt").and_then(|v| v.as_f64());+    if busy && lsa.is_some() { prefs.insert("launchStartedAt".into(), Value::Null); lsa = None; }     if let Some(s) = lsa { if !ready && now - s > 900.0 { prefs.insert("launchStartedAt".into(), json!(now)); prefs.insert("launchHealedAt".into(), Value::Null); lsa = Some(now); } }-    if lsa.is_none() && running && !ready { prefs.insert("launchStartedAt".into(), json!(now)); lsa = Some(now); }+    if lsa.is_none() && running && !ready && !busy { prefs.insert("launchStartedAt".into(), json!(now)); lsa = Some(now); }     if !ready && running && i.crash_dialogs_cleared > 0 {         result.insert("crashReportCleared".into(), json!(i.crash_dialogs_cleared));         result.insert("fusionCrashed".into(), json!(true));         prefs.insert("launchHealedAt".into(), Value::Null); prefs.insert("launchStartedAt".into(), json!(now)); lsa = Some(now);     }     let healed = prefs.get("launchHealedAt").map(|v| !v.is_null()).unwrap_or(false);-    if !ready && running && !needs_signin && !licensing && !updating && lsa.is_some() && !healed {+    if !ready && running && !busy && !needs_signin && !licensing && !updating && lsa.is_some() && !healed {         let p90 = i.launch_stats["p90"].as_f64().unwrap_or(0.0);         let overdue_by = (2.0 * p90).max(180.0);         if now - lsa.unwrap() > overdue_by {

@@ -3,6 +3,7 @@  "installing": "Fusion install is STREAMING (10-30 min) - keep polling fusion_readiness until installed:true.",  "installed_not_running": "Fusion is INSTALLED but not running - call fusion_start (blocks until the add-in is ready), then retry.",  "addin_silent": "Fusion is RUNNING but its add-in is NOT responding yet - NOT ready to drive. Either it is still finishing launch / signing in (poll fusion_readiness a few more times), or the add-in did not load (fusion_stop then fusion_start to re-deploy + re-load it). Do NOT fire modeling/export verbs until ready:true.",+ "addin_busy": "Fusion is RUNNING and its add-in is LOADED but busy: a long command or a heavy Fusion operation holds its main thread (addinBusy says which and for how long). It is working, not missing: poll fusion_readiness again and drive when ready is true. Do NOT restart Fusion for this; a restart closes every open document and loses the work in flight.",  "needs_signin": "Fusion is RUNNING but stuck at the first-run Autodesk SIGN-IN (main UI blocked, add-in cannot serve) - NOT ready. FULL PLAYBOOK: the `fusion-autodesk-signin` skill. Proven sequence + the pitfalls that cost hours on a fresh Hyper-V VM (John 2026-07-14): (1) BLANK white webview on first launch? fusion_stop then fusion_start - the sign-in renders 'Welcome to Fusion' + a 'Sign In' button only after a clean relaunch. (2) ASK the user FIRST (AskUserQuestion): do they have a warm Google/Apple/Microsoft session for the account LINKED to their Autodesk login? Offer to drive it. A truly fresh box has NO warm browser session, so 'Continue with Google' still hits a password wall. (3) Click Fusion 'Sign In' -> it opens the DEFAULT browser (Edge) to the OAuth. Edge windows DO exist even if PowerShell EnumWindows looks empty - that is CLIXML progress noise; set $ProgressPreference='SilentlyContinue', and just desktop_screenshot_window the Edge hwnd (PrintWindow works backgrounded). (4) In the browser: 'Continue with Google' -> type the user's EMAIL (not secret) -> if it asks for a PASSWORD/2FA, STOP and fusion_notify_owner {title, body} to toast their MAIN computer so THEY type it; NEVER enter password/2FA yourself. (5) Handoff back to Fusion is via the 'Autodesk Identity Manager' protocol - Edge shows a 'This site is trying to open...' overlay: tick 'Always allow' + click 'Open'. (6) SPEED MATTERS: the sign-in code EXPIRES in ~2 min; on a high-latency VM slow screenshot/click round-trips let it expire ('Sign-in request expired') and you loop. Minimize steps; if it expires, click Fusion 'Sign In' again for a FRESH code (the browser session stays warm). Then poll until ready:true. FIRST-TIME DEMO? Run fusion_demo instead - it drives this sign-in through the user's NATIVE browser (already signed into Autodesk) and then gives them a real guided tour (project -> schematic -> 2D board -> 3D board).",  "licensing": "Fusion is blocked by a SEAT/LICENSING dialog ('Active Sessions Exceeded' / 'Suspend Remote Session') - detected DETERMINISTICALLY as an OWNED POPUP of the main Fusion window (its title is just 'Fusion360' and it can be as short as 262px, so it is found by owner+parent-screenshot, NOT a size guess). This verb JUST TRIED to auto-resolve it in the BACKGROUND (UIA 'Continue', Suspend pre-selected so it reclaims the seat) but it is still up - it may be mid-render (the first UIA Invoke no-ops). Just POLL fusion_readiness again in a few seconds; it keeps auto-resolving. Never coordinate-click or ask the user, and never kill/relaunch (the server keeps the seat).",  "updating": "Fusion is applying an AUTO-UPDATE (multiple webdeploy builds present) and RESTARTS ITSELF every ~30-60s - this is NOT a crash or a bridge failure. Poll fusion_readiness; it stabilizes to ready:true once the update finishes (can take 10-30 min). Meanwhile, wrap modeling/export verbs in a short retry/catch-loop to ride the up-windows rather than treating an intermittent 'not running' as fatal.",

@@ -19,7 +19,7 @@ fn inputs_from(sc: &Value) -> Inputs {         timings_launch: json!({"cold": {"p50": 45.0, "p90": 53.0, "count": 4, "lastAt": "2026-09-01T10:00:00"}}),         launch_stats: json!({"p50": 45.0, "p90": 53.0, "count": 4}),         progress_override: Some(json!({"phase": "launch", "stepLabel": "", "percent": 40, "elapsedSec": 30, "estimatedSec": 45, "etaSec": 15, "confidence": "measured", "startKind": "cold", "overdue": false})),-        addin_start_failed: None, crash_dialogs_cleared: 0, update_applied_button: None, update_offered: false,+        addin_start_failed: None, crash_dialogs_cleared: 0, update_applied_button: None, update_offered: false, addin_busy: None,     } } @@ -44,3 +44,33 @@ fn readiness_matches_the_python_handler_in_every_scenario() {     }     assert!(n >= 16, "{n} scenarios"); }++/// 2026-10-28: a 93 s script starved the add-in's probes, readiness read it as a launch, and the+/// launch observer would have restarted Fusion after 180 s. A busy, loaded add-in is not a launch.+#[test]+fn a_busy_addin_is_neither_a_launch_nor_a_restart() {+    let base = |busy: Option<Value>, prefs: Map<String, Value>, now: f64| Inputs {+        installed_raw: true, running: true, addin_version: None, expected_addin_version: "1.0.19".into(),+        auto_update_enabled: true, bridge_version: "TEST".into(), prefs, now, now_iso: "2026-10-28T00:09:00".into(),+        timings_launch: json!({}), launch_stats: json!({"p50": 45.0, "p90": 53.0, "count": 4}), addin_busy: busy, ..Default::default()+    };+    let ev = json!({"evidence": "request_in_flight", "busyCommand": "run_modeling_script", "elapsedSeconds": 31.0});+    // busy: no launch timer, a busy hint, the evidence in the reply+    let out = compute(&base(Some(ev.clone()), Map::new(), 1000.0));+    assert_eq!(out.result["ready"], json!(false));+    assert_eq!(out.result["addinBusy"], ev);+    assert!(out.result["_hint"].as_str().unwrap().contains("LOADED but busy"));+    assert!(out.prefs_after.get("launchStartedAt").map(|v| v.is_null()).unwrap_or(true));+    // a timer left from earlier silence is cleared, and 10 minutes later nothing heals+    let mut prefs = Map::new();+    prefs.insert("launchStartedAt".into(), json!(400.0));+    let out = compute(&base(Some(ev.clone()), prefs, 1000.0));+    assert!(out.actions.heal_launch.is_none());+    assert!(out.result.get("addinRestartTriggered").is_none());+    assert_eq!(out.prefs_after["launchStartedAt"], Value::Null);+    // without evidence the observer still heals a launch that never served (unchanged)+    let mut prefs = Map::new();+    prefs.insert("launchStartedAt".into(), json!(400.0));+    let out = compute(&base(None, prefs, 1000.0));+    assert_eq!(out.actions.heal_launch, Some(1));+}

@@ -80,7 +80,9 @@ the four questions a caller needs before starting: | `installed_not_running` | Just needs launching | Proceed; launch is a stage, ~60s, folded into the ETA | | `needs_signin` | Running, but at the Autodesk sign-in screen (bridge 1.10.1+) | Drive the sign-in (fusion-autodesk-signin skill); board verbs return this at once, never a restart diagnosis | | `blocked_by_dialog` | A dialog survived the bridge's safe expiry (rules, then WM_CLOSE) | Read `dialogs[]` (text, buttons); answer by button name, then re-run; never restart |-| `addin_restarting` | Running and signed in, add-in not loaded; the bridge is restarting Fusion itself (restartPolicy auto, the default since 1.10.6: every open document is the AI's own) | Poll `fusion_readiness`, then continue |+| `addin_restarting` | Running and signed in, add-in not loaded; the bridge is restarting Fusion itself (restartPolicy auto, the default: documents are saved first, and nobody's unsaved work is discarded) | Poll `fusion_readiness`, then continue |+| `fusion_addin_busy` | Running, add-in loaded but working (a long command starves even its status probe); readiness says `addinBusy` | Wait and poll `fusion_readiness`; never restart for it |+| `restart_needs_decision` | A restart stopped short of unsaved work the bridge could not save (nothing killed or discarded) | Show `userMessage`; restart again once the work is saved | | `addin_restart_required` | Same, on a box whose prefs.json sets `restartPolicy: ask` | Show `userMessage`, then `fusion_restart_for_addin` on a yes | | `ready` | Good to go | Start | @@ -262,7 +264,7 @@ promised "we will save your documents first" while its only button was an acknow the text made an offer the UI could not keep. That is lazy, and it leaves the user exactly where Adonis was. -Under `restartPolicy: ask` (NOT the default since 1.10.6: the default `auto` raises no toast and the bridge restarts Fusion itself when the add-in is truly gone, never over a dialog) the restart notice offers **"Save and restart"** and **"I'll handle it"**, and the+Under `restartPolicy: ask` (NOT the default since 1.10.6: the default `auto` raises no toast and the bridge restarts Fusion itself when the add-in is truly gone, never over a dialog and never over unsaved work it could not save) the restart notice offers **"Save and restart"** and **"I'll handle it"**, and the bridge honours whichever is pressed (`_watch_restart_choice` polls `notify_response` and either runs `fusion_restart_for_addin {save:true}` or records the decline). Both land in the action ledger, so "why did my Fusion restart" has a timestamped answer.