SOLIDWORKS Bridge

@@ -58,6 +58,61 @@ fn doc_type_name(id: i32) -> String {     } } +/// The `_hint` `swx_import` carries, keyed on the NET document count. An import+/// leaves ONE open, unsaved, bridge-created document — exactly like+/// `swx_new_document` — and it stays open (and costs memory) until it is closed+/// or saved. The 1342-temp leak was callers importing and never closing.+/// Appended when the document handle had to be recovered from `ActiveDoc`.+const RECOVERED_HANDLE_CAVEAT: &str =+    " NOTE: the document handle could not be taken from the import call and was recovered from      ActiveDoc. The net count proves a document arrived; if a SECOND import was running      concurrently (another caller, or the user importing by hand), the title and path reported      here may belong to that one. Confirm with swx_docs before acting on the title.";++fn import_open_hint(net: i32) -> String {+    match net {+        1 => "Imported. This left ONE new open, unsaved document (like swx_new_document) — it \+              stays open and holds memory until you save it (swx_save_as) or close it \+              (swx_close_doc). Importing repeatedly without closing is what leaks documents; \+              swx_close_import_temps drains any that were left behind."+            .to_string(),+        0 => "The open-document count did NOT rise, so nothing was actually imported even though \+              a call returned — do not treat this as a new document. Check swx_docs."+            .to_string(),+        n => format!(+            "The open-document count rose by {n}, not 1 — more than the single document an import \+             should add. Check swx_docs; you may have a duplicate open. swx_close_import_temps \+             drains leaked import temporaries."+        ),+    }+}++/// WHY A DOCUMENT WALK STOPPED. Reaching the end of the session and being cut+/// short are different facts, and only one of them means "that is all there was".+#[derive(Clone, Copy, PartialEq, Debug)]+pub enum WalkStop {+    /// `GetNext` returned nothing: the session really ended here.+    ReachedEnd,+    /// We had seen as many documents as we asked for.+    HitMax,+    /// The time box stopped us.+    TimedOut,+    /// `GetNext` FAILED — the iteration was invalidated (a document closed under+    /// us). Not the end of the session, and never to be reported as one.+    IterationFailed,+}++impl WalkStop {+    pub fn complete(self) -> bool {+        self == WalkStop::ReachedEnd+    }+    pub fn name(self) -> &'static str {+        match self {+            WalkStop::ReachedEnd => "reachedEnd",+            WalkStop::HitMax => "hitMax",+            WalkStop::TimedOut => "timedOut",+            WalkStop::IterationFailed => "iterationFailed",+        }+    }+}+ pub struct ComBackend {     sw: Option<Disp>,     was_launched: bool,@@ -321,7 +376,13 @@ impl ComBackend {     fn cmd_status(&mut self) -> Result<Value, HostError> {         let mut running = false;         let mut version = Value::Null;-        let mut open_docs = 0usize;+        // WHICH sldworks.exe COM is attached to. `host_app_health` needs it to+        // report about the right process when two are running.+        let mut process_id = Value::Null;+        // `None` = we could not count. Reported as JSON null, never as 0: the+        // difference between "no documents are open" and "I could not ask"+        // is the difference the whole 0.3.3 enumeration fix was about.+        let mut open_docs: Option<usize> = None;         if let Ok(clsid) = Self::clsid() {             unsafe {                 let mut unk = None;@@ -333,7 +394,15 @@ impl ComBackend {                             .string("RevisionNumber", &[])                             .map(Value::from)                             .unwrap_or(Value::Null);-                        open_docs = sw.call("GetDocuments", &[]).map(|d| d.as_array().len()).unwrap_or(0);+                        // GetDocumentCount is the AUTHORITY here. On 2026-09-03+                        // it kept saying 51 while GetDocuments returned an empty+                        // VARIANT, so counting the array meant reporting zero+                        // open documents with 51 on screen. An unreadable count+                        // is null — never a comfortable 0.+                        process_id = sw.int("GetProcessID", &[]).map(Value::from).unwrap_or(Value::Null);+                        open_docs = sw+                            .int("GetDocumentCount", &[])+                            .map(|c| c as usize);                         self.sw = Some(sw);                     }                 }@@ -343,10 +412,634 @@ impl ComBackend {             "running": running,             "version": version,             "openDocs": open_docs,+            "processId": process_id,             "attached": self.sw.is_some(),         }))     } +    /// Did this call fail because the COM SERVER WENT AWAY? For a quit rung+    /// that is the SUCCESS case, not an error: any rung that works tears the+    /// server down underneath the very call that asked for it.+    ///+    /// ONLY the specific HRESULTs that mean "the object we were calling has gone+    /// away". An earlier version matched any message containing "server" or+    /// "rpc", which would report a quit for a completely unrelated failure with+    /// SOLIDWORKS still on screen.+    fn is_rpc_disconnect(e: &HostError) -> bool {+        let d = e.detail.as_deref().unwrap_or("");+        [+            "0x800706BA", // RPC_S_SERVER_UNAVAILABLE+            "0x80010108", // RPC_E_DISCONNECTED+            "0x800706BE", // RPC_S_CALL_FAILED+            "0x800706BF", // RPC_S_CALL_FAILED_DNE+            "0x80010012", // CO_E_OBJNOTCONNECTED+            "0x80010105", // RPC_E_SERVERFAULT+        ]+        .iter()+        .any(|code| d.contains(code))+    }++    /// `GetDocumentCount` — ONE call, always answers. `None` only when the+    /// call itself failed.+    fn document_count(sw: &Disp) -> Option<i32> {+        sw.int("GetDocumentCount", &[])+    }++    /// `swx_docs`, and it MUST NOT WEDGE on a huge count.+    ///+    /// The authoritative count is read first. Under the cap the full list is+    /// enumerated as before; over it, only the first `DOC_SAMPLE` handles are+    /// turned into `doc_info` and the rest are reported by number — because a+    /// session with 1342 leaked import temps cannot be marshalled in the+    /// budget, and blocking the whole 30s is what got the com host killed.+    fn cmd_docs(&mut self) -> Result<Value, HostError> {+        let sw = self.app(false, true)?;+        let active =+            sw.obj("ActiveDoc", &[])?.map(|d| Self::doc_info(&d)).unwrap_or(Value::Null);+        let count = Self::document_count(&sw);+        // AN UNREADABLE COUNT IS UNKNOWN, AND UNKNOWN MUST NOT ENUMERATE. The+        // first version fell through to the full marshal when the count came back+        // `None` — which is exactly the 30s wedge this cap exists to prevent, and+        // most likely precisely when the machine is under the memory pressure+        // that made the count unreadable in the first place.+        if count.is_none() {+            return Ok(json!({+                "docs": [],+                "count": Value::Null,+                "documentCount": Value::Null,+                "truncated": true,+                "sample": [],+                "active": active,+                "_hint": "SOLIDWORKS would not say how many documents are open, so this bridge did                           NOT try to enumerate them — an unbounded marshal is how the com host gets                           killed, and an unreadable count usually means the session is under                           pressure. `count:null` means UNKNOWN, not zero. Retry; if it keeps                           failing, swx_close_import_temps drains leaked import temporaries and                           swx_status reports the process's memory.",+            }));+        }+        if let Some(c) = count {+            if c as usize > super::host::doc_enum_cap() {+                // NEVER `GetDocuments` HERE. Walk exactly DOC_SAMPLE documents,+                // one at a time, time-boxed — the cost of this branch must be a+                // function of the SAMPLE, never of how flooded the session is.+                let (walked, stop) = Self::walk_documents(+                    &sw,+                    super::host::DOC_SAMPLE,+                    std::time::Duration::from_secs(super::host::DOC_SAMPLE_BUDGET_SECS),+                )?;+                let timed_out = stop == WalkStop::TimedOut;+                let sample: Vec<Value> = walked.iter().map(Self::doc_info).collect();+                // COUNTED OVER THE SAMPLE ONLY, which is what the field has always+                // been called. Counting it over all 2144 was 2144 `GetPathName`+                // round trips for a number nobody could act on.+                // Roots resolved ONCE, not per document: on Windows resolving+                // them reads the registry, and this loop is the one place that+                // would have paid for it ten times over.+                let roots = super::host::temp_roots();+                let temps = walked+                    .iter()+                    .filter(|d| {+                        d.string("GetPathName", &[])+                            .map(|p| super::host::is_import_temp_under_any(&p, &roots))+                            .unwrap_or(false)+                    })+                    .count();+                return Ok(json!({+                    "docs": [],+                    "count": c,+                    "documentCount": c,+                    "truncated": true,+                    "sample": sample,+                    "active": active,+                    "importTempsInSample": temps,+                    // ...OUT OF HOW MANY. A bare count against an unstated+                    // denominator reads as a count of the session.+                    "importTempsInSampleOf": sample.len(),+                    "sampleTruncatedByTime": timed_out,+                    "sampleWalkStopped": stop.name(),+                    "_hint": format!(+                        "{c} documents are open — too many to enumerate in the budget, so this                          is the count plus the first {} as a sample, NOT the whole list (and                          NOT a timeout). A count this large is almost always leaked STEP/IGES                          import temporaries in the bridge\'s own temp dir (…\\swx<pid>\\IC~~\\…); run \+                         swx_close_import_temps to drain them. It never touches a saved user                          document.",+                        sample.len()+                    ),+                }));+            }+        }+        let docs: Vec<Value> = Self::documents(&sw)?.iter().map(Self::doc_info).collect();+        Ok(json!({+            "docs": docs,+            "count": count.map(Value::from).unwrap_or_else(|| Value::from(docs.len())),+            "truncated": false,+            "active": active,+        }))+    }++    /// Drain leaked STEP/IGES-import temporaries — and NOTHING else.+    ///+    /// A document qualifies ONLY by [`super::host::is_import_temp`] on its own+    /// `GetPathName`: a path under the bridge's temp dir with an `IC~~`+    /// conversion segment. No user document can match that, so this is safe in+    /// the DEFAULT posture — the path is the ownership proof, and a stronger one+    /// than the registry (it survives the pid change that made the 1342 leaked+    /// temps un-ownable). `CloseDoc` discards without a save prompt, which is+    /// correct: these were never saved to a real location.+    ///+    /// BOUNDED per call: it closes at most `max` documents or runs for at most+    /// ~40s, then reports `done:false` with `remaining` so the server can call+    /// it again. Closing 1342 documents in one unbounded call is exactly the+    /// kind of thing that gets the com host killed mid-work.+    fn cmd_close_import_temps(&mut self, args: &Value) -> Result<Value, HostError> {+        let sw = self.app(false, true)?;+        let before = Self::document_count(&sw);+        let max = args.get("max").and_then(|v| v.as_u64()).unwrap_or(200).max(1) as usize;+        // THE ANCHOR IS THE WHOLE LOCATION PROOF, so without a resolved `%TEMP%`+        // nothing can be identified as a temp. Say so — `closed:0, done:true`+        // would read as "there was nothing to drain" on a session holding+        // hundreds of them.+        let temp_roots = super::host::temp_roots();+        if temp_roots.is_empty() {+            return Ok(json!({+                "closed": 0,+                "closedDocs": [],+                "documentCountBefore": before,+                "documentCountAfter": before,+                "done": false,+                "batchLimit": max,+                "tempRoot": Value::Null,+                "tempRoots": [],+            }));+        }+        // WALK, DO NOT MARSHAL. `GetDocuments` returns every handle in one call+        // and did not answer within 30s on Drew's 2144-document session — the+        // exact session this verb exists to drain, so the drain would have wedged+        // the com host on the one machine state it was written for.+        //+        // Two phases, deliberately: COLLECT up to `max` victims by walking one+        // document at a time (reading each path as we pass it), then CLOSE them.+        // Closing while walking would invalidate the very iteration we are in the+        // middle of.+        let (walked, walk_stop) = Self::walk_documents(+            &sw,+            // Enough to find `max` temps on a session where they are not all+            // temps, without becoming an unbounded scan.+            max.saturating_mul(4).max(max + 50),+            std::time::Duration::from_secs(super::host::DRAIN_WALK_BUDGET_SECS),+        )?;+        let walk_timed_out = walk_stop == WalkStop::TimedOut;+        let scanned = walked.len() as u64;+        let mut victims: Vec<(String, String)> = Vec::new();+        // EVERY document the walk passed, by (title, path). The title is read for+        // all of them, not just the victims, because it is what the collision+        // check below needs — and one extra call per scanned document inside a+        // bounded window is the price of not closing the wrong file.+        let mut seen: Vec<(String, String)> = Vec::new();+        let mut hit_limit = walk_timed_out;+        let mut elsewhere = 0u64;+        let mut elsewhere_sample: Option<String> = None;+        for doc in &walked {+            let Some(path) = doc.string("GetPathName", &[]) else { continue };+            let title = doc.string("GetTitle", &[]).unwrap_or_default();+            seen.push((title.clone(), path.clone()));+            // NOTE: the scan does NOT stop at `max` — only the victim list does.+            // Stopping the scan would blind the collision check to a document+            // later in the window that shares a victim's title.+            if !super::host::is_import_temp_under_any(&path, &temp_roots) {+                // A NEAR MISS is worth counting: the launcher's own+                // `swx<digits>\IC~~\<file>` tail, under a directory that is not+                // one of the temp roots this process could resolve. Almost+                // certainly a leaked temp whose `%TEMP%` we do not know — and the+                // one thing the report must not do is call that "nothing to+                // drain".+                if super::host::has_import_temp_tail(&path) {+                    elsewhere += 1;+                    if elsewhere_sample.is_none() {+                        elsewhere_sample = Some(path.clone());+                    }+                }+                continue;+            }+            if victims.len() >= max {+                hit_limit = true;+                continue;+            }+            victims.push((title, path));+        }++        // ── A TITLE IS NOT AN IDENTITY, and this is the one place that rule was+        //    missing. `ISldWorks::CloseDoc` resolves a document BY NAME and does+        //    not prompt. The victim is chosen by PATH — the whole location proof+        //    — and was then closed by TITLE, so on Drew's live session (leaked+        //    temps titled `First.step-1.SLDPRT` beside his SAVED+        //    `…\validation\First.step-1.SLDPRT`) SOLIDWORKS would have chosen+        //    which one died, and this response would have recorded the temp's+        //    path as closed either way.+        //+        //    Two guards, because one of them is about a call whose by-path+        //    behaviour this bridge has not yet proven on a live machine:+        //      1. CLOSE BY THE PATH THE VICTIM WAS CHOSEN BY.+        //      2. REFUSE any victim whose title another open document shares —+        //         and say which paths, so the user can act on it.+        let mut collisions: Vec<Value> = Vec::new();+        let victims: Vec<(String, String)> = victims+            .into_iter()+            .filter(|(title, path)| {+                let others: Vec<String> = seen+                    .iter()+                    .filter(|(t, p)| t == title && !crate::verbs::same_path(p, path))+                    .map(|(_, p)| p.clone())+                    .collect();+                if others.is_empty() {+                    return true;+                }+                let mut paths = vec![path.clone()];+                paths.extend(others);+                collisions.push(json!({"title": title, "paths": paths}));+                false+            })+            .collect();++        // ...THEN CLOSE, by path, verifying each one.+        let mut closed: Vec<Value> = Vec::new();+        let mut wrong_document_closed = false;+        let mut close_ignored_path = false;+        let mut close_outcome_unknown = false;+        let mut close_failed: Vec<Value> = Vec::new();+        for (title, path) in victims {+            let asked = sw.call("CloseDoc", &[&Var::bstr(&path)]).is_ok();+            // VERIFY, by the same identity we asked with. `GetOpenDocumentByName`+            // is one call.+            let still_open = Self::open_document_by_name(&sw, &path).is_some();+            if asked && still_open {+                // ── TWO VERY DIFFERENT FACTS, and only a COUNT separates them.+                //+                // The documented signature of `CloseDoc` is `CloseDoc(name)` and+                // the help text says only "name of the document to close" — that+                // a FULL PATH is accepted is this bridge's premise, and it has+                // not been proven on a live machine. So:+                //+                //   * the count did NOT move  -> the call did nothing at all.+                //     That is a CAPABILITY problem (the path form is not+                //     understood), not a wrong close, and it is not a reason to+                //     retry with a title: that is exactly the ambiguity this+                //     round removed. Refuse, and say which premise failed.+                //   * the count DROPPED while our victim is still open -> some+                //     OTHER document was closed. That must be unreachable, and+                //     this is the check that proves it rather than hoping.+                //+                // One extra count, only in the anomaly case.+                let expected = before.map(|b| b - closed.len() as i32);+                let now = Self::document_count(&sw);+                let nothing_happened = match (expected, now) {+                    (Some(e), Some(n)) => n >= e,+                    // ── THE THIRD CASE, and it is not the benign one. An+                    //    unreadable count cannot distinguish "nothing happened"+                    //    from "something else was closed" — and the count can+                    //    become unreadable BECAUSE something large just changed:+                    //    closing a big assembly is exactly the kind of event that+                    //    makes GetDocumentCount stop answering. Taking the+                    //    reassuring arm here would report a capability problem and+                    //    accuse nobody while a user's document may have gone.+                    //    Everywhere else in this bridge an unknown refuses AND+                    //    SAYS UNKNOWN; so does this.+                    _ => {+                        close_outcome_unknown = true;+                        close_failed.push(json!({+                            "title": title,+                            "path": path,+                            "outcome": "undetermined",+                            "documentCountBeforeClose": expected,+                            "why": "CloseDoc returned success, the document is still open, and the \+                                    open-document count could not be read afterwards — so it \+                                    cannot be told whether NOTHING closed or ANOTHER document did. \+                                    A human must check whether this path, or some other document, \+                                    closed. The drain stopped here.",+                        }));+                        break;+                    }+                };+                if nothing_happened {+                    close_ignored_path = true;+                    close_failed.push(json!({+                        "title": title,+                        "path": path,+                        "why": "CloseDoc(path) returned success, the document is still open, and \+                                the open-document count did not move — the call did nothing. This \+                                bridge will NOT retry by title: a title is not an identity. The \+                                drain stopped here.",+                    }));+                    break;+                }+                wrong_document_closed = true;+                close_failed.push(json!({+                    "title": title,+                    "path": path,+                    "why": "CloseDoc reported success, the document is still open, and the count \+                            DROPPED — a DIFFERENT document was closed. The drain stopped here.",+                }));+                break;+            }+            if !asked || still_open {+                close_failed.push(json!({+                    "title": title,+                    "path": path,+                    "why": "SOLIDWORKS declined to close it; nothing else was touched",+                }));+                continue;+            }+            // It is no longer ours to remember, on either veto.+            self.created.retain(|(t, p)| {+                t != &title && p.as_deref() != Some(path.as_str())+            });+            closed.push(json!({"title": title, "path": path}));+        }+        let remaining_after = Self::document_count(&sw);+        // DID THE WALK SEE EVERY OPEN DOCUMENT? The two numbers were already in+        // the response and nothing compared them.+        let scanned_all = before.map(|b| scanned >= b.max(0) as u64).unwrap_or(false);+        // More may remain either because we hit the batch limit, or because the+        // count still shows import-image documents we did not reach this pass.+        let done = !hit_limit;+        Ok(json!({+            "closed": closed.len(),+            "closedDocs": closed,+            "documentCountBefore": before,+            "documentCountAfter": remaining_after,+            // NOT DONE while documents carry the launcher's tail and we closed+            // nothing, nor when the walk did not reach the end of the session,+            // nor when a victim was skipped: "done" would be a claim about the+            // user's session that the evidence does not support.+            // DONE MEANS THE SESSION IS DRAINED, and every one of these is part+            // of that claim. `hit_limit` alone was seeded from the TIME box only,+            // so a walk that stopped at its scan cap (hitMax) or on an+            // invalidated iteration (iterationFailed) reported a finished drain+            // with temporaries still open past the window.+            "done": done+                && walk_stop.complete()+                && scanned_all+                && collisions.is_empty()+                && close_failed.is_empty()+                && !(elsewhere > 0 && closed.is_empty()),+            "batchLimit": max,+            "tempRoot": temp_roots.first(),+            "tempRoots": temp_roots,+            "importTempsElsewhere": elsewhere,+            "importTempsElsewhereSample": elsewhere_sample,+            // HOW FAR THE WALK GOT. `importTempsElsewhere` is a count over the+            // documents SCANNED, not over the session — on a flooded session this+            // verb deliberately looks at a bounded window per call.+            "documentsScanned": scanned,+            "walkTruncatedByTime": walk_timed_out,+            // DID THE WALK REACH THE END OF THE SESSION? A `GetNext` that fails+            // mid-walk (a document closed under us, invalidating the iteration)+            // is not the end of the session and must never be reported as one.+            "walkComplete": walk_stop.complete(),+            // reachedEnd | hitMax | timedOut | iterationFailed. Published because+            // `titleCollisions: []` and `done` cannot be interpreted without it: a+            // collision check over 55 of 60 documents is not the same claim as one+            // over the session.+            "walkStop": walk_stop.name(),+            "titleCollisions": collisions,+            // THE COLLISION CHECK'S REACH. It compares each victim's title against+            // the documents the walk actually PASSED, so a same-titled document+            // outside that window is invisible to it. Harmless for the close (the+            // path is the key) and load-bearing for the report.+            "titleCollisionsCheckedOver": scanned,+            "closeFailed": close_failed,+            "wrongDocumentClosed": wrong_document_closed,+            "closeIgnoredPath": close_ignored_path,+            "closeOutcomeUnknown": close_outcome_unknown,+        }))+    }++    /// ONE RUNG of the quit ladder (docs/QUIT-INVESTIGATION.md §5.3).+    ///+    /// Every rung ENDS with every COM reference released, and rungs (b)-(f)+    /// therefore START from a released state — the com host re-attaches only to+    /// act, never to measure. A `WM_CLOSE` sent while we still hold an+    /// `IDispatch` is the most direct way to manufacture the half-closed+    /// `SLDWORKS.exe -Embedding` orphan this design exists to avoid.+    ///+    /// The result is what the rung DID, not whether it worked: the server+    /// decides that from a process census. A rung that tears the COM server down+    /// underneath us comes back as an RPC disconnect, which is the SUCCESS case+    /// and must not be reported as an error.+    /// IS THIS STILL THE WINDOW WE MEASURED? Asked immediately before rung (c)+    /// or (d) sends anything, because the handle was captured before rung (a) ran+    /// and rung (a)'s whole purpose is to make that window go away.+    ///+    /// Both facts have to answer, and an unreadable one is a NO: the owning pid+    /// (`GetWindowThreadProcessId`) and that pid's creation time (the census). A+    /// pid alone would pass a recycled pid.+    #[cfg(windows)]+    fn hwnd_still_ours(hwnd: i64, pid: u32, created: Option<u64>, detail: &mut Vec<String>) -> bool {+        let Some(created) = created else {+            detail.push("no creation time was supplied for the target process".into());+            return false;+        };+        let actual = crate::quit::win::window_pid(hwnd);+        let actual_created = crate::launchos::os()+            .processes()+            .ok()+            .and_then(|c| actual.and_then(|p| c.iter().find(|r| r.pid == p).and_then(|r| r.created_at)));+        let id = crate::quit::Identity { pid, created_at: created, main_hwnd: Some(hwnd) };+        let ok = crate::quit::hwnd_still_owned(actual, actual_created, &id);+        detail.push(format!(+            "hwnd {hwnd} re-verified before sending: owner pid {actual:?} (created \+             {actual_created:?}) vs expected {pid} (created {created}) -> {}",+            if ok { "same window" } else { "NOT ours, nothing sent" }+        ));+        ok+    }++    #[cfg(not(windows))]+    fn hwnd_still_ours(_hwnd: i64, _pid: u32, _created: Option<u64>, detail: &mut Vec<String>) -> bool {+        detail.push("window ownership cannot be re-verified off Windows".into());+        false+    }++    fn cmd_quit_rung(&mut self, args: &Value) -> Result<Value, HostError> {+        let rung = args.get("rung").and_then(|v| v.as_str()).unwrap_or("");+        if !crate::quit::is_rung(rung) {+            return Err(HostError::coded(+                "unknown_rung",+                format!("'{rung}' is not a rung of the quit ladder"),+            ));+        }+        let hwnd = args.get("mainHwnd").and_then(|v| v.as_i64()).unwrap_or(0);+        let pid = args.get("processId").and_then(|v| v.as_u64()).unwrap_or(0) as u32;+        let created = args.get("processCreatedAt").and_then(|v| v.as_u64());+        let mut detail: Vec<String> = Vec::new();+        let mut result = "declined";++        match rung {+            "a" => {+                let sw = self.app(false, true)?;+                // UserControl is THE flag that decides whether SOLIDWORKS+                // outlives its automation client. Remember it so a decline can+                // be undone.+                let was = sw.flag("UserControl", &[]);+                detail.push(format!("UserControl before = {was:?}"));+                sw.try_put("UserControl", &Var::boolean(false));+                detail.push("UserControl=false attempted".into());+                let exit = sw.call("ExitApp", &[]);+                match &exit {+                    Ok(_) => detail.push("ExitApp returned".into()),+                    Err(e) => {+                        // The disconnect HRESULTs mean the server went away —+                        // which IS the success case for this call.+                        if Self::is_rpc_disconnect(e) {+                            detail.push(format!("ExitApp: RPC disconnect ({}) — the COM server went away", e.message));+                            result = "exited";+                        } else {+                            detail.push(format!("ExitApp failed: {}", e.message));+                        }+                    }+                }+                // RELEASE EVERYTHING, unconditionally, before returning.+                drop(sw);+                self.sw = None;+                detail.push("released every COM reference".into());+                // Restore UserControl only if it plainly declined AND we can+                // still reach the app — never leave the user's session with a+                // flag we changed.+                if result != "exited" {+                    if let (Some(prev), Ok(sw2)) = (was, self.app(false, true)) {+                        if prev {+                            sw2.try_put("UserControl", &Var::boolean(true));+                            detail.push("UserControl restored to true".into());+                        }+                        drop(sw2);+                        self.sw = None;+                    }+                }+            }+            "b" => {+                let sw = self.app(false, true)?;+                let called = sw.call(+                    "RunCommand",+                    &[&Var::i4(crate::quit::SW_COMMANDS_APP_EXIT), &Var::bstr("")],+                );+                match &called {+                    Ok(_) => detail.push(format!("RunCommand({}) returned", crate::quit::SW_COMMANDS_APP_EXIT)),+                    Err(e) => {+                        if Self::is_rpc_disconnect(e) {+                            detail.push("RunCommand: RPC disconnect — the COM server went away".into());+                            result = "exited";+                        } else {+                            detail.push(format!("RunCommand failed: {}", e.message));+                        }+                    }+                }+                drop(sw);+                self.sw = None;+                detail.push("released every COM reference".into());+            }+            "c" | "d" => {+                // MESSAGE RUNGS: no COM at all, and they must not run while we+                // hold a reference.+                self.sw = None;+                if hwnd == 0 {+                    detail.push("no main-frame hwnd was supplied".into());+                    result = "skipped";+                } else if !Self::hwnd_still_ours(hwnd, pid, created, &mut detail) {+                    // NOT OUR WINDOW ANY MORE. Nothing is sent — a WM_CLOSE to a+                    // recycled handle is a close nobody asked for.+                    result = "skipped";+                } else {+                    #[cfg(windows)]+                    {+                        let (sent, blocked, note) = if rung == "c" {+                            crate::quit::win::send_wm_close(hwnd)+                        } else {+                            crate::quit::win::post_sc_close(hwnd)+                        };+                        detail.push(note);+                        if blocked {+                            result = "uipiBlocked";+                        } else if !sent {+                            result = "declined";+                        }+                    }+                    #[cfg(not(windows))]+                    {+                        detail.push("window messages are Windows-only".into());+                        result = "skipped";+                    }+                }+            }+            "e" => {+                // The in-process exit. ONLY the shipped, content-hashed macro.+                match crate::quit::exit_macro_path() {+                    None => {+                        detail.push(+                            "the exit macro is not shipped in resources/macros/ (a .swp is a \+                             binary VBA project and cannot be authored without SOLIDWORKS), so \+                             this rung is unavailable"+                                .into(),+                        );+                        result = "skipped";+                    }+                    Some(path) => {+                        let sw = self.app(false, true)?;+                        let mut err_code = 0i32;+                        let called = sw.call(+                            "RunMacro2",+                            &[+                                &Var::bstr(&path),+                                &Var::bstr("main"),+                                &Var::bstr("main"),+                                &Var::i4(0),+                                &Var::byref_i4(&mut err_code as *mut i32),+                            ],+                        );+                        match &called {+                            Ok(_) => detail.push(format!("RunMacro2({path}) returned, err={err_code}")),+                            Err(e) => {+                                if Self::is_rpc_disconnect(e) {+                                    detail.push("RunMacro2: RPC disconnect — the COM server went away".into());+                                    result = "exited";+                                } else {+                                    detail.push(format!("RunMacro2 failed: {}", e.message));+                                }+                            }+                        }+                        drop(sw);+                        self.sw = None;+                        detail.push("released every COM reference".into());+                    }+                }+            }+            "f" => {+                self.sw = None;+                match created {+                    None => {+                        detail.push("no process creation time — the Restart Manager needs the pid AND its creation time".into());+                        result = "skipped";+                    }+                    Some(ct) => {+                        #[cfg(windows)]+                        {+                            let (ok, note) = crate::quit::win::restart_manager_shutdown(pid, ct);+                            detail.push(note);+                            if !ok {+                                result = "declined";+                            }+                        }+                        #[cfg(not(windows))]+                        {+                            let _ = (pid, ct);+                            detail.push("the Restart Manager is Windows-only".into());+                            result = "skipped";+                        }+                    }+                }+            }+            _ => unreachable!("guarded by is_rung"),+        }+        Ok(json!({+            "rung": rung,+            "result": result,+            "detail": detail.join("; "),+            "comReferencesOutstanding": usize::from(self.sw.is_some()),+        }))+    }+     fn cmd_open(&mut self, args: &Value) -> Result<Value, HostError> {         let path = args             .get("path")@@ -626,7 +1319,11 @@ impl ComBackend {         mgr.try_put("MakeInterferingPartsTransparent", &Var::boolean(false));          let found = mgr.call("GetInterferences", &[])?;-        let count = mgr.int("GetInterferenceCount", &[]).unwrap_or(0);+        // `null`, not 0. "Zero interferences" is a CLEARANCE REPORT somebody+        // builds a physical thing from; manufacturing an all-clear out of a+        // count SOLIDWORKS declined to give is the most expensive empty-value+        // collapse in this file.+        let count = mgr.int("GetInterferenceCount", &[]);         let mut out = Vec::new();         for item in found.as_array() {             let item = match item.as_dispatch().map(Disp) {@@ -646,7 +1343,26 @@ impl ComBackend {                 .unwrap_or_default();             out.push(json!({"components": names, "volumeM3": item.float("Volume", &[])}));         }-        Ok(json!({"doc": Self::doc_info(&doc), "count": count, "interferences": out}))+        // A count that disagrees with the list is not an answer either.+        let listed = out.len();+        if let Some(c) = count {+            if c as usize != listed && listed == 0 {+                return Err(HostError::coded(+                    "interference_enumeration_failed",+                    format!(+                        "SOLIDWORKS reports {c} interference(s) but returned none of them. This \+                         is NOT a clean result — nothing was concluded from it; retry the check."+                    ),+                ));+            }+        }+        Ok(json!({+            "doc": Self::doc_info(&doc),+            "count": count,+            "countKnown": count.is_some(),+            "interferences": out,+            "listed": listed,+        }))     }      fn cmd_rebuild_check(&mut self, args: &Value) -> Result<Value, HostError> {@@ -930,15 +1646,32 @@ impl ComBackend {     /// from the ENVIRONMENT it inherited rather than from anything the server     /// sent. So the server cannot fabricate the escape: `allowUserWrites` in     /// the request is necessary but never sufficient.-    /// Run a `.lnk` through the shell, detached.+    /// Run the Platform's `.lnk` — by ONE named route.+    ///+    /// THE MEASUREMENT THIS EXISTS FOR (2026-09-04, Drew's machine): five of+    /// five launches through `cmdStart` produced a `SWXDesktopLauncher` log that+    /// stopped at `SecurityContext:` and never logged `Run Begin`. Every launch+    /// of the same shortcut with the same arguments from an INTERACTIVE context+    /// reached `Run Begin` ~2s later and started SOLIDWORKS. The suspected+    /// difference is the startup context — `DETACHED_PROCESS |+    /// CREATE_NO_WINDOW` and the show state that rides with it — so the three+    /// routes above `cmdStart` all hand the link to the SHELL with a normal show+    /// state, by three independent mechanisms. The bridge does not have to know+    /// which one is right: `crate::launch` tries them in order and keeps the one+    /// that works.     ///-    /// `raw_arg` rather than `arg`: `cmd.exe` does its own command-line parsing,-    /// and Rust's argument escaper is written for the CRT convention, so a path-    /// with a space in it (which every one of these has) arrives at `start`-    /// mis-split. DETACHED_PROCESS | CREATE_NO_WINDOW so no console flashes on-    /// the user's desktop — this bridge never puts a window on screen.+    /// `raw_arg` on the `cmd` route rather than `arg`: `cmd.exe` does its own+    /// command-line parsing, and Rust's escaper is written for the CRT+    /// convention, so a path with a space in it (which every one of these has)+    /// arrives at `start` mis-split.+    /// What an invoke was able to say about what it started.+    ///+    /// `Some((pid, created_at))` is AUTHORITY TO TERMINATE, and the only thing+    /// that is. `None` means the route ran but cannot say — which is a first-+    /// class answer: the bridge then never adopts a chain from that route and+    /// never kills anything on its behalf. See `launch::AttributionRule`.     #[cfg(windows)]-    fn spawn_shortcut(shortcut: &str) -> Result<(), HostError> {+    fn spawn_shortcut(shortcut: &str, route: &str) -> Result<Option<(u32, Option<u64>)>, HostError> {         use std::os::windows::process::CommandExt;         const DETACHED_PROCESS: u32 = 0x0000_0008;         const CREATE_NO_WINDOW: u32 = 0x0800_0000;@@ -948,17 +1681,55 @@ impl ComBackend {                 "the shortcut path contains a quote character and will not be run",             ));         }-        std::process::Command::new("cmd.exe")-            .raw_arg(format!("/c start \"\" \"{shortcut}\""))-            .creation_flags(DETACHED_PROCESS | CREATE_NO_WINDOW)-            .spawn()-            .map(|_| ())-            .map_err(|e| {-                HostError::coded(-                    "host_app_launch_blocked",-                    format!("could not invoke the shortcut: {e}"),-                )-            })+        if !crate::launch::is_route(route) {+            return Err(HostError::coded(+                "host_app_launch_blocked",+                format!("'{route}' is not a launch route this bridge knows"),+            ));+        }+        let blocked = |e: std::io::Error| {+            HostError::coded(+                "host_app_launch_blocked",+                format!("could not invoke the shortcut via '{route}': {e}"),+            )+        };+        match route {+            // ShellExecuteExW with an EXPLICIT SW_SHOWNORMAL, and+            // SEE_MASK_NOCLOSEPROCESS so the shell hands back the process it+            // created. Runs here, on the com host's thread, because the shell's+            // link resolver needs an STA apartment and this is the only thread+            // in the bridge that has one.+            "shellExecute" => crate::launchos::shell_execute_lnk(shortcut).map_err(|e| {+                HostError::coded("host_app_launch_blocked", format!("route 'shellExecute': {e}"))+            }),+            // Start-Process -PassThru PRINTS the pid, and the PowerShell child+            // is waited on, so a policy block or a bad path is reported as+            // "this route started nothing" instead of being mistaken later for+            // a stall in a launcher that never ran.+            "powershell" => crate::launchos::powershell_start_lnk(shortcut).map_err(|e| {+                HostError::coded("host_app_launch_blocked", format!("route 'powershell': {e}"))+            }),+            // NOT ATTRIBUTABLE. The shell forwards the link to an existing+            // explorer process and returns nothing, so there is no handle and+            // no pid — and therefore, later, no kill.+            "explorer" => std::process::Command::new("explorer.exe")+                .arg(shortcut)+                .creation_flags(DETACHED_PROCESS)+                .spawn()+                .map(|_| None)+                .map_err(blocked),+            // NOT ATTRIBUTABLE, and the route that stalled five times out of+            // five. Kept last rather than deleted: it is the one route proven+            // to at least START the chain on this machine. `raw_arg` because+            // cmd.exe does its own parsing and Rust's escaper is written for+            // the CRT convention, so a path with a space arrives mis-split.+            _ => std::process::Command::new("cmd.exe")+                .raw_arg(format!("/c start \"\" \"{shortcut}\""))+                .creation_flags(DETACHED_PROCESS | CREATE_NO_WINDOW)+                .spawn()+                .map(|_| None)+                .map_err(blocked),+        }     }      fn authorize(@@ -981,9 +1752,22 @@ impl ComBackend {         destination: Option<&str>,         always: bool,     ) -> Result<(), HostError> {-        let clobbers = destination-            .map(|d| !d.is_empty() && std::path::Path::new(d).exists())-            .unwrap_or(false);+        // THE SAME THREE-STATE RULE THE SERVER USES, from the same function —+        // this is the INDEPENDENT veto, and two vetoes that disagree about what+        // "the destination is free" means are one veto with extra steps. An+        // unverifiable destination refuses here too, and the com host is the layer+        // most likely to hit it: it is a child of ab, and it may not hold the+        // user's network token at all.+        let clobbers = match crate::writes::destination_state(destination) {+            crate::writes::Destination::Occupied => true,+            crate::writes::Destination::Free => false,+            crate::writes::Destination::Unverifiable(io) => {+                return Err(HostError::coded(+                    "destination_unverifiable",+                    crate::writes::unverifiable_message(destination.unwrap_or(""), &io),+                ));+            }+        };         let foreign = doc.map(|d| !self.host_owns(d)).unwrap_or(false);         if !clobbers && !foreign && !always {             return Ok(());@@ -1155,12 +1939,38 @@ impl Backend for ComBackend {                         "version": sw.string("RevisionNumber", &[]),                     }));                 }-                Self::spawn_shortcut(shortcut)?;+                // The SERVER chooses the route (it owns the state machine and+                // the memory of what worked). An absent route means the caller+                // is an older server: fall back to the first route rather than+                // refusing, so a version skew cannot make the bridge unable to+                // start SOLIDWORKS at all.+                let route = args+                    .get("route")+                    .and_then(|v| v.as_str())+                    .filter(|r| crate::launch::is_route(r))+                    .unwrap_or(crate::launch::ROUTES[0]);+                let root = Self::spawn_shortcut(shortcut, route)?;                 // One brief look, so a warm start reports attached immediately                 // instead of making the caller poll for something already true.                 let attached = self.app(false, true).is_ok();                 Ok(json!({                     "invoked": true,+                    "route": route,+                    // THE ATTRIBUTION, or an honest absence of one.+                    "rootPid": root.map(|(p, _)| p),+                    "rootCreatedAt": root.and_then(|(_, c)| c),+                    "attributionSource": match route {+                        "shellExecute" => "shellExecuteHandle",+                        "powershell" => "startProcessPassThru",+                        _ => "none",+                    },+                    "attributionNote": if root.is_some() {+                        Value::Null+                    } else {+                        Value::from(format!(+                            "route '{route}' cannot say what it started, so this bridge will not                              terminate anything on its behalf"+                        ))+                    },                     "attached": attached,                     "shortcut": shortcut,                     "version": if attached {@@ -1226,14 +2036,7 @@ impl Backend for ComBackend {                 }))             } -            "docs" => {-                let sw = self.app(false, true)?;-                let docs: Vec<Value> =-                    Self::documents(&sw)?.iter().map(Self::doc_info).collect();-                let active =-                    sw.obj("ActiveDoc", &[])?.map(|d| Self::doc_info(&d)).unwrap_or(Value::Null);-                Ok(json!({"docs": docs, "active": active}))-            }+            "docs" => self.cmd_docs(),              "open" => self.cmd_open(args), @@ -1254,7 +2057,14 @@ impl Backend for ComBackend {                         ],                     )?;                 }-                sw.call("CloseDoc", &[&Var::bstr(&title)])?;+                // BY PATH when the document has one — a title is not an+                // identity, and `CloseDoc` resolves by name without prompting.+                // `resolve` has already refused an ambiguous title+                // (`ambiguous_target`), so this is the second guard rather than+                // the only one.+                let path = doc.string("GetPathName", &[]).unwrap_or_default();+                let key = if path.trim().is_empty() { title.clone() } else { path.clone() };+                sw.call("CloseDoc", &[&Var::bstr(&key)])?;                 // A closed document is no longer ours: the server prunes its                 // registry the same way, and the two vetoes must not disagree                 // about who owns what.@@ -1346,6 +2156,32 @@ impl Backend for ComBackend {             "set_parameter" => self.cmd_set_parameter(args),             "inspect_bodies" => self.cmd_inspect_bodies(args),             "import" => self.cmd_import(args),++            "close_import_temps" => self.cmd_close_import_temps(args),++            // THE QUIT LADDER. One rung per call; the SERVER orchestrates and+            // measures, because the measurement must not be a COM call.+            "quit_rung" => self.cmd_quit_rung(args),++            // Drop every IDispatch this process holds. Called before any rung+            // and before any measurement — see `crate::quit`'s refcount note.+            "release_com" => {+                let had = self.sw.is_some();+                self.sw = None;+                Ok(json!({+                    "released": had,+                    // `Disp` is a refcounted IDispatch (Clone = AddRef, Drop =+                    // Release) and `self.sw` is the only reference this host+                    // caches, so with it dropped and no local in scope our+                    // outstanding count is zero.+                    "outstanding": 0,+                    "note": "every IDispatch this com host held has been released",+                }))+            }++            // Read-only: how many references we are holding right now. The+            // ladder asserts zero before it measures.+            "com_refs" => Ok(json!({"outstanding": usize::from(self.sw.is_some())})),             "save_as" => self.cmd_save_as(args),             "run_script" => self.cmd_run_script(args),             "add_component" => self.cmd_add_component(args),@@ -1497,8 +2333,95 @@ impl ComBackend {     /// did not create it", for an assembly created seconds earlier.     ///     /// An empty list is only believed when the count agrees it is empty.+    /// WALK the open documents one at a time, stopping at `max` or at `budget`.+    ///+    /// `GetDocuments` marshals EVERY handle in one call, and that is what killed+    /// the com host on Drew's 2144-document session: `GetDocumentCount` answered+    /// in 0.7 s, `GetDocuments` did not answer in 30 s, and the code above the cap+    /// then called `GetPathName` on all 2144 of them — 2144 more round trips — to+    /// fill in a field named `importTempsInSample`. The mock's `GetDocuments` was+    /// instant, so the whole degrade path was mock-proven and false live.+    ///+    /// `GetFirstDocument()` / `GetNext()` is the per-document road, and it was+    /// measured live on the 1342-document session: `$sw.GetFirstDocument()+    /// .GetNext().GetTitle()` answered immediately. So the cost is now O(what we+    /// actually look at) instead of O(everything open).+    ///+    /// Returns the documents visited and WHY the walk stopped — because "we+    /// stopped early" must never be reported as "that is all there was".+    ///+    /// The reason matters: a `GetNext` that fails mid-walk (the user closed+    /// something, and the iteration is invalidated) used to be indistinguishable+    /// from reaching the end, so a walk cut short after four of 2144 documents+    /// was reported as a completed drain.+    fn walk_documents(+        sw: &Disp,+        max: usize,+        budget: std::time::Duration,+    ) -> Result<(Vec<Disp>, WalkStop), HostError> {+        let deadline = std::time::Instant::now() + budget;+        let mut out: Vec<Disp> = Vec::new();+        let mut cur = sw.obj("GetFirstDocument", &[])?;+        let mut stop = WalkStop::ReachedEnd;+        while let Some(doc) = cur {+            if out.len() >= max {+                stop = WalkStop::HitMax;+                break;+            }+            if std::time::Instant::now() >= deadline {+                stop = WalkStop::TimedOut;+                break;+            }+            let next = doc.obj("GetNext", &[]);+            let failed = next.is_err();+            let next = next.ok().flatten();+            out.push(doc);+            if failed {+                // The ITERATION broke, which is not the same as the session+                // ending. Say so.+                stop = WalkStop::IterationFailed;+                break;+            }+            cur = next;+        }+        Ok((out, stop))+    }++    /// Is a document with this exact name still open? `GetOpenDocumentByName`+    /// takes the full path for a document that has one, and it is ONE call — the+    /// cheap, exact way to verify a close did what it was asked to.+    fn open_document_by_name(sw: &Disp, name: &str) -> Option<Disp> {+        sw.obj("GetOpenDocumentByName", &[&Var::bstr(name)]).ok().flatten()+    }+     fn documents(sw: &Disp) -> Result<Vec<Disp>, HostError> {-        let mut count = -1i32;+        // NEVER MARSHAL A FLOODED SESSION. Above the cap this call cannot be+        // completed in any budget a caller would wait for, and its failure mode is+        // a 30s wedge and a killed com host — so it refuses, in ONE place, for+        // every caller that would otherwise have discovered it the hard way.+        // Callers that can work from a count and a sample do that instead.+        if let Some(c) = Self::document_count(sw) {+            if c as usize > super::host::doc_enum_cap() {+                return Err(HostError::coded(+                    "docs_enumeration_capped",+                    format!(+                        "{c} documents are open — more than this bridge will marshal in one call \+                         ({}). GetDocuments returns every handle at once and did not answer within \+                         30s on a 2144-document session, which kills the com host; the count and a \+                         sample come back from swx_docs instead. This many open documents is \+                         almost always leaked STEP/IGES import temporaries: run \+                         swx_close_import_temps to drain them.",+                        super::host::doc_enum_cap()+                    ),+                ));+            }+        }+        +        // THE COUNT IS AN Option, and that is the whole point of this round's+        // fix. It used to be `unwrap_or(-1)`, and `-1 <= 0` made an UNREADABLE+        // count believe an empty enumeration — the exact road to bug #5 that+        // this function was written to close, left open inside the closure.+        let mut count: Option<i32> = None;         for attempt in 0..4u64 {             let docs: Vec<Disp> = sw                 .call("GetDocuments", &[])?@@ -1506,19 +2429,30 @@ impl ComBackend {                 .iter()                 .filter_map(|v| v.as_dispatch().map(Disp))                 .collect();-            count = sw.int("GetDocumentCount", &[]).unwrap_or(-1);-            if !docs.is_empty() || count <= 0 {+            if !docs.is_empty() {+                return Ok(docs);+            }+            count = sw.int("GetDocumentCount", &[]);+            // An empty list is believed ONLY when the count AGREES it is empty.+            // A count we could not read agrees with nothing.+            if count == Some(0) {                 return Ok(docs);             }             std::thread::sleep(std::time::Duration::from_millis(150 * (attempt + 1)));         }         Err(HostError::coded(             "docs_enumeration_failed",-            format!(-                "SOLIDWORKS reports {count} open document(s) but returned none — the enumeration \-                 failed, most likely because it was busy. NOTHING was concluded from this read; \-                 retry the call."-            ),+            match count {+                Some(c) => format!(+                    "SOLIDWORKS reports {c} open document(s) but returned none — the enumeration \+                     failed, most likely because it was busy. NOTHING was concluded from this \+                     read; retry the call."+                ),+                None => "SOLIDWORKS returned no documents AND would not say how many are open, so \+                         this bridge cannot tell an empty session from a failed enumeration. \+                         NOTHING was concluded from this read; retry the call."+                    .to_string(),+            },         ))     } @@ -1526,13 +2460,23 @@ impl ComBackend {     /// only report what was open before and what survived.     fn cmd_close_all_documents(&mut self, args: &Value) -> Result<Value, HostError> {         let sw = self.app(false, true)?;-        let before: Vec<Value> = sw-            .call("GetDocuments", &[])?-            .as_array()-            .iter()-            .filter_map(|v| v.as_dispatch().map(Disp))-            .map(|d| Self::doc_info(&d))-            .collect();+        // ABOVE THE CAP the lists are not affordable — `GetDocuments` on a+        // 2144-document session does not answer in 30s — but the ACT is one COM+        // call and the user may well want it. So the flooded session gets counts+        // instead of lists, and says so; it never gets a list that is silently a+        // sample, and it never gets a wedge.+        let count_before = Self::document_count(&sw);+        let capped = count_before+            .map(|c| c as usize > super::host::doc_enum_cap())+            .unwrap_or(false);+        // `documents()`, so a contradicted empty enumeration cannot make a+        // DESTRUCTIVE verb report that it closed nothing when it closed+        // everything the user had open.+        let before: Vec<Value> = if capped {+            Vec::new()+        } else {+            Self::documents(&sw)?.iter().map(Self::doc_info).collect()+        };         let include_unsaved =             args.get("closeUnsaved").and_then(|v| v.as_bool()).unwrap_or(false);         let would_prompt: Vec<Value> = before@@ -1544,18 +2488,26 @@ impl ComBackend {             .call("CloseAllDocuments", &[&Var::boolean(include_unsaved)])?             .as_bool()             .unwrap_or(false);-        let remaining: Vec<Value> = sw-            .call("GetDocuments", &[])?-            .as_array()-            .iter()-            .filter_map(|v| v.as_dispatch().map(Disp))-            .map(|d| Self::doc_info(&d))-            .collect();+        // Empty here is EXPECTED and believable — `documents()` accepts an+        // empty list the count agrees with, and only refuses one it contradicts.+        let count_after = Self::document_count(&sw);+        let still_capped =+            count_after.map(|c| c as usize > super::host::doc_enum_cap()).unwrap_or(false);+        let remaining: Option<Vec<Value>> = if still_capped {+            None+        } else {+            Some(Self::documents(&sw)?.iter().map(Self::doc_info).collect())+        };         Ok(json!({             "closedAll": ok,-            "closed": before,-            "remaining": remaining,-            "wouldPrompt": would_prompt,+            // NULL, NOT AN EMPTY LIST, when the session was too flooded to+            // enumerate. An empty list here would read as "nothing was open".+            "closed": if capped { Value::Null } else { json!(before) },+            "remaining": remaining.as_ref().map(|r| json!(r)).unwrap_or(Value::Null),+            "documentCountBefore": count_before,+            "documentCountAfter": count_after,+            "listsOmittedTooManyDocuments": capped || still_capped,+            "wouldPrompt": if capped { Value::Null } else { json!(would_prompt) },             "closeUnsaved": include_unsaved,         }))     }@@ -1986,14 +2938,18 @@ impl ComBackend {         // FAIL CLOSED. If we cannot count the open documents we cannot tell         // whether LoadFile4 already imported the file, and guessing wrong runs         // the import a second time — two documents, one of them untracked.-        let before = match sw.call("GetDocuments", &[]) {-            Ok(d) => d.as_array().len(),-            Err(e) => {+        // The COUNT, not the enumeration: `GetDocumentCount` is one call and+        // answers even in a session holding hundreds of leaked temps, whereas+        // marshalling that many document handles is what times out. Import must+        // not become impossible just because earlier imports were not drained.+        let before = match Self::document_count(&sw) {+            Some(c) => c,+            None => {                 return Err(HostError::detailed(-                    "cannot import: SOLIDWORKS would not report its open documents, so there is \-                     no way to tell afterwards whether the import already happened"+                    "cannot import: SOLIDWORKS would not report how many documents are open, so \+                     there is no way to tell afterwards whether the import already happened"                         .to_string(),-                    e.message,+                    "GetDocumentCount returned nothing".to_string(),                 ))             }         };@@ -2008,37 +2964,69 @@ impl ComBackend {         );         let load4_err = load4.as_ref().err().map(|e| e.message.clone());         let imported = load4.ok().and_then(|v| v.as_dispatch()).map(Disp);-        let after = match sw.call("GetDocuments", &[]) {-            Ok(d) => d.as_array().len(),-            Err(e) => {-                return Err(HostError::detailed(-                    "the import may or may not have completed: SOLIDWORKS stopped reporting its \-                     open documents. Check swx_docs before retrying — retrying blind could import \-                     the file twice."+        // OWN IT THE MOMENT IT EXISTS. Registration used to happen in the+        // dispatcher, on the way out — so any failure AFTER the document was+        // created (a count that stopped answering, a timeout, a kill) left a+        // document open that this host would then refuse to close, because its+        // own record said it had never made one. `register_created` persists, so+        // this survives a respawn as well as a failure.+        let born = imported.as_ref().map(Self::doc_info);+        if let Some(doc) = born.clone() {+            self.register_created(&doc);+        }+        let after = match Self::document_count(&sw) {+            Some(c) => c,+            None => {+                let mut e = HostError::detailed(+                    "the import may or may not have completed: SOLIDWORKS stopped reporting how \+                     many documents are open. Check swx_docs before retrying — retrying blind \+                     could import the file twice."                         .to_string(),-                    e.message,-                ))+                    "GetDocumentCount returned nothing".to_string(),+                );+                e.created = born;+                return Err(e);             }         };+        // THE NET-COUNT ASSERTION. A clean import raises the open-document count+        // by exactly one; anything else is reported so a caller is never told+        // "imported" for a no-op or a double.+        let net = after - before;         if let Some(doc) = imported {             return Ok(json!({                 "imported": Self::doc_info(&doc),                 "via": "LoadFile4",                 "errors": errors,-                "documentsOpened": after.saturating_sub(before),+                "documentsOpened": net,+                "netCountOk": net == 1,+                "documentCount": after,+                "_hint": import_open_hint(net),             }));         }         if after > before {             // It DID import; we just could not take the handle. Use the active             // document rather than importing it again.+            //+            // CAVEAT, and it is reported rather than silently assumed: under a+            // CONCURRENT second import (another caller, or a user importing by+            // hand at the same moment) `ActiveDoc` is whichever document became+            // active last, which may be the OTHER import. The net count still+            // proves that A document arrived; the title/path we report may+            // belong to the other one. The bridge serialises its own COM calls,+            // so this needs a second actor outside the bridge — and the honest+            // move is to say so in the hint, not to pretend the handle was ours.             let doc = sw                 .obj("ActiveDoc", &[])?                 .ok_or_else(|| HostError::msg("import added a document but none became active"))?;             return Ok(json!({                 "imported": Self::doc_info(&doc),                 "via": "LoadFile4 (handle recovered from ActiveDoc)",+                "titleMayBeAnotherConcurrentImport": true,                 "errors": errors,-                "documentsOpened": after - before,+                "documentsOpened": net,+                "netCountOk": net == 1,+                "documentCount": after,+                "_hint": format!("{}{}", import_open_hint(net), RECOVERED_HANDLE_CAVEAT),             }));         }         let ok = sw.call("LoadFile2", &[&Var::bstr(path), &Var::bstr("")])?.as_bool().unwrap_or(false);@@ -2145,13 +3133,22 @@ impl ComBackend {                 }))             }         };-        let docs: Vec<Value> = sw-            .call("GetDocuments", &[])?-            .as_array()-            .iter()-            .filter_map(|v| v.as_dispatch().map(Disp))-            .map(|d| Self::doc_info(&d))-            .collect();+        // DEGRADE ABOVE THE CAP, exactly as `cmd_docs` does — this is called by+        // `ownership_context` on nearly every verb, so a 1342-document session+        // would wedge the whole bridge here, not just `swx_docs`. Over the cap+        // we report the COUNT and set `documentsTruncated`, and the SERVER must+        // then NOT prune its ownership registry against an empty list (an empty+        // list here means "too many to enumerate", not "nothing is open").+        let count = Self::document_count(&sw);+        // `None` (unreadable) is UNKNOWN-and-truncated, never "small enough to+        // enumerate": the server must not prune ownership against it and must not+        // pay the unbounded marshal. See cmd_docs.+        let truncated = count.map(|c| c as usize > super::host::doc_enum_cap()).unwrap_or(true);+        let docs: Vec<Value> = if truncated {+            Vec::new()+        } else {+            Self::documents(&sw)?.iter().map(Self::doc_info).collect()+        };         let active = sw.obj("ActiveDoc", &[])?.map(|d| Self::doc_info(&d));         let workspace = active             .as_ref()@@ -2168,7 +3165,8 @@ impl ComBackend {             "activeDocument": active.clone().map(|a| a.get("title").cloned().unwrap_or(Value::Null)).unwrap_or(Value::Null),             "activeDoc": active,             "documents": docs,-            "documentCount": sw.int("GetDocumentCount", &[]),+            "documentsTruncated": truncated,+            "documentCount": count,             "unsavedDocuments": unsaved,             "workspace": workspace,             "busy": sw.flag("CommandInProgress", &[]),@@ -2195,7 +3193,14 @@ impl ComBackend {     /// half to the server's window census.     fn cmd_check_recovery(&mut self) -> Result<Value, HostError> {         let sw = self.app(false, true)?;-        let docs = sw.call("GetDocuments", &[])?.as_array().len();+        // The COUNT, for the same reason cmd_status uses it: a contradicted+        // empty enumeration would report "no documents open" to a human asking+        // whether SOLIDWORKS is showing a recovery pane.+        // `null`, not 0, when SOLIDWORKS will not say. A human asking whether+        // the Document Recovery pane is up is asking about a session that has+        // just come back from a crash; "0 documents open" is the most+        // misleading possible answer to get wrong there.+        let docs = sw.int("GetDocumentCount", &[]).map(|c| c as usize);         Ok(json!({             "openDocuments": docs,             "comApiHasRecoveryCheck": false,@@ -2406,9 +3411,33 @@ impl ComBackend {                 let before = Self::component_count(&asm);                 for method in Self::insert_ladder(self.insert_method.as_deref()) {                     let called = Self::invoke_insert(&asm, method, r);-                    if Self::component_count(&asm) > before {-                        used = Some(method);-                        break 'passes;+                    let after = Self::component_count(&asm);+                    match (before, after) {+                        (Some(b), Some(a)) if a > b => {+                            used = Some(method);+                            break 'passes;+                        }+                        // COULD NOT COUNT. Trying the next method would insert+                        // the component a second time if the first one worked,+                        // so stop and say so rather than guess.+                        (None, _) | (_, None) => {+                            return Err(HostError::coded(+                                "component_count_failed",+                                format!(+                                    "SOLIDWORKS would not report how many components '{}' has, so \+                                     this bridge cannot tell whether the insert of {} succeeded — \+                                     and trying the next insert method could add it TWICE. \+                                     Nothing further was attempted; check the assembly with \+                                     swx_design_info and retry.",+                                    Self::doc_info(&asm)+                                        .get("title")+                                        .and_then(|t| t.as_str())+                                        .unwrap_or("the assembly"),+                                    r.file+                                ),+                            ));+                        }+                        _ => {}                     }                     attempts.push(json!({                         "method": method,@@ -2566,8 +3595,24 @@ impl ComBackend {      /// THE SUCCESS TEST. Not the return value of the insert call — see     /// `cmd_add_component`.-    fn component_count(asm: &Disp) -> usize {-        asm.call("GetComponents", &[&Var::boolean(true)]).map(|v| v.as_array().len()).unwrap_or(0)+    ///+    /// `None` = COULD NOT COUNT. The `unwrap_or(0)` this replaces made a failed+    /// enumeration look like an empty assembly, so `count > before` was false+    /// after an insert that had actually WORKED — and the method ladder moved on+    /// and inserted the SAME component again. Same shape as bug #11, with a+    /// duplicated component in the user's assembly for a consequence.+    fn component_count(asm: &Disp) -> Option<usize> {+        let comps = asm.call("GetComponents", &[&Var::boolean(true)]).ok()?;+        let listed = comps.as_array().len();+        if listed > 0 {+            return Some(listed);+        }+        // An empty list is believed only when the assembly agrees it is empty.+        match asm.int("GetComponentCount", &[]) {+            Some(0) => Some(0),+            Some(_) => None, // it says it has components and did not list them+            None => comps.is_null().then_some(0),+        }     }      /// The most recently added top-level component, best effort — used only for@@ -3001,6 +4046,18 @@ impl ComBackend {                 // v0.2 rename bug wearing a different hat, and a script has no                 // obvious place for the caller to have consented to it.                 // swx_save_as {copy:false} remains the deliberate rename.+                // THE SAME THREE-STATE RULE as the write gate: "could not+                // look" is not "nothing is there". This is a pre-check and+                // `save_as` re-checks below, but the defect class does not get to+                // live on in a second copy of the question.+                if let crate::writes::Destination::Unverifiable(io) =+                    crate::writes::destination_state(Some(path))+                {+                    return Err(HostError::coded(+                        "destination_unverifiable",+                        crate::writes::unverifiable_message(path, &io),+                    ));+                }                 if std::path::Path::new(path).exists() {                     return Err(HostError::msg(format!(                         "refusing to overwrite an existing file: {path}. A modelling script that \

@@ -26,18 +26,44 @@ pub struct HostError {     /// carrying `errorCode: None` and prose only — a caller cannot branch on     /// "document not open: Part2".     pub code: Option<String>,+    /// The HOST gave up on this call — its own inner deadline, not the+    /// server's. Carried over the wire so the server's `hung` verdict never has+    /// to guess a timeout from the wording of a message.+    pub timed_out: bool,+    /// A DOCUMENT THIS CALL CREATED BEFORE IT FAILED.+    ///+    /// Live, 2026-09-11: an import whose com host timed out AFTER `LoadFile4`+    /// had already succeeded left a document open that neither veto knew about —+    /// the server could not close it (not in its registry) and the host refused+    /// to (not in its `created` set), so it could only be closed by hand. A+    /// backend that made something during a call that then failed still MADE it,+    /// and that is the host's own first-hand evidence, not a claim the server+    /// asked it to believe.+    pub created: Option<Value>, }  impl HostError {+    /// Attach the document this failing call had already created. The dispatcher+    /// registers it, so the host owns what it made even when it could not say so.+    pub fn with_created(mut self, doc: Value) -> Self {+        self.created = Some(doc);+        self+    }+     pub fn msg(message: impl Into<String>) -> Self {-        Self { message: message.into(), detail: None, code: None }+        Self { message: message.into(), detail: None, code: None, timed_out: false, created: None }+    }++    /// A call the HOST abandoned. One half of `host_app_hung`.+    pub fn timeout(message: impl Into<String>) -> Self {+        Self { message: message.into(), detail: None, code: None, timed_out: true, created: None }     }     pub fn detailed(message: impl Into<String>, detail: impl Into<String>) -> Self {-        Self { message: message.into(), detail: Some(detail.into()), code: None }+        Self { message: message.into(), detail: Some(detail.into()), code: None, timed_out: false, created: None }     }     /// A failure a caller can branch on.     pub fn coded(code: &str, message: impl Into<String>) -> Self {-        Self { message: message.into(), detail: None, code: Some(code.to_string()) }+        Self { message: message.into(), detail: None, code: Some(code.to_string()), timed_out: false, created: None }     } } @@ -118,6 +144,34 @@ pub const READ_ONLY_COMMANDS: &[&str] = &[     //                        closing, and on a Connected edition stopping was —     //                        until this route existed — not recoverable at all.     "launch_shortcut",+    //   `close_import_temps`  CLOSES DOCUMENTS, and is exempt for one reason:+    //                        the only documents it can reach are STEP/IGES+    //                        conversion temporaries the BRIDGE ITSELF caused,+    //                        proven by the launcher's own contiguous path layout+    //                        (`is_import_temp` — a `Temp\swx<pid>\…\IC~~\`+    //                        chain no user document can have). That path IS the+    //                        ownership proof, and a stronger one than the+    //                        registry: it survives the pid change that made 1342+    //                        leaked temps un-ownable by a dead bridge process,+    //                        which is exactly the state the drain exists to+    //                        clear. Requiring the write opt-in would make the+    //                        leak undrainable in the DEFAULT posture — the bug+    //                        this verb was written to fix.+    //+    //                        BECAUSE the host's veto does not apply here, the+    //                        path proof is the ONLY guard, which is why it is a+    //                        segment walk and not two substring tests: a loose+    //                        version closed a user's saved file with `CloseDoc`+    //                        (no save prompt). See `is_import_temp`.+    "close_import_temps",+    //   `release_com` / `com_refs`  Drop or count the IDispatch pointers THIS+    //                        HOST holds. They change nothing in SOLIDWORKS — a+    //                        client releasing its own reference is not a write —+    //                        and the quit ladder's central invariant is that no+    //                        rung runs while we hold one, so they must be+    //                        callable without an opt-in.+    "release_com",+    "com_refs", ];  /// Does this command need authorization? Anything not known to be side-effect@@ -171,6 +225,347 @@ pub trait Backend { /// every document it ever looked at. pub const CREATED_KEYS: &[&str] = &["created", "imported"]; +/// Above this many open documents, an enumeration is not attempted — the count+/// is reported with a sample instead.+///+/// A live session was found holding 1342 open documents (8 GB), all leaked+/// STEP-import temporaries, and `swx_docs` blocked the full 30s marshalling+/// them and got the com host killed. Enumerating N documents is N handles times+/// several COM round-trips each; past a few hundred that cannot finish in any+/// budget. `GetDocumentCount` is ONE call and always answers, so the honest+/// report is "N open, here are the first few" — never a timeout, never a+/// fabricated empty list. See docs/IMPORT-LEAK.md.+pub const DOC_ENUM_CAP_DEFAULT: usize = 200;+/// The cap, overridable by `SWX_DOC_ENUM_CAP` for tests only (so the degrade+/// and drain paths can be exercised with a handful of documents rather than the+/// 200+ it would otherwise take to reach them). Never set in production.+pub fn doc_enum_cap() -> usize {+    std::env::var("SWX_DOC_ENUM_CAP")+        .ok()+        .and_then(|v| v.parse().ok())+        .unwrap_or(DOC_ENUM_CAP_DEFAULT)+}+/// How many titles/paths to sample when the count is over the cap.+pub const DOC_SAMPLE: usize = 10;++/// How long the SAMPLE WALK may take. A time box, not a doc count, because the+/// thing that went wrong live was cost per document under memory pressure: the+/// walk stops and says `sampleTruncatedByTime:true` rather than becoming the+/// 30-second wedge the cap exists to prevent.+pub const DOC_SAMPLE_BUDGET_SECS: u64 = 5;++/// How long the DRAIN may spend walking to find its batch. The drain is a bounded+/// batch by design (`max`), and this bounds the SEARCH for that batch too — on a+/// session where most documents are temps it finds them immediately, and on one+/// where they are rare it stops and reports what it scanned.+pub const DRAIN_WALK_BUDGET_SECS: u64 = 20;++/// The resolved `%TEMP%` this process would use, lowercased with `\` separators+/// and no trailing slash. `None` when the environment does not say.+///+/// The com host runs as the SAME USER as the SOLIDWORKS it is attached to (it is+/// a child of the bridge in that user's interactive session), so its own `%TEMP%`+/// IS the directory the launcher writes conversion temps into. That is what makes+/// this an anchor and not a guess.+/// THE TEMP DIRECTORIES A LEAKED IMPORT TEMP MAY LEGITIMATELY SIT UNDER, in+/// precedence order, deduplicated, lowercased and separator-normalised.+///+/// This is a SET and not a single directory because the drain compares a path+/// SOLIDWORKS reported against a directory THIS process resolved, and the two can+/// legitimately differ:+///+///   * the com host inherits Adom Bridge's environment, and ab may run under a+///     service profile, a redirected `TEMP`, or a different account from the+///     interactive session SOLIDWORKS lives in;+///   * the temps this verb exists for were written by a DIFFERENT, DEAD bridge+///     process (the design deliberately does not check the pid) — and 0.5.3+///     nonetheless assumed that process's `%TEMP%` was ours.+///+/// PRECEDENCE+///+///   1. `SWX_TEMP_ROOT`, when set, is the WHOLE set. It is the explicit override+///      the suite and the gate use to say "this is the resolved root", and an+///      operator can use it on a live machine once they know which directory+///      SOLIDWORKS is really writing under.+///   2. Otherwise: this process's `%TEMP%` (`TEMP`, then `TMP`, then `TMPDIR`),+///      AND the interactive user's own `HKCU\Environment\TEMP` expanded. Each is+///      a candidate only if it is readable and non-empty, and a document under+///      EITHER qualifies. Reading the user's registry value is the least invasive+///      way to learn the temp directory of the session SOLIDWORKS is in: its own+///      `GetTempPath` cannot be called from another process, and reading its PEB+///      to get at its environment block is invasive, version-fragile and needs+///      rights this bridge should not want.+///+/// An EMPTY set is not a permissive one: the drain refuses+/// (`temp_root_unknown`), because the resolved directory is the whole location+/// proof and the close it authorises does not prompt.+pub fn temp_roots() -> Vec<String> {+    let norm = |v: &str| -> Option<String> {+        let v = v.trim();+        if v.is_empty() {+            return None;+        }+        let n = v.replace('/', "\\").trim_end_matches('\\').to_ascii_lowercase();+        if n.is_empty() { None } else { Some(n) }+    };+    // MOCK MODE'S SIMULATED %TEMP%. The simulated launcher writes Windows paths+    // under `C:\Users\drew\AppData\Local\Temp`, and the real environment here+    // says `/tmp` — so without this the anchor would reject the mock's own temps+    // and the whole drain would be untested. The explicit override still wins, so+    // a test can model a MISMATCH (which is exactly what adversary8 does) or an+    // unknown root.+    if let Ok(v) = std::env::var("SWX_TEMP_ROOT") {+        return norm(&v).into_iter().collect();+    }+    if crate::is_mock() {+        return norm(crate::comhost::mock::MOCK_TEMP_ROOT).into_iter().collect();+    }+    let mut out: Vec<String> = Vec::new();+    let mut push = |v: Option<String>| {+        if let Some(v) = v {+            if !out.contains(&v) {+                out.push(v);+            }+        }+    };+    for key in ["TEMP", "TMP", "TMPDIR"] {+        if let Ok(v) = std::env::var(key) {+            push(norm(&v));+            break;+        }+    }+    push(user_registry_temp().and_then(|v| norm(&v)));+    out+}++/// The FIRST resolved temp root, for reporting and for the single-root callers.+/// `None` means no root could be resolved at all, which refuses.+pub fn temp_root() -> Option<String> {+    temp_roots().into_iter().next()+}++/// `HKCU\Environment\TEMP`, with `%USERPROFILE%`-style references expanded.+///+/// This is the interactive user's own setting — the one SOLIDWORKS inherits when+/// the user launches it — which is precisely the value this process's environment+/// may NOT have. Read-only, one value, no write of any kind.+#[cfg(windows)]+fn user_registry_temp() -> Option<String> {+    use winreg::enums::HKEY_CURRENT_USER;+    use winreg::RegKey;+    let key = RegKey::predef(HKEY_CURRENT_USER).open_subkey("Environment").ok()?;+    let raw: String = key.get_value("TEMP").or_else(|_| key.get_value("TMP")).ok()?;+    Some(expand_env_refs(&raw))+}++#[cfg(not(windows))]+fn user_registry_temp() -> Option<String> {+    None+}++/// `%USERPROFILE%\AppData\Local\Temp` -> the expanded path. An unresolvable+/// reference leaves the text alone, which then simply fails to match any path —+/// a miss, never a wildcard.+#[cfg(windows)]+fn expand_env_refs(raw: &str) -> String {+    let mut out = String::new();+    let mut rest = raw;+    while let Some(i) = rest.find('%') {+        out.push_str(&rest[..i]);+        let after = &rest[i + 1..];+        match after.find('%') {+            Some(j) => {+                let name = &after[..j];+                match std::env::var(name) {+                    Ok(v) => out.push_str(&v),+                    Err(_) => {+                        out.push('%');+                        out.push_str(name);+                        out.push('%');+                    }+                }+                rest = &after[j + 1..];+            }+            None => {+                out.push('%');+                out.push_str(after);+                rest = "";+            }+        }+    }+    out.push_str(rest);+    out+}++/// Is this the path of a STEP/IGES-import TEMPORARY — a document SOLIDWORKS+/// created under the bridge's own temp directory while converting an imported+/// file, never saved to a real location and unambiguously transient?+///+/// THREE things must all hold, and each closed a data-loss path:+///+/// 1. **LOCATION.** The path must sit under THIS USER'S RESOLVED `%TEMP%`+///    ([`temp_root`]), and that is the WHOLE location test. Proving the layout+///    alone was not enough: `D:\Temp\swx107688\IC~~\First.step.SLDPRT` has the+///    launcher's exact shape on a volume the launcher never writes to, and the+///    drain closes what qualifies with `CloseDoc`, which does not prompt. An+///    earlier version OR-ed in a shape test (`parent` ends+///    `appdata\local\temp`), which made the anchor advisory: a restored profile+///    backup at `E:\Backups\drew\AppData\Local\Temp\swx…\IC~~\…`, or another+///    user's profile, qualified — and when `%TEMP%` was unreadable the shape+///    alone decided. **No root, no drain**: `temp_root() == None` matches+///    nothing, and the verb refuses with `temp_root_unknown` rather than+///    reporting a silent zero.+/// 2. **THE PID FOLDER.** Immediately under `%TEMP%`, a `swx<digits>` segment+///    (the 8.3 short form `SWX107~1` counts). The pid VALUE is deliberately not+///    checked: the 1342 leaked temps belonged to a DEAD bridge process, and a+///    dead pid's directory is still under the same `%TEMP%`.+/// 3. **`IC~~` DIRECTLY UNDER IT**, then the file. Live evidence is exactly+///    `…\Temp\swx107688\IC~~\First.step.SLDPRT`; anything deeper is not a shape+///    the launcher produces. A miss costs memory, a false match costs data, and+///    those are not the same price.+pub fn is_import_temp(path: &str) -> bool {+    is_import_temp_under_any(path, &temp_roots())+}++/// THE LAUNCHER'S TAIL, wherever it lives: `…\swx<digits>\ic~~\<file>`.+///+/// This is deliberately NOT the drain's test — it is the NEAR MISS. A document+/// whose path carries this tail but sits under no resolved temp root is almost+/// certainly a leaked import temp whose `%TEMP%` this process does not know, and+/// the drain has to be able to SAY that: 0.5.3 matched nothing in that case and+/// reported "every open STEP/IGES import temporary was closed" with three of them+/// open. A miss is the safe direction for the close; it is not the safe direction+/// for the report.+pub fn has_import_temp_tail(path: &str) -> bool {+    tail_parts(path).is_some()+}++/// `(parent segments, pid segment)` when the path ends `…\swx<digits>\ic~~\<file>`.+/// Lowercased, separators normalised.+fn tail_parts(path: &str) -> Option<(Vec<String>, String)> {+    let lower = path.replace('/', "\\").to_ascii_lowercase();+    let segs: Vec<&str> = lower.split('\\').filter(|s| !s.is_empty()).collect();+    if segs.len() < 4 {+        return None;+    }+    let file_at = segs.len() - 1;+    let ic_at = file_at - 1;+    let pid_at = ic_at - 1;+    if segs[ic_at] != "ic~~" || !is_swx_pid_dir(segs[pid_at]) {+        return None;+    }+    Some((segs[..pid_at].iter().map(|s| s.to_string()).collect(), segs[pid_at].to_string()))+}++/// The same rule with the temp root made explicit, so every branch is testable+/// without mutating the process environment.+pub fn is_import_temp_under(path: &str, temp_root: Option<&str>) -> bool {+    let roots: Vec<String> = temp_root.into_iter().map(String::from).collect();+    is_import_temp_under_any(path, &roots)+}++/// The rule against a SET of resolved roots: the document qualifies if its pid+/// folder's parent IS one of them. An EMPTY set matches nothing — no root, no+/// drain.+pub fn is_import_temp_under_any(path: &str, roots: &[String]) -> bool {+    if roots.is_empty() {+        return false;+    }+    let Some((parent, _pid)) = tail_parts(path) else { return false };+    roots.iter().any(|root| {+        let root = root.replace('/', "\\").trim_end_matches('\\').to_ascii_lowercase();+        let want: Vec<&str> = root.split('\\').filter(|s| !s.is_empty()).collect();+        !want.is_empty()+            && parent.len() == want.len()+            && parent.iter().zip(want.iter()).all(|(a, b)| segment_equivalent(a, b))+    })+}++/// Two path segments that name the SAME directory: equal, or one is the other's+/// 8.3 short form.+///+/// Both sides have to be resolved, not just compared, because the two forms of+/// the same directory are both legitimate: `GetPathName` can hand back+/// `C:\Users\DREW~1\AppData\Local\Temp\…` for the very directory `%TEMP%`+/// reports as `C:\Users\drew\AppData\Local\Temp`. `GetLongPathName` would be+/// the Windows way to do it and is deliberately NOT used: it answers only for a+/// path that still exists on disk, and this rule is asked about documents whose+/// temp file may already have been deleted while the document is still open in+/// SOLIDWORKS. A rule whose answer depends on whether a file happens to exist is+/// not a rule you can reason about before a close.+fn segment_equivalent(a: &str, b: &str) -> bool {+    a == b || is_short_form_of(a, b) || is_short_form_of(b, a)+}++/// Is `short` the 8.3 short form of `long`? Both lowercased.+///+/// Windows builds it from the first six characters of the name with spaces and+/// periods removed, plus `~<n>`. The six-character head is required to be+/// EXACTLY that long (or the whole name, when the name is shorter), so `a~1`+/// cannot stand in for `adversary` — a loose prefix rule would let a short+/// segment match a great many long ones, which is the opposite of an anchor.+fn is_short_form_of(short: &str, long: &str) -> bool {+    let Some((head, tail)) = short.split_once('~') else { return false };+    if head.is_empty() || tail.is_empty() || !tail.bytes().all(|b| b.is_ascii_digit()) {+        return false;+    }+    let stripped: String = long.chars().filter(|c| *c != ' ' && *c != '.').collect();+    // WHEN DOES WINDOWS ACTUALLY GENERATE A TILDE NAME? Two cases, and they are+    // different shapes:+    //+    //  1. MANGLING. The long name does not fit 8.3 — over 8 characters, a space,+    //     a second period, an extension over 3. The short name is then the first+    //     SIX characters plus `~n`: `adversary` -> `ADVERS~1`. This is the case+    //     adversary pass 8 asked for, and it correctly rejects `a~1` standing in+    //     for `adversary`.+    //  2. COLLISION. The long name fits 8.3 perfectly and STILL gets a tilde,+    //     because another entry in the same directory claims the same short name.+    //     The short name is then the WHOLE name plus `~n`: `DREW~1` for `drew`.+    //     This is not hypothetical and it is not rare — it is the standard+    //     profile-directory case on a domain-joined machine, where `C:\Users\drew`+    //     sits beside `C:\Users\drew.ADOM` and the short name of the first IS+    //     `DREW~1`. Pass 8 read this acceptance as a pure widening; it is the+    //     collision form, and rejecting it would make the drain MISS real leaked+    //     temps on exactly the machine class this bridge ships to. A miss is the+    //     safe direction for a close and the wrong direction for a drain that+    //     exists because 1342 temps went unclosed.+    //+    // So: the mangled form needs the six-character head, and the collision form+    // needs the whole name. Neither admits a loose prefix, which was the actual+    // looseness worth removing.+    let long_len = long.chars().count();+    let needs_mangling = long_len > 8+        || long.contains(' ')+        || long.matches('.').count() > 1+        || long.split('.').nth(1).map(|ext| ext.chars().count() > 3).unwrap_or(false);+    let head_len = head.chars().count();+    if needs_mangling {+        head_len == stripped.chars().count().min(6) && stripped.starts_with(head)+    } else {+        head == stripped+    }+}++/// `swx107688`, or its 8.3 short form `swx107~1`. Lowercased input.+///+/// `swx` followed by DIGITS — not `swx-archive`, not `swxnotes`. The 8.3 form is+/// accepted because a path read through a short-name API legitimately carries it.+fn is_swx_pid_dir(seg: &str) -> bool {+    let Some(rest) = seg.strip_prefix("swx") else { return false };+    if rest.is_empty() {+        return false;+    }+    match rest.split_once('~') {+        Some((head, tail)) => {+            !head.is_empty()+                && !tail.is_empty()+                && head.bytes().all(|b| b.is_ascii_digit())+                && tail.bytes().all(|b| b.is_ascii_digit())+        }+        None => rest.bytes().all(|b| b.is_ascii_digit()),+    }+}+ /// The document a result says it created, if any. /// /// IT CAN BE NESTED. `run_script` reports the `new_document` result it ran as@@ -222,6 +617,12 @@ pub const COMMANDS: &[&str] = &[     "set_parameter",     "inspect_bodies",     "import",+    "close_import_temps",+    // The quit ladder: one rung per call, plus the two reference-discipline+    // commands the ladder's invariant depends on.+    "quit_rung",+    "release_com",+    "com_refs",     "save_as",     "run_script",     "run_macro",@@ -333,7 +734,13 @@ pub fn run() {     spawn_parent_watchdog();     let mut backend = make_backend(); -    send(&json!({"event": "ready", "pid": pid}));+    // THE VERSION IS PART OF THE HANDSHAKE. The com host is a separate process+    // and can be an OLDER BINARY than the server that spawned it (a half-applied+    // update, a stale exe left in a cache dir). A field this server expects and+    // that host never sends then reads as `false` — and one of those fields is+    // `closeOutcomeUnknown`, where a silently dropped `true` becomes "nothing+    // happened". A skew must be an explicit error, not a quietly missing field.+    send(&json!({"event": "ready", "pid": pid, "version": crate::BRIDGE_VERSION}));      // Test-only knob: emit junk around every response so the SERVER's     // skip-what-you-cannot-parse path is exercised over the real wire@@ -397,7 +804,7 @@ pub fn run() {             match verdict {                 Ok(Ok(())) => {}                 Ok(Err(e)) => {-                    send(&json!({"id": id, "ok": false, "error": e.message, "detail": e.detail, "errorCode": e.code}));+                    send(&json!({"id": id, "ok": false, "error": e.message, "detail": e.detail, "errorCode": e.code, "timedOut": e.timed_out}));                     continue;                 }                 Err(_) => {@@ -431,9 +838,19 @@ pub fn run() {                 }                 send(&json!({"id": id, "ok": true, "result": value}))             }-            Ok(Err(e)) => send(-                &json!({"id": id, "ok": false, "error": e.message, "detail": e.detail, "errorCode": e.code}),-            ),+            Ok(Err(e)) => {+                // A CALL THAT FAILED AFTER IT CREATED SOMETHING still created it.+                if let Some(doc) = e.created.clone() {+                    let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {+                        backend.register_created(&doc)+                    }));+                }+                send(+                &json!({"id": id, "ok": false, "error": e.message, "detail": e.detail,+                        "errorCode": e.code, "timedOut": e.timed_out,+                        "createdBeforeFailing": e.created}),+                )+            }             Err(panic) => {                 let what = panic                     .downcast_ref::<&str>()@@ -457,6 +874,91 @@ mod tests {     use super::*;     use serde_json::json; +    #[test]+    fn the_temp_anchor_is_the_whole_location_test() {+        let live = r"C:\Users\drew\AppData\Local\Temp";+        // UNDER the resolved root, in every form GetPathName can hand back.+        for p in [+            r"C:\Users\drew\AppData\Local\Temp\swx107688\IC~~\First.step.SLDPRT",+            "C:/Users/drew/AppData/Local/Temp/swx107688/IC~~/First.step.SLDPRT",+            r"C:\USERS\DREW\APPDATA\LOCAL\TEMP\SWX107~1\IC~~\FIRST.STEP.SLDPRT",+            // the 8.3 PROFILE form of the same directory+            r"C:\Users\DREW~1\AppData\Local\Temp\swx107688\IC~~\First.step.SLDPRT",+        ] {+            assert!(is_import_temp_under(p, Some(live)), "must still drain: {p}");+        }+        // NOT under it, however exactly the tail matches: a restored profile+        // backup on another volume, and another user's profile. The shape test+        // that used to be OR-ed in qualified both.+        for p in [+            r"E:\Backups\drew\AppData\Local\Temp\swx107688\IC~~\First.step.SLDPRT",+            r"C:\Users\someoneelse\AppData\Local\Temp\swx107688\IC~~\x.SLDPRT",+            r"D:\Temp\swx107688\IC~~\First.step.SLDPRT",+        ] {+            assert!(!is_import_temp_under(p, Some(live)), "not under the resolved %TEMP%: {p}");+        }+        // NO ROOT, NO DRAIN — an unreadable %TEMP% matches nothing at all.+        assert!(!is_import_temp_under(+            r"C:\Users\drew\AppData\Local\Temp\swx107688\IC~~\First.step.SLDPRT",+            None+        ));+    }++    #[test]+    fn a_document_under_either_resolved_root_drains_and_a_near_miss_is_recognisable() {+        // TWO candidate roots, because the com host's own %TEMP% and the+        // interactive user's HKCU\Environment\TEMP can legitimately differ and a+        // leaked temp may sit under either.+        let process_root = r"C:\Windows\Temp".to_string();+        let user_root = r"C:\Users\drew\AppData\Local\Temp".to_string();+        let roots = vec![process_root.clone(), user_root.clone()];+        let under_user = r"C:\Users\drew\AppData\Local\Temp\swx107688\IC~~\First.step.SLDPRT";+        let under_process = r"C:\Windows\Temp\swx4242\IC~~\Second.step.SLDPRT";+        let under_neither = r"E:\Backups\drew\AppData\Local\Temp\swx1\IC~~\Third.SLDPRT";+        for p in [under_user, under_process] {+            assert!(is_import_temp_under_any(p, &roots), "under one of the roots: {p}");+        }+        assert!(!is_import_temp_under_any(under_neither, &roots));+        // ...and with only ONE root known, only that one qualifies.+        assert!(is_import_temp_under_any(under_user, &[user_root]));+        assert!(!is_import_temp_under_any(under_user, &[process_root]));+        // NO ROOT, NO DRAIN — an empty set matches nothing at all.+        assert!(!is_import_temp_under_any(under_user, &[]));+        // THE NEAR MISS is the launcher's tail regardless of where it sits: it is+        // what lets the drain say "3 documents look like temps but are not under+        // the directory I compared against" instead of "nothing to do".+        for p in [under_user, under_process, under_neither] {+            assert!(has_import_temp_tail(p), "the launcher's tail: {p}");+        }+        // ...and it is not satisfied by the things round five and six closed.+        for p in [+            r"C:\Users\drew\AppData\Local\Temp\swxnotes\IC~~\keep.sldprt",+            r"C:\work\IC~~\drafts\Temp\swx_export\customer-master.sldprt",+            r"C:\Users\drew\AppData\Local\Temp\swx107688\IC~~",+        ] {+            assert!(!has_import_temp_tail(p), "not the launcher's tail: {p}");+        }+    }++    #[test]+    fn an_8_3_short_name_is_matched_by_the_real_rule_not_a_loose_prefix() {+        // The MANGLED form takes the six-character head; the COLLISION form takes+        // the whole name (`DREW~1` for `drew`, which is what a domain-joined+        // machine really produces when `drew.ADOM` sits beside `drew`). A loose+        // prefix — the looseness actually worth removing — is rejected in both.+        assert!(segment_equivalent("advers~1", "adversary"), "mangled: six-char head");+        assert!(!segment_equivalent("a~1", "adversary"), "a loose prefix is not a short name");+        assert!(segment_equivalent("advers~1", "advers"), "collision form of a 6-char name");+        assert!(!segment_equivalent("advers~1", "adverse"), "fits 8.3, and the head is not the name");+        assert!(segment_equivalent("drew~1", "drew"), "collision form of a name that fits 8.3");+        assert!(!segment_equivalent("drew~1", "drewson"), "neither form: 7 chars, head is not it");+        assert!(segment_equivalent("myfold~2", "my folder"), "a space forces mangling");+        // ...and the symmetry and the malformed cases.+        assert!(segment_equivalent("drew", "drew~1"));+        assert!(!segment_equivalent("drew~x", "drew"), "the tail must be digits");+        assert!(!segment_equivalent("drew", "someone"));+    }+     #[test]     fn a_created_document_is_found_flat_and_nested() {         let flat = json!({"created": {"title": "Part1", "path": ""}});

@@ -89,9 +89,74 @@ struct MockDoc {     /// BOM aggregates THESE when there are any, so a test can insert components     /// and then read a BOM built from what it inserted.     components: Vec<(String, String)>,+    /// Modelled STEP/IGES-import temporary: a document SOLIDWORKS created under+    /// the bridge's temp dir with an `IC~~` conversion path. The real backend+    /// recognises these by that path; the mock carries the fact as a flag and a+    /// synthetic temp path, so `close_import_temps` and the enumeration cap can+    /// be tested without a live SOLIDWORKS.+    import_temp: bool,+    temp_path: Option<String>, }  impl MockDoc {+    /// The mock's documents live in the com-host CHILD, which the server kills+    /// and respawns by design — so without this they vanished on every respawn,+    /// and the mock quietly modelled a SOLIDWORKS that closes everything when+    /// the bridge's sidecar restarts. It does not. That fiction made bug #5+    /// (ownership lost across a respawn) untestable: the documents were gone,+    /// so no verb could ever reach the ownership check.+    fn to_json(&self) -> Value {+        json!({+            "path": self.path,+            "title": self.title,+            "saved": self.saved,+            "docType": self.doc_type,+            "config": self.config,+            "dirty": self.dirty,+            "props": Value::Object(self.props.clone()),+            "material": self.material,+            "dimensions": Value::Object(self.dimensions.clone()),+            "bodies": self.bodies,+            "components": self.components.iter().map(|(f, c)| json!([f, c])).collect::<Vec<_>>(),+            "importTemp": self.import_temp,+            "tempPath": self.temp_path,+        })+    }++    fn from_json(v: &Value) -> Option<MockDoc> {+        let doc_type = match v.get("docType")?.as_str()? {+            "part" => "part",+            "assembly" => "assembly",+            "drawing" => "drawing",+            _ => return None,+        };+        Some(MockDoc {+            path: v.get("path")?.as_str()?.to_string(),+            title: v.get("title")?.as_str()?.to_string(),+            saved: v.get("saved").and_then(|x| x.as_bool()).unwrap_or(true),+            doc_type,+            config: v.get("config").and_then(|x| x.as_str()).unwrap_or("Default").to_string(),+            dirty: v.get("dirty").and_then(|x| x.as_bool()).unwrap_or(false),+            props: v.get("props").and_then(|x| x.as_object()).cloned().unwrap_or_default(),+            material: v.get("material").and_then(|x| x.as_str()).map(String::from),+            dimensions: v.get("dimensions").and_then(|x| x.as_object()).cloned().unwrap_or_default(),+            bodies: v.get("bodies").and_then(|x| x.as_array()).cloned().unwrap_or_default(),+            components: v+                .get("components")+                .and_then(|x| x.as_array())+                .map(|rows| {+                    rows.iter()+                        .filter_map(|r| {+                            Some((r.get(0)?.as_str()?.to_string(), r.get(1)?.as_str()?.to_string()))+                        })+                        .collect()+                })+                .unwrap_or_default(),+            import_temp: v.get("importTemp").and_then(|x| x.as_bool()).unwrap_or(false),+            temp_path: v.get("tempPath").and_then(|x| x.as_str()).map(String::from),+        })+    }+     fn opened(path: String, doc_type: &'static str, config: String) -> MockDoc {         let title = base_name(&path).to_string();         MockDoc {@@ -106,6 +171,8 @@ impl MockDoc {             dimensions: Map::new(),             bodies: Vec::new(),             components: Vec::new(),+            import_temp: false,+            temp_path: None,         }     } }@@ -141,10 +208,136 @@ pub struct MockBackend {     /// properties from — which is exactly the situation a BOM is in when its     /// components are files on disk rather than windows on screen.     files: std::collections::BTreeMap<String, Map<String, Value>>,+    /// A rung reported success and the simulated process is STILL GOING — it+    /// exits at this instant (epoch ms). A real `ExitApp` returns while+    /// SOLIDWORKS is still tearing itself down, so this is the divergence the+    /// mock has to be able to express: the census must see the process for a+    /// while after the rung returned.+    pending_exit_at_ms: Option<u64>,+}++/// The simulated machine, when a test has configured one. With a fake dir set,+/// the SIMULATOR is the single source of truth for whether a launch reached a+/// COM-attachable SOLIDWORKS — so a route that stalls never becomes attachable,+/// however long anybody polls, exactly as on the real machine.+fn fake_dir() -> Option<std::path::PathBuf> {+    std::env::var(crate::launchos::ENV_FAKE_DIR)+        .ok()+        .filter(|d| !d.is_empty())+        .map(std::path::PathBuf::from)+}++/// A runtime fault switch: a file in the scratch root, so a test can turn a+/// failure on and off BETWEEN calls without restarting the bridge. Test-only —+/// nothing in production ever creates these.+fn fault(name: &str) -> bool {+    crate::scratch::root().join(name).exists() }  const MOCK_VERSION: &str = "mock 33.0.0 (2025 SP0)"; +/// The `%TEMP%` the SIMULATED launcher writes under.+///+/// The real backend anchors the drain to the `%TEMP%` the com-host process+/// resolves, which on this Linux host would be `/tmp` — nothing like the Windows+/// path SOLIDWORKS reports. So the mock carries its own RESOLVED root and passes+/// it explicitly, which keeps the drain going through the same+/// `is_import_temp_under` rule the real backend uses rather than a mock-only+/// flag. Modelling this faithfully is what exposed the loose anchor twice.+pub const MOCK_TEMP_ROOT: &str = r"C:\Users\drew\AppData\Local\Temp";++/// The simulated resolved root, or `None` when the test asked for an UNREADABLE+/// `%TEMP%` (`mock-temp-root-unknown`) — the branch where the drain must refuse+/// instead of reporting that it found nothing.+/// PER-DOCUMENT COST, simulated. `SWX_MOCK_DOC_LATENCY_MS` (or the fault file+/// `mock-doc-latency-ms` holding a number) is the milliseconds a single document+/// costs to touch.+///+/// THIS EXISTS BECAUSE THE MOCK'S SPEED HID A LIVE WEDGE. `GetDocuments`+/// marshals every handle in one call; on Drew's 2144-document session it did not+/// answer within 30s and the com host was killed, while `GetDocumentCount`+/// answered in 0.7s. The mock's enumeration was instant, so the whole "degrades+/// instead of timing out" claim was mock-proven and false live. A mock that+/// cannot be slow cannot prove anything about a budget.+fn doc_latency_ms() -> u64 {+    if let Ok(v) = std::env::var("SWX_MOCK_DOC_LATENCY_MS") {+        if let Ok(n) = v.trim().parse::<u64>() {+            return n;+        }+    }+    std::fs::read_to_string(crate::scratch::root().join("mock-doc-latency-ms"))+        .ok()+        .and_then(|t| t.trim().parse::<u64>().ok())+        .unwrap_or(0)+}++/// Charge for touching `n` documents. Called wherever the real backend pays a+/// COM round trip per document — and, crucially, ONCE PER DOCUMENT IN THE WHOLE+/// SESSION wherever it would call `GetDocuments`, because that call's cost is a+/// function of everything open and not of what the caller wanted.+fn charge_docs(n: usize) {+    let ms = doc_latency_ms();+    if ms > 0 && n > 0 {+        std::thread::sleep(std::time::Duration::from_millis(ms.saturating_mul(n as u64)));+    }+}++/// THE OPEN-DOCUMENT COUNT, through the same seam that can be made UNREADABLE.+///+/// The mock used to read `self.docs.len()` directly, so `mock-doccount-none`+/// could not reach the drain — and the drain's discriminator has an arm that+/// fires only when the count cannot be read, which is the arm that decides+/// between "the call did nothing" and "a user's document may have closed". It+/// was dead code as far as the suite was concerned.+/// A PER-CALL SEQUENCE OF COM PROCESS IDS, so the attached session can CHANGE+/// between two reads inside one verb.+///+/// The quit ladder re-measures every precondition before every rung, and the+/// claim check is part of that sweep — but nothing could demonstrate it, because+/// the simulator's attached pid was fixed for the life of a run and the FRONT+/// GATE would always be the thing that caught a mismatch. `mock-com-pid` holds+/// whitespace-separated pids and hands out the next one on each read, so a test+/// can make the session identity valid at rung (a) and different by rung (b) —+/// which is the situation the per-rung sweep exists for.+fn mock_com_pid() -> Option<i64> {+    let path = crate::scratch::root().join("mock-com-pid");+    let text = std::fs::read_to_string(&path).ok()?;+    let pids: Vec<i64> = text.split_whitespace().filter_map(|t| t.parse().ok()).collect();+    if pids.is_empty() {+        return None;+    }+    // The cursor lives beside it, so the sequence survives the com host being+    // respawned mid-verb — which this bridge does on purpose.+    let cursor_path = crate::scratch::root().join("mock-com-pid.cursor");+    let i: usize = std::fs::read_to_string(&cursor_path)+        .ok()+        .and_then(|t| t.trim().parse().ok())+        .unwrap_or(0);+    let _ = std::fs::write(&cursor_path, (i + 1).to_string());+    // The LAST value stands once the sequence is exhausted: a test says what+    // changes, not how many times it will be asked.+    Some(*pids.get(i).unwrap_or(pids.last().expect("non-empty")))+}++fn mock_doc_count(n: usize) -> Option<i32> {+    if fault("mock-doccount-none") {+        None+    } else {+        Some(n as i32)+    }+}++fn mock_temp_roots() -> Vec<String> {+    if fault("mock-temp-root-unknown") {+        return Vec::new();+    }+    // The SAME resolver the real backend uses — which in mock mode answers with+    // MOCK_TEMP_ROOT unless SWX_TEMP_ROOT overrides it. Deferring to it means the+    // mock cannot drift into proving something about a root the real rule would+    // never accept, and it is what lets a test set a MISMATCHED root.+    super::host::temp_roots()+}+ /// The mock's preference table — the same NAMES the real backend exposes, so a /// caller cannot discover a preference here that SOLIDWORKS would reject. const MOCK_PREFERENCES: &[(&str, i32)] = &[("lengthUnitRaw", 53), ("unitSystemRaw", 48)];@@ -155,7 +348,7 @@ fn prop(value: &str) -> Value {  impl MockBackend {     pub fn new() -> Self {-        Self {+        let mut me = Self {             running: false,             created: crate::comhost::created_store::load_session().1,             created_session: crate::comhost::created_store::load_session().0,@@ -166,11 +359,160 @@ impl MockBackend {             active: None,             files: std::collections::BTreeMap::new(),             launching: None,+            pending_exit_at_ms: None,+        };+        me.restore();+        me+    }++    /// A backend with NO restored session — for the in-process unit tests,+    /// which all share one scratch root and would otherwise inherit each+    /// other's open documents. The integration suite gets a real restore+    /// because each bridge there has its own `SWX_SCRATCH_DIR`.+    #[cfg(test)]+    pub fn fresh() -> Self {+        Self {+            running: false,+            created: Vec::new(),+            created_session: None,+            generation: 0,+            untitled: 0,+            preferences: Map::new(),+            docs: Vec::new(),+            active: None,+            files: std::collections::BTreeMap::new(),+            launching: None,+            pending_exit_at_ms: None,+        }+    }++    /// Where the simulated SOLIDWORKS keeps its session between com-host+    /// processes. This is not bridge state: it stands in for the application's+    /// OWN memory, which a com-host respawn does not touch.+    fn session_file() -> std::path::PathBuf {+        crate::scratch::root().join("mock-solidworks-open-docs.json")+    }++    /// `ISldWorks::CloseDoc(name)` — BY NAME, which is what makes the close key+    /// matter: a full path identifies one document, a title identifies whichever+    /// SOLIDWORKS finds first.+    ///+    /// Modelled faithfully as of 0.5.6. Before that the mock removed by its own+    /// unique internal key, so it closed exactly the right document every time+    /// and 254 green tests said nothing whatsoever about the close key — while+    /// the real backend was passing a TITLE that Drew's session had two of.+    fn find_by_name(&self, name: &str) -> Option<usize> {+        // A full path wins, and matches only itself.+        if let Some(i) = self+            .docs+            .iter()+            .position(|d| {+                let p = Self::reported_path(d);+                !p.is_empty() && crate::verbs::same_path(p, name)+            })+        {+            return Some(i);+        }+        // Otherwise it is a TITLE, and SOLIDWORKS resolves it to the FIRST open+        // document that carries it.+        self.docs.iter().position(|d| d.title.eq_ignore_ascii_case(name))+    }++    fn close_doc_by_name(&mut self, name: &str) -> bool {+        // AN UNPROVEN PREMISE, MODELLED. `CloseDoc`'s help says only "name of the+        // document to close"; that a FULL PATH is accepted is this bridge's+        // assumption and has never been run live. With this fault set, the path+        // form returns SUCCESS and closes nothing — which is what the count-based+        // discriminator exists to catch, and what would otherwise look like a+        // drain that quietly did nothing.+        if fault("mock-closedoc-ignores-path") && name.contains('\\') {+            return true;+        }+        let Some(pos) = self.find_by_name(name) else { return false };+        let d = self.docs.remove(pos);+        self.created.retain(|(t, _)| t != &d.title);+        if self.active.as_deref() == Some(d.path.as_str()) {+            self.active = self.docs.first().map(|x| x.path.clone());         }+        true     } +    /// FLOOD THE SESSION, for the tests that are about scale.+    ///+    /// `SWX_MOCK_OPEN_DOCS=2144` opens that many import temporaries at start, so+    /// the suite can hold the exact session the live defect was found on: 2144+    /// documents, a cap of 200, and a `swx_docs` that must still answer in+    /// seconds. Creating them through `import` one at a time would take longer+    /// than the test it enables.+    fn flood(&mut self) {+        let Ok(n) = std::env::var("SWX_MOCK_OPEN_DOCS") else { return };+        let Ok(n) = n.trim().parse::<usize>() else { return };+        for i in 0..n {+            let key = format!("untitled:flood:{i}:Widget{i}.SLDPRT");+            let mut d = MockDoc::opened(key.clone(), "part", "Default".into());+            d.title = format!("Widget{i}.SLDPRT");+            d.saved = false;+            d.import_temp = true;+            d.temp_path = Some(format!("{MOCK_TEMP_ROOT}\\swx4242\\IC~~\\Widget{i}.SLDPRT"));+            self.docs.push(d);+        }+        self.active = self.docs.first().map(|d| d.path.clone());+    }++    /// Reload the simulated application's open documents. Called once, at host+    /// boot — so a respawned host attaches to the SAME session it left, exactly+    /// as `GetActiveObject` does against a SOLIDWORKS that never went away.+    fn restore(&mut self) {+        let Ok(text) = std::fs::read_to_string(Self::session_file()) else { return };+        let Ok(v) = serde_json::from_str::<Value>(&text) else { return };+        self.running = v.get("running").and_then(|x| x.as_bool()).unwrap_or(false);+        self.untitled = v.get("untitled").and_then(|x| x.as_u64()).unwrap_or(0) as u32;+        self.active = v.get("active").and_then(|x| x.as_str()).map(String::from);+        self.docs = v+            .get("docs")+            .and_then(|x| x.as_array())+            .map(|rows| rows.iter().filter_map(MockDoc::from_json).collect())+            .unwrap_or_default();+        if let Some(files) = v.get("files").and_then(|x| x.as_object()) {+            for (k, val) in files {+                if let Some(props) = val.as_object() {+                    self.files.insert(k.clone(), props.clone());+                }+            }+        }+    }++    /// Persist the simulated application's session. Called after EVERY command+    /// from the dispatch entry point, not from the individual commands, for the+    /// same reason `register_created` is: a command that forgets cannot exist.+    fn persist(&self) {+        let files: Map<String, Value> = self+            .files+            .iter()+            .map(|(k, v)| (k.clone(), Value::Object(v.clone())))+            .collect();+        let body = json!({+            "running": self.running,+            "untitled": self.untitled,+            "active": self.active,+            "docs": self.docs.iter().map(|d| d.to_json()).collect::<Vec<_>>(),+            "files": Value::Object(files),+        });+        let p = Self::session_file();+        if let Some(parent) = p.parent() {+            let _ = std::fs::create_dir_all(parent);+        }+        let _ = std::fs::write(p, body.to_string());+    }++    /// Find an open document by its key. CASE-INSENSITIVE, via the same+    /// `same_path` the server uses: SOLIDWORKS normalises what it reports (ask+    /// it to save `mine.sldprt` and it will tell you the document lives at+    /// `mine.SLDPRT`), so a mock that compared strings exactly would answer+    /// "document not open" for a document that is open — which is precisely+    /// what it did to a respawned host holding a restored session.     fn find(&self, path: &str) -> Option<&MockDoc> {-        self.docs.iter().find(|d| d.path == path)+        self.docs.iter().find(|d| d.path == path || crate::verbs::same_path(&d.path, path))     }      fn doc_info(&self, path: &str) -> Value {@@ -178,9 +520,19 @@ impl MockBackend {             None => Value::Null,             Some(d) => json!({                 "title": d.title,-                // Never saved -> no path. This is the ONE signal that separates-                // a scratch document from a real file, and both backends give it.-                "path": if d.saved { d.path.clone() } else { String::new() },+                // Never saved -> no path... EXCEPT an import temporary, whose+                // `GetPathName` on the real backend returns its+                // `…\Temp\swx<pid>\IC~~\…` conversion path even though it was+                // never saved anywhere real. The mock used to report "" for+                // those, so `is_import_temp` was FALSE against the mock's own+                // doc_info and every path-keyed consumer (the drain match, the+                // write gate's exists-check, save_as, ownership-by-path) was+                // exercised on a value the real backend never produces.+                "path": match (&d.temp_path, d.saved) {+                    (Some(t), _) => t.clone(),+                    (None, true) => d.path.clone(),+                    (None, false) => String::new(),+                },                 "type": d.doc_type,                 "config": d.config,                 // SOLIDWORKS DOES NOT ALWAYS ANSWER THIS. `GetSaveFlag` is@@ -203,11 +555,15 @@ impl MockBackend {     /// The mock's internal key (`untitled:Part1`) is not a path and must never     /// be matchable as one — treating it as one is what made every mock test     /// pass while the first real unsaved document was unaddressable.+    /// What `GetPathName` would return: a saved document's file, an import+    /// temporary's conversion path, and "" for a document that has neither.+    /// Must agree with `doc_info`, or resolve-by-path cannot find a document the+    /// listing just advertised.     fn reported_path(d: &MockDoc) -> &str {-        if d.saved {-            &d.path-        } else {-            ""+        match (&d.temp_path, d.saved) {+            (Some(t), _) => t,+            (None, true) => &d.path,+            (None, false) => "",         }     } @@ -218,7 +574,9 @@ impl MockBackend {         if let Some(path) =             args.get("path").and_then(|v| v.as_str()).filter(|s| !s.is_empty())         {-            return match self.docs.iter().find(|d| Self::reported_path(d) == path) {+            return match self.docs.iter().find(|d| {+                Self::reported_path(d) == path || crate::verbs::same_path(&Self::reported_path(d), path)+            }) {                 Some(d) => Ok(d.path.clone()),                 None => Err(HostError::coded(                     "document_not_open",@@ -298,12 +656,19 @@ impl MockBackend {             return false;         }         let Some(d) = self.find(key) else { return false };-        if d.saved {+        // BY THE PATH SOLIDWORKS WOULD REPORT, not by the mock's internal key and+        // not by `saved`. An import temporary is UNSAVED and still has a path+        // (its `IC~~` conversion file), so keying this on `saved` looked for a+        // pathless record while `register_created` had stored the path — and the+        // host refused to close the document the bridge had just imported. The+        // real backend has always compared `GetPathName`; this is that rule.+        let reported = Self::reported_path(d);+        if reported.is_empty() {+            self.created.iter().any(|(t, p)| p.is_none() && *t == d.title)+        } else {             self.created                 .iter()-                .any(|(_, p)| p.as_deref().map(|q| crate::verbs::same_path(q, &d.path)).unwrap_or(false))-        } else {-            self.created.iter().any(|(t, p)| p.is_none() && *t == d.title)+                .any(|(_, p)| p.as_deref().map(|q| crate::verbs::same_path(q, reported)).unwrap_or(false))         }     } @@ -328,9 +693,19 @@ impl MockBackend {     }      fn authorize_inner(&self, args: &Value, what: &str, doc: Option<&str>, destination: Option<&str>, always: bool) -> Result<(), HostError> {-        let clobbers = destination-            .map(|d| !d.is_empty() && std::path::Path::new(d).exists())-            .unwrap_or(false);+        // THE SAME THREE-STATE RULE, through the same function the real backend+        // and the server use. The mock's veto has to be the real veto or the+        // suite proves nothing about the layer that actually stops writes.+        let clobbers = match crate::writes::destination_state(destination) {+            crate::writes::Destination::Occupied => true,+            crate::writes::Destination::Free => false,+            crate::writes::Destination::Unverifiable(io) => {+                return Err(HostError::coded(+                    "destination_unverifiable",+                    crate::writes::unverifiable_message(destination.unwrap_or(""), &io),+                ));+            }+        };         let foreign = doc.map(|p| !self.host_owns(p)).unwrap_or(false);         if !clobbers && !foreign && !always {             return Ok(());@@ -393,6 +768,47 @@ impl MockBackend {         v     } +    /// Publish the simulated SOLIDWORKS pid into the fake-OS directory so the+    /// PROCESS CENSUS can see it.+    ///+    /// The quit ladder measures success by census (pid + creation time absent),+    /// never by a COM call — so the census and the mock backend must agree about+    /// which process is SOLIDWORKS. This is the same one-source-of-truth wiring+    /// `quit.jsonl` and launch attachability use: the backend publishes, the+    /// census reads.+    fn publish_session(&self) {+        let Some(dir) = fake_dir() else { return };+        let _ = std::fs::create_dir_all(&dir);+        let f = dir.join("mock-session");+        // ONLY WHEN IT IS ACTUALLY RUNNING. Publishing unconditionally put a+        // SOLIDWORKS into the census of every launch fixture the moment anything+        // called status — and a launch machine that sees SOLIDWORKS already up+        // correctly refuses to start a second copy, so the launch suite went+        // red. The census must describe the machine, not the fact that someone+        // asked about it.+        if self.running {+            let _ = std::fs::write(&f, self.session().to_string());+        } else {+            let _ = std::fs::remove_file(&f);+        }+    }++    /// THE SESSION IS OVER: the simulated process is gone, and the next one is a+    /// NEW SOLIDWORKS — new process id, and the untitled numbering restarts at+    /// Part1, which is the whole reason document ownership is scoped to a+    /// session.+    fn finish_exit(&mut self) {+        self.running = false;+        self.docs.clear();+        self.active = None;+        self.generation += 1;+        self.untitled = 0;+        self.end_session();+        let _ = std::fs::remove_file(Self::session_file());+        crate::comhost::created_store::clear();+        self.publish_session();+    }+     /// The SOLIDWORKS "process" went away: a new one gets a new id.     fn end_session(&self) {         let _ = std::fs::remove_file(crate::scratch::root().join("mock-solidworks-session"));@@ -487,15 +903,76 @@ impl Backend for MockBackend {     }      fn call(&mut self, cmd: &str, args: &Value) -> Result<Value, HostError> {+        let out = self.dispatch(cmd, args);+        // The simulated APPLICATION's session outlives the com host, because a+        // real one does. Written after every command so a respawn resumes from+        // exactly where the last one left off.+        self.persist();+        out+    }+}++impl MockBackend {+    fn dispatch(&mut self, cmd: &str, args: &Value) -> Result<Value, HostError> {+        // A SLOW EXIT that has now completed. Applied lazily rather than on a+        // timer so the simulator has no thread of its own and stays exactly as+        // deterministic as the file-backed census that measures it.+        if let Some(at) = self.pending_exit_at_ms {+            if crate::launchos::epoch_ms() as u64 >= at {+                self.pending_exit_at_ms = None;+                self.finish_exit();+            }+        }+        // A COM CALL THAT OVERRAN ITS BUDGET, simulated at the exact boundary+        // the server judges: the message the ComHost produces on a real timeout.+        // Test-only; it is the only way to reach the `host_app_hung` branch,+        // which needs a genuine timeout and not merely a failure.+        if fault("mock-com-timeout") && cmd != "ping" {+            return Err(HostError::timeout(format!(+                "com host did not answer '{cmd}' within 20s (SOLIDWORKS may be busy with a modal \+                 dialog or a huge rebuild); it was killed and respawns on the next call"+            )));+        }         match cmd {             "ping" => Ok(json!({"pong": true, "pid": std::process::id()})), -            "status" => Ok(json!({+            "status" => {+                // A REAL `status` CALLS `GetActiveObject`: it does not report a+                // cached flag, it asks the machine. So the mock asks the+                // simulator — otherwise `running` could only ever become true+                // inside `start`, and a session that came up while nobody was+                // calling swx_start (the user signing in, which is exactly the+                // case the sign-in work exists for) was invisible to swx_status.+                if !self.running {+                    if let Some(dir) = fake_dir() {+                        if crate::launchos::FakeOs::attachable(&dir) {+                            self.running = true;+                            self.launching = None;+                        }+                    }+                }+                self.publish_session();+                Ok(json!({                 "running": self.running,                 "version": if self.running { Value::from(MOCK_VERSION) } else { Value::Null },                 "openDocs": self.docs.len(),                 "attached": self.running,-            })),+                // THE PID COM WOULD REPORT: the simulated SOLIDWORKS process,+                // not the mock's internal session number. They are the same+                // process, and a scenario where they differ is not one that can+                // occur on a real machine.+                "processId": if self.running {+                    Value::from(mock_com_pid().unwrap_or_else(|| {+                        fake_dir()+                            .and_then(|d| crate::launchos::FakeOs::attached_sldworks_pid(&d))+                            .map(|p| p as i64)+                            .unwrap_or_else(|| self.session())+                    }))+                } else {+                    Value::Null+                },+                }))+            }              "start" => {                 // ATTACH vs LAUNCH, modelled faithfully: with launch:false this@@ -508,7 +985,15 @@ impl Backend for MockBackend {                 // attachable once it has had its time — so an ATTACH (launch:                 // false) starts failing and then starts succeeding, exactly as                 // it does while a Connected edition boots.-                if let Some(since) = self.launching {+                if let Some(dir) = fake_dir() {+                    // The simulator decides. A stalled route reports invoked but+                    // never attachable, which is the branch the whole launch+                    // state machine exists for.+                    if crate::launchos::FakeOs::attachable(&dir) {+                        self.running = true;+                        self.launching = None;+                    }+                } else if let Some(since) = self.launching {                     let after = std::env::var("SWX_MOCK_SHORTCUT_ATTACHES_AFTER_MS")                         .ok()                         .and_then(|v| v.parse::<u64>().ok());@@ -535,6 +1020,9 @@ impl Backend for MockBackend {                 }                 let was_launched = !self.running;                 self.running = true;+                if was_launched && self.docs.is_empty() {+                    self.flood();+                }                 Ok(json!({                     "started": true,                     "version": MOCK_VERSION,@@ -566,6 +1054,57 @@ impl Backend for MockBackend {                 if self.running {                     return Ok(json!({"invoked": false, "attached": true, "alreadyRunning": true}));                 }+                // The SERVER picks the route; the host only carries it out.+                let route = args+                    .get("route")+                    .and_then(|v| v.as_str())+                    .filter(|r| crate::launch::is_route(r))+                    .unwrap_or(crate::launch::ROUTES[0])+                    .to_string();+                if let Some(dir) = fake_dir() {+                    // Running the shortcut, simulated: the invocation is+                    // recorded and everything the state machine can observe —+                    // the chain, the launcher log, Run Begin, sldworks.exe,+                    // attachability — is derived from it by `FakeOs`.+                    let seq = crate::launchos::FakeOs::record_invoke(&dir, &route, &shortcut);+                    self.launching = Some(std::time::Instant::now());+                    // ATTRIBUTION, modelled per route exactly as the real thing+                    // can and cannot supply it: the two shell-handle routes hand+                    // back the root they started, the other two hand back+                    // nothing. And a route that started no process has nothing+                    // to attribute whichever route it is.+                    let sim = crate::launchos::FakeOs { dir: dir.clone() };+                    let inv = sim.invocations().into_iter().find(|i| i.seq == seq);+                    // A route attributes only when it CAN in principle AND+                    // this particular invocation actually got a handle back.+                    let reports_root = sim.route_reports_root(&route);+                    let root = match (crate::launch::route_is_attributable(&route), reports_root, inv) {+                        (true, true, Some(i)) => Some((i.catstart_pid(), (i.at_ms / 1000) as u64)),+                        _ => None,+                    };+                    return Ok(json!({+                        "invoked": true,+                        "route": route,+                        "rootPid": root.map(|(p, _)| p),+                        "rootCreatedAt": root.map(|(_, c)| c),+                        "attributionSource": match route.as_str() {+                            "shellExecute" => "shellExecuteHandle",+                            "powershell" => "startProcessPassThru",+                            _ => "none",+                        },+                        "attributionNote": if root.is_some() {+                            Value::Null+                        } else {+                            Value::from(format!(+                                "route '{route}' cannot say what it started, so this bridge will \+                                 not terminate anything on its behalf"+                            ))+                        },+                        "attached": false,+                        "shortcut": shortcut,+                        "version": Value::Null,+                    }));+                }                 let attaches = std::env::var("SWX_MOCK_SHORTCUT_ATTACHES").as_deref() == Ok("1");                 if attaches {                     self.running = true;@@ -581,6 +1120,7 @@ impl Backend for MockBackend {                 }                 Ok(json!({                     "invoked": true,+                    "route": route,                     "attached": attaches,                     "shortcut": shortcut,                     "version": if attaches { Value::from(MOCK_VERSION) } else { Value::Null },@@ -599,19 +1139,380 @@ impl Backend for MockBackend {                 self.generation += 1;                 self.untitled = 0;                 self.end_session();+                let _ = std::fs::remove_file(Self::session_file());                 crate::comhost::created_store::clear();                 Ok(json!({"stopped": true, "stillRunning": false, "rpcDisconnect": Value::Null}))             }              "docs" => {                 self.require_running()?;-                let docs: Vec<Value> =-                    self.docs.iter().map(|d| self.doc_info(&d.path)).collect();                 let active = match &self.active {                     Some(p) => self.doc_info(p),                     None => Value::Null,                 };-                Ok(json!({"docs": docs, "active": active}))+                // SOLIDWORKS DECLINING TO COUNT. Modelled so the+                // unreadable-count branch (which must NOT enumerate) has a test.+                if fault("mock-doccount-none") {+                    return Ok(json!({+                        "docs": [],+                        "count": Value::Null,+                        "documentCount": Value::Null,+                        "truncated": true,+                        "sample": [],+                        "active": active,+                        "_hint": "SOLIDWORKS would not say how many documents are open, so this                                   bridge did NOT try to enumerate them. `count:null` means                                   UNKNOWN, not zero. Retry.",+                    }));+                }+                let count = self.docs.len();+                if count > super::host::doc_enum_cap() {+                    // THE WALK, not the marshal: the real backend now visits+                    // exactly DOC_SAMPLE documents here, so the mock pays for+                    // exactly that many. Before this fix it paid for none, and a+                    // path that cost 2144 round trips live looked free.+                    charge_docs(self.docs.len().min(super::host::DOC_SAMPLE));+                    // Built from the doc's own fields, not via doc_info, to keep+                    // the iterator's immutable borrow of self.docs clean — and+                    // an import temp shows its synthetic IC~~ path here (as the+                    // real backend shows GetPathName) even though it is unsaved.+                    let sample: Vec<Value> = self+                        .docs+                        .iter()+                        .take(super::host::DOC_SAMPLE)+                        .map(|d| json!({+                            "title": d.title,+                            "path": d.temp_path.clone().unwrap_or_else(|| if d.saved { d.path.clone() } else { String::new() }),+                            "importTemp": d.import_temp,+                        }))+                        .collect();+                    // COUNTED OVER THE SAMPLE ONLY, like the real backend — the+                    // session-wide count used to be computed here with one path+                    // read per document, which is the 2144-round-trip defect.+                    let temps = self+                        .docs+                        .iter()+                        .take(super::host::DOC_SAMPLE)+                        .filter(|d| {+                            d.temp_path+                                .as_deref()+                                .map(|p| {+                                    super::host::is_import_temp_under_any(p, &mock_temp_roots())+                                })+                                .unwrap_or(false)+                        })+                        .count();+                    return Ok(json!({+                        "docs": [],+                        "count": count,+                        "documentCount": count,+                        "truncated": true,+                        "sample": sample,+                        "active": active,+                        "importTempsInSample": temps,+                        "importTempsInSampleOf": sample.len(),+                        "sampleTruncatedByTime": false,+                        "_hint": "too many documents to enumerate in the budget — count plus a                                   sample, not a timeout. Likely leaked import temps; run                                   swx_close_import_temps.",+                    }));+                }+                // UNDER the cap the real backend does marshal them all, so the+                // mock pays for all of them — which is what makes the cap itself+                // testable rather than decorative.+                charge_docs(count);+                let docs: Vec<Value> =+                    self.docs.iter().map(|d| self.doc_info(&d.path)).collect();+                Ok(json!({"docs": docs, "count": count, "truncated": false, "active": active}))+            }++            // THE QUIT LADDER, per-rung, scripted. `quit-script.json` in the+            // fake dir says what each rung does — declined / exited / dialog /+            // uipiBlocked / skipped — so every branch of the ladder has a test+            // instead of the mock's old "rung (a) always quits", which made+            // rungs (b)-(f) unreachable from any test.+            "quit_rung" => {+                let rung = args.get("rung").and_then(|v| v.as_str()).unwrap_or("").to_string();+                if !crate::quit::is_rung(&rung) {+                    return Err(HostError::coded(+                        "unknown_rung",+                        format!("'{rung}' is not a rung of the quit ladder"),+                    ));+                }+                // Every rung releases every reference, exactly as the real one+                // does — the ladder's invariant is that no rung runs, and no+                // measurement is taken, while the host holds an IDispatch.+                // The script entry is either a plain outcome ("exited") or an+                // object: {"result":"exited","exitAfterMs":4000}. The delay is+                // the important one — a real `ExitApp` RETURNS and the process+                // then takes seconds to go, and a single post-rung sample called+                // that "declined" and escalated into an exiting application.+                let entry = fake_dir().and_then(|d| {+                    std::fs::read_to_string(d.join("quit-script.json"))+                        .ok()+                        .and_then(|t| serde_json::from_str::<Value>(&t).ok())+                        .and_then(|v| v.get(&rung).cloned())+                });+                let (outcome, exit_after_ms) = match &entry {+                    Some(Value::String(s)) => (s.clone(), 0u64),+                    Some(v @ Value::Object(_)) => (+                        v.get("result").and_then(|x| x.as_str()).unwrap_or("declined").to_string(),+                        v.get("exitAfterMs").and_then(|x| x.as_u64()).unwrap_or(0),+                    ),+                    // No script at all: with no fake dir there is no census to+                    // measure against either, so the simplest useful default is+                    // a clean immediate exit.+                    _ if fake_dir().is_none() => ("exited".to_string(), 0),+                    _ => ("declined".to_string(), 0),+                };+                let mut detail = vec![format!("simulated rung '{rung}': {outcome}")];+                match outcome.as_str() {+                    "exited" | "quit" => {+                        // ONE source of truth: the census (FakeOs) reads this+                        // same file, so the measurement cannot disagree.+                        let now_ms = crate::launchos::epoch_ms() as u64;+                        let effective = now_ms + exit_after_ms;+                        if let Some(d) = fake_dir() {+                            let f = d.join("quit.jsonl");+                            let mut t = std::fs::read_to_string(&f).unwrap_or_default();+                            t.push_str(+                                &json!({"rung": rung, "atMs": now_ms, "effectiveAtMs": effective})+                                    .to_string(),+                            );+                            t.push('\n');+                            let _ = std::fs::write(&f, t);+                        }+                        // A QUIT ENDS THE SESSION, and the next one is a NEW+                        // SOLIDWORKS: new process id, and the untitled numbering+                        // restarts at Part1 — which is the whole reason document+                        // ownership is scoped to a session. The `stop` command+                        // has always modelled this; the ladder must too, or a+                        // test could not tell a real quit from a no-op.+                        if exit_after_ms == 0 {+                            self.finish_exit();+                            detail.push(+                                "the simulated SOLIDWORKS process exited; the session ended (new \+                                 process id, untitled numbering restarts)"+                                    .into(),+                            );+                        } else {+                            // STILL RUNNING for now: the rung returned, the+                            // process has not gone yet, and the census says so.+                            self.pending_exit_at_ms = Some(effective);+                            detail.push(format!(+                                "the rung returned; the simulated process exits {exit_after_ms} ms \+                                 later (it is still in the census until then)"+                            ));+                        }+                    }+                    "dialog" | "dialogAppeared" => {+                        if let Some(d) = fake_dir() {+                            let _ = std::fs::write(+                                d.join("dialog-open.json"),+                                json!({+                                    "hwnd": 9001,+                                    "className": "#32770",+                                    "title": "Save Modified Documents",+                                    "visible": true+                                })+                                .to_string(),+                            );+                        }+                        detail.push("a top-level dialog appeared".into());+                    }+                    _ => {}+                }+                Ok(json!({+                    "rung": rung,+                    "result": outcome,+                    "detail": detail.join("; "),+                    "comReferencesOutstanding": 0,+                }))+            }++            "release_com" => Ok(json!({+                "released": true,+                "outstanding": 0,+                "note": "the mock holds no IDispatch; the count is zero by construction",+            })),++            "com_refs" => Ok(json!({"outstanding": 0})),++            "close_import_temps" => {+                self.require_running()?;+                let max = args.get("max").and_then(|v| v.as_u64()).unwrap_or(200).max(1) as usize;+                let before = mock_doc_count(self.docs.len());+                // AN UNREADABLE %TEMP% IS A REFUSAL, NOT AN EMPTY DRAIN. The+                // anchor is the whole location proof, so without it nothing can+                // be identified as a temp — and reporting `closed:0, done:true`+                // for that would be the silent no-op this bridge keeps being+                // rewritten to stop making.+                let roots = mock_temp_roots();+                if roots.is_empty() {+                    return Ok(json!({+                        "closed": 0,+                        "closedDocs": [],+                        "documentCountBefore": before,+                        "documentCountAfter": before,+                        "done": false,+                        "batchLimit": max,+                        "tempRoot": Value::Null,+                        "tempRoots": [],+                    }));+                }+                // BY PATH, through the SAME `is_import_temp` the real backend+                // calls — not by a mock-only flag. The flag would have made the+                // mock prove something about itself while the real drain proved+                // something about paths, which is exactly how F1 (a loose path+                // proof that closed user documents) had no e2e test.+                let is_temp = |d: &MockDoc| -> bool {+                    d.temp_path+                        .as_deref()+                        .map(|p| super::host::is_import_temp_under_any(p, &roots))+                        .unwrap_or(false)+                };+                // ── THE WINDOW IS THE WHOLE POINT. The real backend walks a+                //    bounded window (about 4x the batch) one document at a time+                //    and reasons ONLY over what it passed. The mock used to select+                //    victims and check collisions across the entire session, so it+                //    closed documents its own reported scan never reached — and+                //    every window property of the real backend was untested.+                let window = self.docs.len().min(max.saturating_mul(4).max(max + 50));+                charge_docs(window);+                // The window as (title, reported path, is-a-temp, has-the-tail) —+                // everything the real backend learns by walking, and nothing it+                // could not have learned that way.+                let walked: Vec<(String, String, bool, bool)> = self+                    .docs+                    .iter()+                    .take(window)+                    .map(|d| {+                        (+                            d.title.clone(),+                            Self::reported_path(d).to_string(),+                            is_temp(d),+                            d.temp_path+                                .as_deref()+                                .map(super::host::has_import_temp_tail)+                                .unwrap_or(false),+                        )+                    })+                    .collect();+                let walk_complete = window >= self.docs.len();+                // The NEAR MISSES, over the WINDOW: the launcher's tail under a+                // directory that is not one of the roots this process resolved.+                let elsewhere: Vec<&(String, String, bool, bool)> =+                    walked.iter().filter(|(_, _, temp, tail)| !*temp && *tail).collect();+                let elsewhere_count = elsewhere.len() as u64;+                let elsewhere_sample = elsewhere.first().map(|(_, p, _, _)| p.clone());+                let total_temps = walked.iter().filter(|(_, _, temp, _)| *temp).count();+                // THE VICTIM IS (title, reported path) — the same pair the real+                // backend collects, because the close key is the whole point of+                // this round.+                let victims: Vec<(String, String)> = walked+                    .iter()+                    .filter(|(_, _, temp, _)| *temp)+                    .take(max)+                    .map(|(t, p, _, _)| (t.clone(), p.clone()))+                    .collect();+                let hit_limit = total_temps > victims.len();+                // A TITLE IS NOT AN IDENTITY. Any other open document sharing a+                // victim's title makes `CloseDoc` ambiguous — SOLIDWORKS would+                // pick — so the victim is skipped and the collision reported.+                let mut collisions: Vec<Value> = Vec::new();+                let victims: Vec<(String, String)> = victims+                    .into_iter()+                    .filter(|(title, path)| {+                        // OVER THE WINDOW, exactly as the real backend does — a+                        // same-titled document outside it is invisible to this+                        // check, which is what `titleCollisionsCheckedOver` says.+                        let others: Vec<String> = walked+                            .iter()+                            .filter(|(t, p, _, _)| t == title && !crate::verbs::same_path(p, path))+                            .map(|(_, p, _, _)| p.clone())+                            .collect();+                        if others.is_empty() {+                            return true;+                        }+                        let mut paths = vec![path.clone()];+                        paths.extend(others);+                        collisions.push(json!({"title": title, "paths": paths}));+                        false+                    })+                    .collect();+                let mut closed = Vec::new();+                let mut wrong_document_closed = false;+                let mut close_failed: Vec<Value> = Vec::new();+                let mut close_ignored_path = false;+                let mut close_outcome_unknown = false;+                for (title, path) in &victims {+                    // BY NAME, exactly as CloseDoc resolves it — see+                    // `close_doc_by_name`. Passing the title here would close+                    // whichever document SOLIDWORKS found first, which is the+                    // defect the previous round existed for.+                    let count_before_this = mock_doc_count(self.docs.len());+                    let asked = self.close_doc_by_name(path);+                    let still_open = self.find_by_name(path).is_some();+                    if asked && still_open {+                        // The SAME discriminator the real backend uses, including+                        // its third case: an UNREADABLE count cannot tell "nothing+                        // happened" from "something else closed", and saying so is+                        // the only honest answer.+                        let now = mock_doc_count(self.docs.len());+                        let nothing_happened = match (count_before_this, now) {+                            (Some(e), Some(n)) => n >= e,+                            _ => {+                                close_outcome_unknown = true;+                                close_failed.push(json!({+                                    "title": title, "path": path, "outcome": "undetermined",+                                    "documentCountBeforeClose": count_before_this,+                                    "why": "CloseDoc returned success, the document is still open, \+                                            and the count could not be read afterwards"}));+                                break;+                            }+                        };+                        if nothing_happened {+                            close_ignored_path = true;+                            close_failed.push(json!({"title": title, "path": path,+                                "why": "CloseDoc(path) did nothing and the count did not move"}));+                            break;+                        }+                        wrong_document_closed = true;+                        close_failed.push(json!({"title": title, "path": path,+                            "why": "CloseDoc reported success, the document is still open, and the \+                                    count DROPPED"}));+                        break;+                    }+                    if !asked || still_open {+                        close_failed.push(json!({"title": title, "path": path,+                            "why": "SOLIDWORKS declined to close it"}));+                        continue;+                    }+                    closed.push(json!({"title": title, "path": path}));+                }+                let after = mock_doc_count(self.docs.len());+                Ok(json!({+                    "closed": closed.len(),+                    "closedDocs": closed,+                    "documentCountBefore": before,+                    "documentCountAfter": after,+                    "done": !hit_limit+                        && walk_complete+                        && collisions.is_empty()+                        && close_failed.is_empty()+                        && !(elsewhere_count > 0 && closed.is_empty()),+                    "batchLimit": max,+                    "tempRoot": roots.first(),+                    "tempRoots": roots,+                    "importTempsElsewhere": elsewhere_count,+                    "importTempsElsewhereSample": elsewhere_sample,+                    "documentsScanned": window,+                    "walkTruncatedByTime": false,+                    "walkComplete": walk_complete,+                    "walkStop": if walk_complete { "reachedEnd" } else { "hitMax" },+                    "titleCollisions": collisions,+                    "titleCollisionsCheckedOver": window,+                    "closeFailed": close_failed,+                    "wrongDocumentClosed": wrong_document_closed,+                    "closeIgnoredPath": close_ignored_path,+                    "closeOutcomeUnknown": close_outcome_unknown,+                }))             }              "open" => {@@ -904,9 +1805,26 @@ impl Backend for MockBackend {                     &path,                     "interference detection needs an assembly (.sldasm)",                 )?;+                // SOLIDWORKS DECLINING TO COUNT, modelled — because `count:+                // null` is the most consequential null in this bridge (a+                // clearance report somebody builds a physical part from) and a+                // shape no test could reach is a shape nothing checks.+                if fault("mock-interference-count-unknown") {+                    return Ok(json!({+                        "doc": self.doc_info(&path),+                        "count": Value::Null,+                        "countKnown": false,+                        "interferences": [+                            {"components": ["bracket-1", "shaft-1"], "volumeM3": 2.1e-08}+                        ],+                        "listed": 1,+                    }));+                }                 Ok(json!({                     "doc": self.doc_info(&path),                     "count": 1,+                    "countKnown": true,+                    "listed": 1,                     "interferences": [                         {"components": ["bracket-1", "shaft-1"], "volumeM3": 2.1e-08}                     ],@@ -970,6 +1888,15 @@ impl Backend for MockBackend {             "new_document" => {                 self.running = true;                 let kind = args.get("type").and_then(|v| v.as_str()).unwrap_or("part");+                // EXHAUSTION, as the real thing reports it: SOLIDWORKS accepts+                // the call and hands back nothing. Observed live on 2026-09-03+                // for BOTH the part and the assembly template, at 17.4 GB and+                // 52 open documents.+                if fault("mock-newdoc-empty") {+                    return Err(HostError::msg(+                        "SOLIDWORKS created no document from C:\\ProgramData\\SolidWorks\\templates\\Part.prtdot (is the template valid?)",+                    ));+                }                 // The REAL untitled names SOLIDWORKS uses. A mock that invents                 // its own ("Assembly1") lets a test assert on a title the live                 // application will never produce.@@ -1212,15 +2139,100 @@ impl Backend for MockBackend {                 // document titled `smoke.SLDPRT`. The mock used the bare stem,                 // so it could not express the title collision the live run hit                 // when the suite imported a STEP beside its own saved part.+                let before = self.docs.len() as i32;                 let title = format!("{}.SLDPRT", file_stem(&path));-                let key = format!("untitled:{title}");+                // A UNIQUE key per import (SOLIDWORKS keeps every leaked temp as+                // its own document), and a synthetic IC~~ temp path so the drain+                // verb and the cap have something faithful to match — this is+                // how the 1342-temp leak is modelled.+                let n = self.untitled;+                let key = format!("untitled:import:{n}:{title}");+                // LIVE, 2026-09-11: a fresh `LoadFile4` import has NO PATH AT+                // ALL. The `IC~~` conversion paths belonged to the older route+                // that produced the 1342 leaked temps. `mock-import-pathless`+                // models the live behaviour so the identity-at-birth step, and+                // the drain's ownership-based rule, have the real shape to work+                // against.+                // BUG C's shape: the document IS created and the call then+                // times out. The server must reconcile on the respawned host+                // rather than leaving a document nobody owns.+                if fault("mock-import-timeout-after-open") {+                    // A SECOND document appearing in the same window — the user+                    // opening something of their own while our call hangs. The+                    // session then gains two, and only one of them is ours.+                    if fault("mock-open-extra-doc") {+                        let mut theirs = MockDoc::opened(+                            "C:\\users\\drew\\theirs.SLDPRT".into(),+                            "part",+                            "Default".into(),+                        );+                        theirs.title = "theirs.SLDPRT".into();+                        theirs.saved = true;+                        self.docs.push(theirs);+                    }+                    let title = format!("{}.SLDPRT", file_stem(&path));+                    let n = self.untitled;+                    let key = format!("untitled:import:{n}:{title}");+                    let mut doc = MockDoc::opened(key.clone(), "part", "Default".into());+                    doc.title = title;+                    doc.saved = false;+                    doc.import_temp = true;+                    doc.temp_path = None;+                    self.docs.push(doc);+                    self.active = Some(key.clone());+                    self.publish_session();+                    // IT MADE THE DOCUMENT. The error carries it, so the host+                    // owns what it made — exactly as the real backend now does by+                    // registering at birth rather than on the way out.+                    let info = self.doc_info(&key);+                    return Err(HostError::timeout(+                        "com host did not answer 'import' within 280s (the file was already                          loaded when it stopped answering)",+                    )+                    .with_created(info));+                }+                if fault("mock-import-pathless") {+                    let title = format!("{}.SLDPRT", file_stem(&path));+                    let n = self.untitled;+                    let key = format!("untitled:import:{n}:{title}");+                    let mut doc = MockDoc::opened(key.clone(), "part", "Default".into());+                    doc.title = title;+                    doc.saved = false;+                    doc.import_temp = true;+                    doc.temp_path = None;+                    doc.bodies.push(mock_body("Imported1", 50.0, 30.0, 20.0));+                    self.docs.push(doc);+                    self.active = Some(key.clone());+                    let after = self.docs.len() as i32;+                    return Ok(json!({+                        "imported": {"title": self.docs.last().map(|d| d.title.clone()),+                                     "path": "", "type": "part"},+                        "documentCountBefore": before,+                        "documentCountAfter": after,+                        "net": after - before,+                        "netCountOk": after - before == 1,+                    }));+                }+                let temp_path =+                    format!("{MOCK_TEMP_ROOT}\\swx4242\\IC~~\\{}-{n}.SLDPRT", file_stem(&path));                 let mut doc = MockDoc::opened(key.clone(), "part", "Default".into());                 doc.title = title;                 doc.saved = false;+                doc.import_temp = true;+                doc.temp_path = Some(temp_path);                 doc.bodies.push(mock_body("Imported1", 50.0, 30.0, 20.0));                 self.docs.push(doc);                 self.active = Some(key.clone());-                Ok(json!({"imported": self.doc_info(&key), "via": "LoadFile4", "errors": 0}))+                let after = self.docs.len() as i32;+                let net = after - before;+                Ok(json!({+                    "imported": self.doc_info(&key),+                    "via": "LoadFile4",+                    "errors": 0,+                    "documentsOpened": net,+                    "netCountOk": net == 1,+                    "documentCount": after,+                    "_hint": "Imported. This left ONE new open, unsaved document (like                               swx_new_document) — it stays open and holds memory until you save                               or close it. Importing repeatedly without closing is what leaks                               documents; swx_close_import_temps drains any left behind.",+                }))             }              "save_as" => {@@ -1299,8 +2311,30 @@ impl Backend for MockBackend {                 }))             } +            // NOTE ON COST: `app_state` reads the COUNT first and enumerates only+            // under the cap — so it is charged inside that branch, below.             "app_state" => {-                let docs: Vec<Value> = self.docs.iter().map(|d| self.doc_info(&d.path)).collect();+                self.publish_session();+                // A com host that cannot answer. The point of the switch is that+                // the SERVER must treat this as "I do not know" and keep its+                // ownership registry — which is bug #5.+                if fault("mock-fail-app-state") {+                    return Err(HostError::msg(+                        "com host did not answer 'app_state' (simulated: SOLIDWORKS is busy)",+                    ));+                }+                // DEGRADE ABOVE THE CAP, exactly as the real backend does: this is+                // read on nearly every verb, so a flooded session must report+                // the count and set documentsTruncated rather than enumerate.+                let count_known = !fault("mock-doccount-none");+                let count = self.docs.len();+                let truncated = !count_known || count > super::host::doc_enum_cap();+                let docs: Vec<Value> = if truncated {+                    Vec::new()+                } else {+                    charge_docs(count);+                    self.docs.iter().map(|d| self.doc_info(&d.path)).collect()+                };                 let active = self.active.as_ref().map(|p| self.doc_info(p));                 Ok(json!({                     "running": self.running,@@ -1308,7 +2342,8 @@ impl Backend for MockBackend {                     "activeDocument": active.clone().map(|a| a.get("title").cloned().unwrap_or(Value::Null)).unwrap_or(Value::Null),                     "activeDoc": active,                     "documents": docs,-                    "documentCount": self.docs.len(),+                    "documentsTruncated": truncated,+                    "documentCount": if count_known { Value::from(count) } else { Value::Null },                     "unsavedDocuments": self.docs.iter().filter(|d| d.dirty).count(),                     "workspace": self                         .active@@ -1318,7 +2353,10 @@ impl Backend for MockBackend {                         .unwrap_or("none"),                     "busy": false,                     "visible": self.running,-                    "processId": self.session(),+                    // THE SAME PER-CALL SEQUENCE `status` uses: this is the read+                    // the quit ladder's precondition sweep makes, so it is the+                    // one that has to be able to change between rungs.+                    "processId": mock_com_pid().unwrap_or_else(|| self.session()),                     "mainHwnd": if self.running { json!(4242) } else { Value::Null },                 }))             }@@ -1326,7 +2364,11 @@ impl Backend for MockBackend {             "check_recovery" => {                 self.require_running()?;                 Ok(json!({-                    "openDocuments": self.docs.len(),+                    "openDocuments": if fault("mock-doccount-unknown") {+                        Value::Null+                    } else {+                        Value::from(self.docs.len())+                    },                     "comApiHasRecoveryCheck": false,                     "note": "SOLIDWORKS exposes no COM member for the Document Recovery pane; \                              the server pairs this with the window census, which is where a \@@ -1454,6 +2496,18 @@ impl Backend for MockBackend {              "add_component" => {                 self.require_running()?;+                // AN UNCOUNTABLE ASSEMBLY. The real backend refuses to run the+                // insert ladder when it cannot tell whether the last insert+                // worked, because the next method would add the component a+                // SECOND time.+                if fault("mock-component-count-unknown") {+                    return Err(HostError::coded(+                        "component_count_failed",+                        "SOLIDWORKS would not report how many components the assembly has, so \+                         this bridge cannot tell whether the insert succeeded — and trying the \+                         next insert method could add it TWICE. Nothing further was attempted.",+                    ));+                }                 let path = self.resolve(args)?;                 self.require_assembly(                     &path,@@ -1594,6 +2648,14 @@ impl Backend for MockBackend {                             json!({"property": name, "value": value, "code": 1})                         }                         Op::SaveAs { path } => {+                            if let crate::writes::Destination::Unverifiable(io) =+                                crate::writes::destination_state(Some(path))+                            {+                                return Err(HostError::coded(+                                    "destination_unverifiable",+                                    crate::writes::unverifiable_message(path, &io),+                                ));+                            }                             if std::path::Path::new(path).exists() {                                 return Err(HostError::msg(format!(                                     "refusing to overwrite an existing file: {path}"@@ -1650,7 +2712,7 @@ mod tests {      #[test]     fn open_then_resolve_active_then_close_falls_back() {-        let mut b = MockBackend::new();+        let mut b = MockBackend::fresh();         // launch:true because opening no longer starts SOLIDWORKS on its own —         // the SERVER decides that, per edition (see swx_open / may_launch).         b.call("open", &json!({"path": "C:\\m\\a.sldasm", "launch": true})).unwrap();@@ -1667,14 +2729,14 @@ mod tests {     fn opening_a_document_does_not_start_solidworks_by_itself() {         // swx_open used to pass launch:true unconditionally, which made it a         // second road to CoCreateInstance that skipped the edition check.-        let mut b = MockBackend::new();+        let mut b = MockBackend::fresh();         let e = b.call("open", &json!({"path": "C:\\m\\a.sldprt"})).unwrap_err();         assert!(e.message.contains("not running"), "{}", e.message);     }      #[test]     fn bom_requires_an_assembly() {-        let mut b = MockBackend::new();+        let mut b = MockBackend::fresh();         b.call("open", &json!({"path": "C:\\m\\a.sldprt", "launch": true})).unwrap();         let e = b.call("bom", &json!({})).unwrap_err();         assert!(e.message.contains("assembly"), "{}", e.message);

@@ -53,15 +53,25 @@ pub struct SidecarError {     pub detail: Option<String>,     /// The host's branchable code, if it gave one.     pub code: Option<String>,+    /// DID THIS CALL EXCEED ITS BUDGET? Carried explicitly, because it is one+    /// half of the `host_app_hung` verdict and callers were deriving it by+    /// searching this struct's `message` for the words "did not answer" — a+    /// copy of the sentence built below, in two other files, that would have+    /// gone quietly false the day this wording changed.+    pub timed_out: bool, }  impl SidecarError {     fn new(message: impl Into<String>, detail: Option<String>) -> Self {-        Self { message: message.into(), detail, code: None }+        Self { message: message.into(), detail, code: None, timed_out: false }+    }++    fn timeout(message: impl Into<String>, detail: Option<String>) -> Self {+        Self { message: message.into(), detail, code: None, timed_out: true }     }      fn coded(message: impl Into<String>, detail: Option<String>, code: Option<String>) -> Self {-        Self { message: message.into(), detail, code }+        Self { message: message.into(), detail, code, timed_out: false }     } } @@ -257,14 +267,17 @@ impl ComHost {                             resp.get("detail").and_then(|v| v.as_str()).map(|s| s.to_string());                         let code =                             resp.get("errorCode").and_then(|v| v.as_str()).map(|s| s.to_string());-                        return Err(SidecarError::coded(message, detail, code));+                        let mut e = SidecarError::coded(message, detail, code);+                        // The HOST may have given up on the call itself.+                        e.timed_out = resp.get("timedOut").and_then(|v| v.as_bool()).unwrap_or(false);+                        return Err(e);                     }                     return Ok(resp.get("result").cloned().unwrap_or_else(|| json!({})));                 }                 Err(RecvTimeoutError::Timeout) => {                     let tail = tail_text(&live.tail);                     kill(guard.take());-                    return Err(SidecarError::new(+                    return Err(SidecarError::timeout(                         format!(                             "com host did not answer '{cmd}' within {}s (SOLIDWORKS may be busy \                              with a modal dialog or a huge rebuild); it was killed and respawns \@@ -432,6 +445,37 @@ fn spawn_child() -> Result<Live, SidecarError> {             Ok(line) => {                 if let Ok(v) = serde_json::from_str::<Value>(&line) {                     if v.get("event").and_then(|e| e.as_str()) == Some("ready") {+                        // PROTOCOL SKEW IS AN ERROR, NOT A SHRUG. A host older+                        // than this server does not send every field this server+                        // reads, and an absent field is indistinguishable from a+                        // `false` one unless somebody checks. The version is the+                        // one fact that makes the difference visible.+                        let their = v.get("version").and_then(|x| x.as_str());+                        match their {+                            Some(v) if v == crate::BRIDGE_VERSION => {}+                            Some(v) => {+                                let detail = format!(+                                    "com host reports version {v}, this server is {}. They are \+                                     separate binaries and a mismatched pair drops fields \+                                     silently — including the ones that say a close could not be \+                                     verified. Reinstall so both come from the same release.",+                                    crate::BRIDGE_VERSION+                                );+                                kill(Some(live));+                                return Err(SidecarError::new("com host version mismatch", Some(detail)));+                            }+                            None => {+                                let detail = format!(+                                    "the com host's ready line carries no version, so it is older \+                                     than {} and this server cannot tell which of its fields that \+                                     host never sends. Reinstall so both come from the same \+                                     release.",+                                    crate::BRIDGE_VERSION+                                );+                                kill(Some(live));+                                return Err(SidecarError::new("com host version unknown", Some(detail)));+                            }+                        }                         println!("[swx] com host up (pid {pid}, mock={})", crate::is_mock());                         return Ok(live);                     }

@@ -0,0 +1,3793 @@+//! LAUNCH RESILIENCE — the state machine that starts SOLIDWORKS and recovers+//! when the 3DEXPERIENCE launcher chain stalls.+//!+//! ## What went wrong, measured+//!+//! On 2026-09-04, five of five launches this bridge made produced a+//! `SWXDesktopLauncher` log that stopped at `SecurityContext:` and went no+//! further: no `Run Begin`, no helper log, no `sldworks.exe`. `CATSTART.exe` and+//! `SWXDesktopLauncher.exe` sat idle at ~50 MB forever. Every launch of the SAME+//! shortcut with the SAME arguments from an INTERACTIVE context — a Start-Menu+//! click, the crash reporter's "Restart SOLIDWORKS Design" button — reached+//! `Run Begin` about two seconds later and started SOLIDWORKS.+//!+//! The difference is the startup context. The bridge ran the shortcut through+//! `cmd.exe /c start` with `DETACHED_PROCESS | CREATE_NO_WINDOW`, and the+//! launcher's Run thread never started. That is a HYPOTHESIS, not a proven+//! cause, and this module is written so it does not need to be right: it tries+//! routes in order, DETECTS the stall from the launcher's own log, cleans up+//! after itself, and moves to the next one — then remembers which route worked+//! so the next launch starts there.+//!+//! ## The four failures this module answers+//!+//! | # | Failure | Answer here |+//! |---|---|---|+//! | A | the chain stalls before `Run Begin` | [`Supervisor`] watches the log, kills ONLY the chain it started, tries the next route |+//! | B | a second `swx_start` fires the launcher again | the attempt is persisted; a call during flight NEVER launches (`stillLaunching`) |+//! | C | SOLIDWORKS crashes on first spawn and the reporter appears | [`CRASH_RESTART_BUTTON`] is clicked ONCE, ledgered, and never anything else |+//! | D | SOLIDWORKS is up but hung or memory-exhausted | [`host_app_hung`] / [`host_app_exhausted`], with the honest "only the user can end it" |+//!+//! ## The kill allowlist — the only processes this bridge may ever terminate+//!+//! [`TERMINABLE_IMAGES`], and only instances CREATED AFTER our own invoke.+//! Everything else is off limits, permanently:+//!+//!   * **`3DEXPERIENCELauncher*` daemons are NEVER touched.** They are the+//!     Platform's own background services. A successful launch on 2026-09-04+//!     had no Backbone running at all, so they are not even required — killing+//!     them buys nothing and breaks the user's Platform session. A real user+//!     launch rebuilds them; this bridge does not get to decide that.+//!   * **`sldworks.exe` is NEVER killed here.** Ending the user's CAD session is+//!     `swx_kill`'s job, and that verb is gated behind the process-level write+//!     opt-in, a `reason` and a `confirm` for exactly this reason.+//!   * **No image-name kill anywhere.** Every terminate is by pid, re-checked+//!     against the live census. See [`crate::launchos::LaunchOs::terminate`].+//!+//! ## Round 2 (0.4.1) — what the adversary found in the above+//!+//! The first version scoped the kill list BY CLOCK: every terminable image+//! younger than our invoke. Two consequences, both proved by test:+//!+//!   * a chain the USER started while ours was in flight was swept up with ours+//!     (pids 70003/70004) — and twenty seconds of a screen doing nothing is+//!     exactly when somebody reaches for their own Start Menu;+//!   * a one-second "clock slack" was applied to the PROCESS's age rather than+//!     to ours, so a chain created a second BEFORE our invoke was terminable.+//!+//! The kill list is now the chain we RECORDED — pids that appeared after our+//! invoke and were absent from the baseline census taken immediately before it,+//! plus their descendants by parent pid — each re-verified as (pid, image,+//! creation time) on the open handle at the moment of the kill. There is no+//! backward slack anywhere, and `swx-bridge` reads its own clock through the+//! same call the creation times come from.++use crate::launchos::{epoch_secs, LaunchOs, ProcInfo};+use serde_json::{json, Value};+use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};+use std::sync::{Arc, Mutex};+use std::time::Duration;++// ── routes ──────────────────────────────────────────────────────────────────++/// How the shortcut is invoked, in the order this bridge tries them.+///+/// **ATTRIBUTABLE ROUTES FIRST.** The order used to be about which mechanism+/// was most likely to make the launcher work; it is now about which one can+/// tell us WHAT IT STARTED, because a route that cannot is a route whose chain+/// this bridge may never clean up:+///+/// | Route | Attribution | Show state |+/// |---|---|---|+/// | `shellExecute` | `SEE_MASK_NOCLOSEPROCESS` -> `hProcess` -> pid + creation time | explicit `SW_SHOWNORMAL` |+/// | `powershell` | `Start-Process -PassThru` prints the pid; the child is waited on | `Start-Process`'s own normal |+/// | `explorer` | **NONE** — the shell forwards the link and returns nothing | the shell's own |+/// | `cmdStart` | **NONE** — `start` returns as soon as it has handed off | detached, no window |+///+/// `explorer` and `cmdStart` are kept because they may be the routes that+/// actually WORK (that is still unmeasured), but a stall on either is reported+/// as `cleanup:"notAttributable"` and nothing is terminated.+pub const ROUTES: &[&str] = &["shellExecute", "powershell", "explorer", "cmdStart"];++/// Can this route say what it started? Routes that cannot are still tried and+/// still watched — they simply never earn the right to end a process.+pub fn route_is_attributable(route: &str) -> bool {+    matches!(route, "shellExecute" | "powershell")+}++/// A route name we will actually invoke. Anything else is refused rather than+/// passed to a process spawner.+pub fn is_route(name: &str) -> bool {+    ROUTES.contains(&name)+}++/// The plan for one attempt: the remembered route first (if it is still a real+/// route), then every other route in the standard order. No duplicates.+pub fn route_plan(preferred: Option<&str>) -> Vec<String> {+    let mut plan: Vec<String> = Vec::new();+    if let Some(p) = preferred.filter(|p| is_route(p)) {+        plan.push(p.to_string());+    }+    for r in ROUTES {+        if !plan.iter().any(|p| p == r) {+            plan.push((*r).to_string());+        }+    }+    plan+}++// ── the kill allowlist ──────────────────────────────────────────────────────++/// The ONLY images this bridge may ever terminate as part of a launch recovery.+pub const TERMINABLE_IMAGES: &[&str] = &["CATSTART.exe", "SWXDesktopLauncher.exe"];++/// Images that are off limits whatever else is true. `3DEXPERIENCELauncher` is+/// matched as a PREFIX so a renamed or versioned daemon cannot slip through a+/// list of exact names.+pub const NEVER_TERMINATE_PREFIXES: &[&str] = &["3DEXPERIENCELauncher"];+/// In the census as PARENT LINKS, and never as targets. The shells are how a+/// chain root is attributed; terminating one would take the user's desktop+/// (explorer.exe) or this bridge's own tooling with it.+pub const NEVER_TERMINATE: &[&str] = &[+    "SLDWORKS.exe",+    "sldworks.exe",+    "swCefSubProc.exe",+    "explorer.exe",+    "cmd.exe",+    "powershell.exe",+    "pwsh.exe",+    "swx-bridge.exe",+];++/// MAY THIS BRIDGE TERMINATE THIS PROCESS? The whole safety property, as one+/// pure function, so every branch of it is testable and none of it depends on+/// what a caller passed in.+///+/// Four conditions, ALL required:+///   1. the image is on [`TERMINABLE_IMAGES`];+///   2. the image is not on either never-terminate list;+///   3. the creation time is KNOWN — an unreadable creation time is "not ours",+///      never "probably ours";+///   4. it was created **at or after** our own invoke. NO BACKWARD SLACK: the+///      first version subtracted a second here "for clock skew", which made a+///      chain created a second BEFORE our invoke terminable — and a second is+///      exactly how long it takes somebody to click their own Start Menu while+///      an agent is telling them it is starting SOLIDWORKS. Skew is dealt with+///      where it belongs instead: `LaunchOs::now()` reads the SAME clock the+///      creation times come from, through the same conversion.+///+/// **This function is necessary and not sufficient.** It answers "could this+/// class of process ever be ours"; WHICH processes are ours is decided by+/// [`chain_candidates`] from a baseline census, and the kill itself re-verifies+/// identity on the open handle.+pub fn may_terminate(image: &str, created_at: Option<u64>, invoked_at: u64) -> bool {+    if NEVER_TERMINATE.iter().any(|n| n.eq_ignore_ascii_case(image)) {+        return false;+    }+    let lower = image.to_ascii_lowercase();+    if NEVER_TERMINATE_PREFIXES.iter().any(|p| lower.starts_with(&p.to_ascii_lowercase())) {+        return false;+    }+    if !TERMINABLE_IMAGES.iter().any(|t| t.eq_ignore_ascii_case(image)) {+        return false;+    }+    match created_at {+        None => false,+        Some(at) => at >= invoked_at,+    }+}++/// THE ROOT OF OUR CHAIN, as the invoke itself reported it.+///+/// `None` means the route could not say — and that is a first-class answer, not+/// a gap to be filled in by looking around the machine.+#[derive(Clone, Debug, PartialEq)]+pub struct Attribution {+    pub pid: u32,+    pub created_at: Option<u64>,+    /// How we came to believe it: `shellExecuteHandle`, `startProcessPassThru`.+    pub source: String,+}++impl Attribution {+    pub fn to_json(&self) -> Value {+        json!({"pid": self.pid, "createdAt": self.created_at, "source": self.source})+    }+    /// The identity this pins, for `ProcInfo::same_process`.+    pub fn as_proc(&self, image: &str) -> ProcInfo {+        ProcInfo { pid: self.pid, image: image.to_string(), created_at: self.created_at, ppid: None }+    }+}++/// **NO HANDLE, NO KILL.**+///+/// The law this module is built on, stated once. A process may be terminated by+/// this bridge only if its membership of our launcher chain descends, through+/// parent links, from a root the INVOKE ITSELF handed back — a `hProcess` from+/// `ShellExecuteExW`, or a pid printed by `Start-Process -PassThru`. Nothing+/// found by searching the machine afterwards is ever adopted.+///+/// The rule this replaces was "the first CATSTART to appear after our invoke, in+/// census order, is ours". Three things made that a guess and not an inference:+///+///   * census order is roughly pid order and pids do not record who asked;+///   * parentage could not break the tie, because the census contained no+///     shells, so the root's parent link always dangled;+///   * on the `explorer` route our CATSTART and a Start-Menu CATSTART have+///     literally the SAME parent — the user's `explorer.exe`.+///+/// So on a run where our route started nothing at all (which this bridge now+/// detects and names), a launch the user started while waiting was the only+/// candidate — and was adopted, and terminated. That is the finding this rule+/// exists to make structurally impossible.+pub struct AttributionRule;++/// Grow the chain DOWNWARD from pids already proven ours.+///+/// Strictly descendants: a seed pid is never re-adopted as a member by its+/// number. Membership of the seeds themselves is re-confirmed elsewhere with+/// [`ProcInfo::same_process`] against the recorded identities — because CATSTART+/// exits about three seconds into a healthy launch and its number is then free+/// for the rest of a four-minute watch, so anything that takes it and happens to+/// be a launcher image would otherwise be re-adopted by number alone.+///+/// With NO seeds there is nothing to descend from and the answer is EMPTY. That+/// is the whole of the fix: this function can no longer invent a root.+pub fn chain_candidates(+    census: &[ProcInfo],+    baseline_pids: &[u32],+    seed_pids: &[u32],+    invoked_at: u64,+) -> Vec<ProcInfo> {+    // The earliest creation time among the seeds: nothing descending from them+    // can be older than the oldest of them.+    let root_created = census+        .iter()+        .filter(|p| seed_pids.contains(&p.pid))+        .filter_map(|p| p.created_at)+        .min();+    let mut ids: Vec<u32> = seed_pids.to_vec();+    let mut ours: Vec<ProcInfo> = Vec::new();+    let mut changed = true;+    while changed {+        changed = false;+        for p in census {+            if ids.contains(&p.pid) || baseline_pids.contains(&p.pid) {+                continue;+            }+            if !may_terminate(&p.image, p.created_at, invoked_at) {+                continue;+            }+            // DESCENT IS THE ONLY WAY IN. No root rule, no "first one wins".+            // And a child cannot pre-date its parent: a pid whose number+            // happens to point at one of ours, on a process that already+            // existed when ours started, is not our child.+            let after_parent = match (p.created_at, root_created) {+                (Some(child), Some(root)) => child >= root,+                _ => true,+            };+            if after_parent && p.ppid.map(|pp| ids.contains(&pp)).unwrap_or(false) {+                ids.push(p.pid);+                ours.push(p.clone());+                changed = true;+            }+        }+    }+    ours+}++/// The whole chain: the attributed ROOT (re-confirmed as the same process), the+/// members we already confirmed, and everything descending from them.+///+/// Returns `None` when there is no attribution — the caller must then record+/// nothing and, on a stall, report that a chain may remain which it cannot+/// identify.+pub fn attributed_chain(+    census: &[ProcInfo],+    root: Option<&Attribution>,+    recorded: &[ProcInfo],+    baseline_pids: &[u32],+    invoked_at: u64,+) -> Option<Vec<ProcInfo>> {+    let root = root?;+    // A root whose creation time we could not read is not an identity.+    root.created_at?;+    let mut chain: Vec<ProcInfo> = Vec::new();+    // The root is a MEMBER only if the census can see it and it is terminable.+    if let Some(live) = census+        .iter()+        .find(|c| c.pid == root.pid && c.created_at == root.created_at)+    {+        if may_terminate(&live.image, live.created_at, invoked_at) {+            chain.push(live.clone());+        }+    }+    // Members confirmed on an earlier pass, re-confirmed now as the SAME+    // processes — never by number.+    for r in recorded {+        if chain.iter().any(|c| c.pid == r.pid) {+            continue;+        }+        if let Some(live) = census.iter().find(|c| c.same_process(r)) {+            chain.push(live.clone());+        }+    }+    // THE ROOT PID SEEDS THE WALK UNCONDITIONALLY. Being terminable and being+    // proof of lineage are different things, and the first version conflated+    // them: `ShellExecuteExW` hands back whatever process the shell created for+    // the `.lnk`, and if that is anything but the two watched launcher images —+    // a shim, a wrapper, a future Platform build — the root was never seeded,+    // the walk had nothing to descend from, and the real CATSTART it started+    // (whose ppid is right there in the census, pointing at our handle-proven+    // pid) was never attributed. The supervisor then read the empty result as+    // "nothingToClean" and moved on with a chain of ours still running.+    let mut seeds: Vec<u32> = chain.iter().map(|p| p.pid).collect();+    // ...UNLESS THE MACHINE CONTRADICTS IT. A census entry with the root's pid+    // and a DIFFERENT creation time means that number now belongs to something+    // else, so its children are somebody else's children and the lineage is+    // void. A root the census simply cannot SEE (an unwatched image, or one+    // that has already exited) is not contradicted — that is the whole point.+    let contradicted = census+        .iter()+        .any(|c| c.pid == root.pid && c.created_at.is_some() && c.created_at != root.created_at);+    if !contradicted && !seeds.contains(&root.pid) {+        seeds.push(root.pid);+    }+    chain.extend(chain_candidates(census, baseline_pids, &seeds, invoked_at));+    Some(chain)+}++// ── stages ──────────────────────────────────────────────────────────────────++/// How far the launch has got. Reported verbatim to callers as `launch.stage`.+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]+pub enum Stage {+    /// The route was invoked; nothing has been observed yet.+    Invoked,+    /// A NEW `SWXDesktopLauncher` log appeared — the chain is running.+    LauncherStarted,+    /// The launcher's second thread logged `Run Begin`: it is locating and+    /// spawning `sldworks.exe`. This is the transition that never happened.+    RunBegin,+    /// A `SWXDesktopHelper` log appeared: sign-in / licence.+    HelperSignIn,+    /// `sldworks.exe` exists.+    SldworksUp,+    /// `sldworks.exe` exists and we are polling for a COM server.+    Attaching,+    /// COM-attached. Terminal, and the only success.+    Attached,+    /// This route stalled and its chain was cleaned up. Terminal for the route.+    Stalled,+    /// Every route was tried. Terminal for the attempt.+    Exhausted,+}++impl Stage {+    pub fn name(&self) -> &'static str {+        match self {+            Stage::Invoked => "invoked",+            Stage::LauncherStarted => "launcherStarted",+            Stage::RunBegin => "runBegin",+            Stage::HelperSignIn => "helperSignIn",+            Stage::SldworksUp => "sldworksUp",+            Stage::Attaching => "attaching",+            Stage::Attached => "attached",+            Stage::Stalled => "stalled",+            Stage::Exhausted => "exhausted",+        }+    }++    /// What a caller should DO about this stage. Every one of these is written+    /// for an AI reading the response and nothing else.+    pub fn advice(&self) -> &'static str {+        match self {+            Stage::Invoked => "The launcher was invoked moments ago. Poll swx_status.",+            Stage::LauncherStarted =>+                "The launcher chain is running but has not reached 'Run Begin' yet. This is the \+                 stage that stalls; the bridge is watching for it and will clean up and try the \+                 next route on its own. Do NOT invoke the shortcut any other way.",+            Stage::RunBegin =>+                "The launcher is locating and spawning sldworks.exe. SOLIDWORKS appears within a \+                 few seconds; COM attach follows in 1-3 minutes.",+            Stage::HelperSignIn =>+                "SOLIDWORKS is signing in to the 3DEXPERIENCE tenant. This can stop at a sign-in \+                 window only the user can answer — if it sits here, ask them to look at their screen.",+            Stage::SldworksUp | Stage::Attaching =>+                "sldworks.exe is up; the COM server is not answering yet. A Connected cold start \+                 runs 1-3 minutes. Keep polling swx_status; do not launch again.",+            Stage::Attached => "SOLIDWORKS is up and COM-attached. Carry on.",+            Stage::Stalled =>+                "That route stalled and its chain was cleaned up. The bridge is trying the next route.",+            Stage::Exhausted =>+                "Every launch route was tried and none reached a COM-attachable SOLIDWORKS. ASK \+                 THE USER to start SOLIDWORKS from the Start Menu or the 3DEXPERIENCE Platform; \+                 an interactive launch works when this one does not, and once it is up every \+                 other verb in this bridge behaves normally.",+        }+    }+}++/// THE 3DEXPERIENCE ID SIGN-IN WINDOW.+///+/// Live, 2026-09-11: a cold launch stopped at a NATIVE WebView2 window — class+/// `DSYSysLoginPanelWebView2Class`, title "Login | 3DEXPERIENCE ID | Dassault+/// Systemes", owned by `SWXDesktopLauncher.exe` in the bridge's OWN chain, and+/// with no controls visible to UIA at all. Nothing can fill it, including this+/// bridge; only the user can.+///+/// The launch machine did not know that window existed, so its+/// "sldworks.exe within 120s" deadline fired while Drew was reading the sign-in+/// prompt, and the machine KILLED ITS OWN CHAIN — including the window he was+/// about to type into — escalated to the next route, killed that too, and+/// finished `exhausted` with advice to ask the user. SOLIDWORKS then started+/// anyway, from a surviving window, and the bridge recorded the session as not+/// its own.+///+/// A SIGN-IN WAIT IS NOT A STALL. It is the launch working correctly and waiting+/// for a human, and a human is slower than any budget worth setting.+pub const SIGN_IN_CLASSES: &[&str] = &["DSYSysLoginPanelWebView2Class"];++/// Title fragments, as a fallback for a build whose class name differs. Both+/// must match — a window is a sign-in only if its title carries the platform's+/// own name AND says what it is.+pub fn is_sign_in_window(class_name: &str, title: &str) -> bool {+    if SIGN_IN_CLASSES.iter().any(|c| c.eq_ignore_ascii_case(class_name)) {+        return true;+    }+    let t = title.to_ascii_lowercase();+    (t.contains("3dexperience id") || t.contains("dassault"))+        && (t.contains("login") || t.contains("sign in") || t.contains("sign-in"))+}++/// TELL THE USER, once, that the launch is waiting on them.+///+/// A paused deadline is invisible: without this the bridge would sit silently+/// while a window nobody mentioned waited on a desk somebody had walked away+/// from. Through ab, so it is the same native toast every other bridge uses; a+/// failure here never fails the launch (the wait is still correct), it just+/// means nobody was told.+fn announce_sign_in(title: &str) {+    let r = crate::caller::ad_callback(+        "notify_user",+        json!({+            "title": "SOLIDWORKS needs your 3DEXPERIENCE sign-in",+            "message": format!(+                "The launch is waiting at \"{title}\". Type your password in that window — this \+                 bridge cannot (and never stores one). Tick \"Remember me\" so the next launch \+                 does not stop here."+            ),+        }),+        Duration::from_secs(10),+    );+    crate::ledger::record(+        "solidworks_launch_sign_in_notified",+        json!({"delivered": r.get("success").and_then(|v| v.as_bool()), "title": title}),+    );+}++/// Is one of OUR chain's processes showing a sign-in window right now?+///+/// Attribution by OWNER PID, never by class name alone: a sign-in window+/// belonging to somebody else's launch is not ours to wait for. `None` means the+/// window census could not be taken for any of our pids — which is NOT "no+/// sign-in": an unreadable census must not resume a deadline that would kill the+/// very window it could not see.+pub fn sign_in_window(os: &dyn LaunchOs, ours: &[u32]) -> Option<Option<(i64, String)>> {+    let mut any_read = false;+    for pid in ours {+        match os.windows_of_pid(*pid) {+            Ok(ws) => {+                any_read = true;+                if let Some(w) = ws.iter().find(|w| is_sign_in_window(&w.class_name, &w.title)) {+                    return Some(Some((w.hwnd, w.title.clone())));+                }+            }+            Err(_) => {}+        }+    }+    if any_read {+        Some(None)+    } else {+        None+    }+}++// ── tunables (test knobs; the defaults are the measured machine) ────────────++fn secs_env(name: &str, default: u64) -> u64 {+    std::env::var(name).ok().and_then(|v| v.parse().ok()).unwrap_or(default)+}++/// `Run Begin` within this many seconds of the invoke, or the route has stalled.+/// Measured: a healthy launch logs it ~2s after `SecurityContext:`.+pub fn run_begin_budget() -> Duration {+    Duration::from_secs(secs_env("SWX_LAUNCH_RUN_BEGIN_SECS", 20))+}+/// `sldworks.exe` within this long of the invoke. Measured: ~3s after Run Begin.+pub fn sldworks_budget() -> Duration {+    Duration::from_secs(secs_env("SWX_LAUNCH_SLDWORKS_SECS", 120))+}+/// COM attach within this long of the invoke. Measured: 1-3 minutes.+pub fn attach_budget() -> Duration {+    Duration::from_secs(secs_env("SWX_LAUNCH_ATTACH_SECS", 240))+}+/// How long an unfinished attempt keeps refusing to launch again.+pub fn inflight_budget() -> Duration {+    Duration::from_secs(secs_env("SWX_LAUNCH_INFLIGHT_SECS", 240))+}+/// How long after a FAILED attempt before another full one may start.+///+/// A retry that immediately sweeps all four routes again is how four launcher+/// chains ended up on somebody's desktop. After a failure the bridge waits, and+/// then tries ONE route rather than the whole plan.+pub fn backoff_budget() -> Duration {+    Duration::from_secs(secs_env("SWX_LAUNCH_BACKOFF_SECS", 60))+}+fn poll_interval() -> Duration {+    Duration::from_millis(secs_env("SWX_LAUNCH_POLL_MS", 1000).max(50))+}+fn attach_poll_interval() -> Duration {+    Duration::from_millis(secs_env("SWX_LAUNCH_ATTACH_POLL_MS", 3000).max(50))+}++// ── the crash reporter ──────────────────────────────────────────────────────++/// The ONE control this bridge may click during a launch. Identification is by+/// the BUTTON'S ACCESSIBLE NAME, not by a window title.+pub const CRASH_RESTART_BUTTON: &str = "Restart SOLIDWORKS";++/// Crash-reporter recovery is OFF unless this is `on`.+///+/// SHIPPED DISABLED. The click is decided from ab's `desktop_find_control`+/// reply, and **no reply from that verb has ever been seen** — the shape it+/// returns on a real desktop is a guess, and a guess about a reply shape is a+/// guess about whether to click something on somebody's screen. The live gate+/// captures the real reply; until it has, the bridge reports the crash reporter+/// and does nothing about it.+pub const ENV_CRASH_RECOVERY: &str = "SWX_CRASH_RECOVERY";++pub fn crash_recovery_enabled() -> bool {+    std::env::var(ENV_CRASH_RECOVERY).as_deref() == Ok("on")+}++/// Phrases that make a window a crash reporter. A crash reporter SAYS a crash+/// happened; it does not merely mention SOLIDWORKS.+const CRASH_PHRASES: &[&str] =+    &["stopped working", "stopped responding", "not responding", "error report", "crash report",+      "has crashed", "document recovery", "unexpectedly"];++/// ...and phrases that prove it is something else. A browser tab about a crash,+/// a mail thread about one, and the Installation Manager asking for a restart+/// all contain the words a naive matcher looks for. The bridge sends a UIA probe+/// at every candidate, so candidacy is not free.+const NOT_A_CRASH_REPORTER: &[&str] = &[+    "chrome", "firefox", "edge", "opera", "safari", "outlook", "teams", "slack", "gmail",+    "installation manager", "install", "update", "upgrade", "setup", "re:", "fw:", "how to",+    "- word", "- excel", "notepad", "visual studio", "explorer",+];++/// Is this window worth a read-only control probe? Pure, so the rule is visible+/// and testable rather than buried in a callback.+///+/// NOTE the asymmetry: a false NO costs one crash recovery the user can do+/// themselves in two clicks; a false YES sends a UIA probe at an arbitrary+/// window on somebody's desktop and, if the reply is read loosely, clicks it.+pub fn is_crash_reporter_candidate(title: &str) -> bool {+    let t = title.to_lowercase();+    if NOT_A_CRASH_REPORTER.iter().any(|bad| t.contains(bad)) {+        return false;+    }+    if let Ok(exact) = std::env::var("SWX_CRASH_REPORTER_TITLE") {+        if !exact.is_empty() && t.contains(&exact.to_lowercase()) {+            return true;+        }+    }+    t.contains("solidworks") && CRASH_PHRASES.iter().any(|w| t.contains(w))+}++/// Did ab's control lookup actually FIND the button?+///+/// Reads NAMED FIELDS ONLY. The first version stringified the whole reply and+/// searched it for the button name — and the bridge sends that name in the+/// request, so any reply that echoed its query passed the gate with zero+/// controls found. A reply is a find when it says so structurally: an explicit+/// `found:true`, or a control/element entry whose own `name`/`automationId`/+/// `text` names the button. An empty list is a NO, and an unrecognised shape is+/// a NO — the bridge does not click on a reply it does not understand.+pub fn mentions_button(resp: &Value) -> bool {+    if resp.get("success").and_then(|v| v.as_bool()) != Some(true) {+        return false;+    }+    if resp.get("found").and_then(|v| v.as_bool()) == Some(false) {+        return false;+    }+    let names_it = |v: &Value| -> bool {+        ["name", "automationId", "automationID", "text", "label"].iter().any(|k| {+            v.get(*k)+                .and_then(|x| x.as_str())+                .map(|s| s.to_lowercase().contains(&CRASH_RESTART_BUTTON.to_lowercase()))+                .unwrap_or(false)+        })+    };+    // A list of controls: at least one entry must name the button itself.+    for key in ["controls", "elements", "matches", "results", "children"] {+        if let Some(arr) = resp.get(key).and_then(|v| v.as_array()) {+            return arr.iter().any(names_it);+        }+    }+    // A single control object, inline or under `control`.+    if let Some(c) = resp.get("control").filter(|c| c.is_object()) {+        return names_it(c);+    }+    if names_it(resp) {+        // A flat reply naming the control — accepted only alongside a positive+        // `found`/`invokable`, so the query echo (which has neither) cannot.+        return resp.get("found").and_then(|v| v.as_bool()) == Some(true)+            || resp.get("invokable").and_then(|v| v.as_bool()) == Some(true);+    }+    false+}++// ── the persisted attempt ───────────────────────────────────────────────────++/// One route's turn inside an attempt, as it is recorded.+#[derive(Clone, Debug)]+pub struct RouteTry {+    pub route: String,+    pub invoked_at: u64,+    pub stage: Stage,+    pub stalled: bool,+    pub killed: Vec<ProcInfo>,+    /// The cleanup could not be PERFORMED — the census failed, or a terminate+    /// was refused. `killed:[]` alone is indistinguishable from "there was+    /// nothing to kill", which is what a clean recovery looks like.+    pub cleanup_failed: bool,+    pub cleanup_error: Option<String>,+    /// Chain processes known to be still running after the cleanup.+    pub chain_left_running: Vec<ProcInfo>,+    /// Did the INVOKE tell us what it started? Without this, nothing may be+    /// terminated, however obvious the chain on the machine looks.+    pub attributed: bool,+    /// `cleaned` | `notAttributable` | `notConfirmed` | `failed` | `nothingToClean`.+    pub cleanup: &'static str,+    /// A launcher chain from this route may still be running and this bridge+    /// cannot name it. Distinct from `chain_left_running`, which lists+    /// processes it CAN name and could not end.+    pub chain_may_remain: bool,+    // ── THIS ROUTE'S OWN EVIDENCE ────────────────────────────────────────+    // These were read off the ATTEMPT by the gate's per-route table, which+    // printed the same value on every row: the last route's log attributed to+    // all of them. A per-route table whose rows are all the same number is not+    // a measurement.+    pub launcher_log: Option<String>,+    pub run_begin_seen: bool,+    pub unattributed_log: bool,+    pub root_pid: Option<u32>,+    pub root_confirmed: bool,+    pub note: Option<String>,+}++impl RouteTry {+    fn to_json(&self) -> Value {+        json!({+            "route": self.route,+            "invokedAt": self.invoked_at,+            "stage": self.stage.name(),+            "stalled": self.stalled,+            "killed": self.killed.iter().map(|p| p.to_json()).collect::<Vec<_>>(),+            "cleanupFailed": self.cleanup_failed,+            "cleanupError": self.cleanup_error,+            "chainLeftRunning": self.chain_left_running.iter().map(|p| p.to_json()).collect::<Vec<_>>(),+            "attributed": self.attributed,+            "cleanup": self.cleanup,+            "chainMayRemain": self.chain_may_remain,+            "launcherLog": self.launcher_log,+            "runBeginSeen": self.run_begin_seen,+            "unattributedLog": self.unattributed_log,+            "rootPid": self.root_pid,+            "rootConfirmed": self.root_confirmed,+            "note": self.note,+        })+    }+}++/// The launch attempt this process is running (or last ran).+#[derive(Clone, Debug)]+pub struct Attempt {+    pub id: u64,+    pub started_at: u64,+    pub shortcut: String,+    pub reason: String,+    pub caller: String,+    pub plan: Vec<String>,+    pub route: String,+    pub invoked_at: u64,+    pub stage: Stage,+    pub stage_at: u64,+    /// The chain WE started, by identity. The kill path uses this and nothing+    /// else.+    pub chain: Vec<ProcInfo>,+    /// Terminable processes that were ALREADY running when we invoked. Never+    /// ours, whatever their age says later.+    pub baseline_pids: Vec<u32>,+    /// Could the baseline census be taken at all? `false` means this bridge+    /// cannot see the machine it is starting processes on.+    pub baseline_known: bool,+    /// What the INVOKE said it started. The only authority to terminate.+    pub attribution: Option<Attribution>,+    pub launcher_log: Option<String>,+    /// Did `Run Begin` appear in a launcher log we could prove was OURS? The+    /// only evidence that the route did anything — and the only thing that may+    /// make a route "preferred".+    pub run_begin_seen: bool,+    /// Was the user asked to sign in to 3DEXPERIENCE during this attempt? It+    /// changes what every timing in this record MEANS — a launch that took eight+    /// minutes because somebody was typing a password is not a slow launch.+    pub sign_in_seen: bool,+    /// LAUNCHER PROCESSES THAT APPEARED AFTER OUR INVOKE AND CANNOT BE PROVED+    /// EITHER WAY. An unattributable route (`explorer`, `cmdStart`) cannot say+    /// what it started, so a launcher that shows up while one is running is+    /// UNATTRIBUTED — possibly ours, possibly not. It is recorded here so the+    /// record is honest about what was on the machine, and it is excluded from+    /// BOTH the foreign set and the kill path: "possibly ours" is a reason not to+    /// accuse and not to terminate, which happen to be the same answer.+    pub possibly_ours: Vec<u32>,+    /// WHEN EACH CHAIN PROCESS WAS LAST SEEN ALIVE, as `(pid, created_at, epoch+    /// seconds)`.+    ///+    /// A dead parent may be accepted as lineage — the launcher chain always exits+    /// once `sldworks.exe` is up, so requiring it alive would make the walk+    /// useless — but "a pid we once recorded" is not enough on its own: once that+    /// process dies the NUMBER is free, and a user's launcher that reuses it+    /// would have its SOLIDWORKS record our dead pid as its parent, with nothing+    /// alive left to contradict it. So the window in which a child may claim that+    /// parent is bounded by when we last watched the parent run.+    pub chain_last_seen: Vec<(u32, u64, u64)>,+    /// THE SOLIDWORKS THIS ATTEMPT'S ATTRIBUTION IS ABOUT: `(pid, creation+    /// time)`, set when a session is re-claimed after a sign-in. `None` until+    /// then. Read by the verbs that END a session, so that an attribution record+    /// can never authorise acting on a DIFFERENT process than the one it was+    /// made about.+    pub attributed_sldworks: Option<(u32, u64)>,+    /// Did we ever see the attributed root, or anything descending from it?+    /// An attributed route whose chain was NEVER confirmed cannot be cleaned+    /// up, and that is a failure to account for what we started — not a clean+    /// "there was nothing to kill".+    pub root_confirmed: bool,+    /// Which route was in flight when COM attached. An ORDERING HINT ONLY —+    /// `attached` is proof that SOLIDWORKS is up, never proof that this route+    /// put it there. Reported with `"proof": false` and never promoted.+    pub last_route_before_attach: Option<String>,+    /// A launcher chain that is not ours was seen alive during this route's+    /// watch. It is what stops "the only new log must be ours" being true.+    pub foreign_chain_seen: bool,+    /// A NEW launcher log appeared while this route was watched, and it could+    /// not be attributed to us. Evidence that something started; no evidence+    /// whose it is.+    pub unattributed_log: bool,+    pub tries: Vec<RouteTry>,+    pub crash_recovery_clicked: bool,+    /// The bridge process supervising this attempt. A LATER bridge reading this+    /// file needs to tell "somebody is watching this" from "this was left+    /// behind by a process that is gone".+    pub supervisor_pid: Option<u32>,+    pub finished: bool,+    pub outcome: Option<String>,+    pub error: Option<String>,+    pub os_kind: &'static str,+}++impl Attempt {+    pub fn age_secs(&self) -> u64 {+        epoch_secs().saturating_sub(self.started_at)+    }++    /// Any chain process this attempt could not end.+    pub fn left_running(&self) -> Vec<Value> {+        self.tries+            .iter()+            .flat_map(|t| t.chain_left_running.iter())+            .map(|p| p.to_json())+            .collect()+    }++    pub fn cleanup_failed(&self) -> bool {+        self.tries.iter().any(|t| t.cleanup_failed)+    }++    pub fn to_json(&self) -> Value {+        json!({+            "id": self.id,+            "startedAt": self.started_at,+            "ageSeconds": self.age_secs(),+            "shortcut": self.shortcut,+            "reason": self.reason,+            "caller": self.caller,+            "routePlan": self.plan,+            "route": self.route,+            "invokedAt": self.invoked_at,+            "stage": self.stage.name(),+            "stageAgeSeconds": epoch_secs().saturating_sub(self.stage_at),+            "chainPids": self.chain.iter().map(|p| p.to_json()).collect::<Vec<_>>(),+            "baselinePids": self.baseline_pids,+            "baselineKnown": self.baseline_known,+            "attribution": self.attribution.as_ref().map(|a| a.to_json()),+            "attributed": self.attribution.is_some(),+            "launcherLog": self.launcher_log,+            "runBeginSeen": self.run_begin_seen,+            "signInSeen": self.sign_in_seen,+            // Launcher processes that appeared while an UNATTRIBUTABLE route was+            // running: not proved ours, not proved anybody else's, and never+            // terminated on either reading.+            "possiblyOurs": self.possibly_ours,+            "attributedSolidworks": self.attributed_sldworks+                .map(|(p, c)| json!({"pid": p, "createdAt": c})),+            "chainLastSeen": self.chain_last_seen+                .iter()+                .map(|(p, c, t)| json!([p, c, t]))+                .collect::<Vec<_>>(),+            "rootConfirmed": self.root_confirmed,+            "unattributedLog": self.unattributed_log,+            "foreignChainSeen": self.foreign_chain_seen,+            "lastRouteBeforeAttach": self.last_route_before_attach.as_ref().map(|r| json!({+                "route": r,+                "proof": false,+                "note": "the route in flight when COM attached. NOT evidence that it did the \+                         launching — the user may have started SOLIDWORKS themselves — so it is \+                         never remembered as preferredRoute. An ordering hint for a human.",+            })),+            "routesTried": self.tries.iter().map(|t| t.to_json()).collect::<Vec<_>>(),+            "cleanupFailed": self.cleanup_failed(),+            "chainLeftRunning": self.left_running(),+            "crashRecovery": if !crash_recovery_enabled() {+                "off"+            } else if self.crash_recovery_clicked {+                "clicked"+            } else {+                "armed"+            },+            "supervisorPid": self.supervisor_pid,+            "finished": self.finished,+            "outcome": self.outcome,+            "error": self.error,+            "observedBy": self.os_kind,+        })+    }+}++/// Everything the launch machine persists, next to `com-host-created.json` in+/// the bridge's own scratch root.+#[derive(Clone, Debug, Default)]+pub struct LaunchStore {+    pub preferred_route: Option<String>,+    pub attempt: Option<Attempt>,+    pub history: Vec<Value>,+    /// How many attempts in a row have failed. Drives the backoff.+    pub consecutive_failures: u32,+    /// When the last attempt finished without attaching.+    pub last_failure_at: Option<u64>,+}++const HISTORY_MAX: usize = 20;++pub fn state_path() -> std::path::PathBuf {+    crate::scratch::root().join("launch-state.json")+}++fn stage_from_name(s: &str) -> Stage {+    match s {+        "launcherStarted" => Stage::LauncherStarted,+        "runBegin" => Stage::RunBegin,+        "helperSignIn" => Stage::HelperSignIn,+        "sldworksUp" => Stage::SldworksUp,+        "attaching" => Stage::Attaching,+        "attached" => Stage::Attached,+        "stalled" => Stage::Stalled,+        "exhausted" => Stage::Exhausted,+        _ => Stage::Invoked,+    }+}++fn procs_from_json(v: Option<&Value>) -> Vec<ProcInfo> {+    v.and_then(|a| a.as_array())+        .map(|rows| {+            rows.iter()+                .filter_map(|r| {+                    Some(ProcInfo {+                        pid: r.get("pid")?.as_u64()? as u32,+                        image: r.get("image")?.as_str()?.to_string(),+                        created_at: r.get("createdAt").and_then(|c| c.as_u64()),+                        ppid: r.get("ppid").and_then(|c| c.as_u64()).map(|v| v as u32),+                    })+                })+                .collect()+        })+        .unwrap_or_default()+}++/// Read the store from disk. A missing file is an EMPTY store; an UNPARSEABLE+/// one is an empty store AND a loud line, because those are different facts.+pub fn load() -> LaunchStore {+    let path = state_path();+    let text = match std::fs::read_to_string(&path) {+        Ok(t) => t,+        Err(_) => return LaunchStore::default(),+    };+    let v: Value = match serde_json::from_str(&text) {+        Ok(v) => v,+        Err(e) => {+            eprintln!(+                "[swx] launch-state.json could not be parsed ({e}); starting with no launch \+                 history. The file is kept as launch-state.json.bad."+            );+            let _ = std::fs::rename(&path, path.with_extension("json.bad"));+            return LaunchStore::default();+        }+    };+    let attempt = v.get("attempt").filter(|a| a.is_object()).map(|a| Attempt {+        id: a.get("id").and_then(|x| x.as_u64()).unwrap_or(0),+        started_at: a.get("startedAt").and_then(|x| x.as_u64()).unwrap_or(0),+        shortcut: a.get("shortcut").and_then(|x| x.as_str()).unwrap_or("").to_string(),+        reason: a.get("reason").and_then(|x| x.as_str()).unwrap_or("").to_string(),+        caller: a.get("caller").and_then(|x| x.as_str()).unwrap_or("").to_string(),+        plan: a+            .get("routePlan")+            .and_then(|x| x.as_array())+            .map(|r| r.iter().filter_map(|s| s.as_str().map(String::from)).collect())+            .unwrap_or_default(),+        route: a.get("route").and_then(|x| x.as_str()).unwrap_or("").to_string(),+        invoked_at: a.get("invokedAt").and_then(|x| x.as_u64()).unwrap_or(0),+        stage: stage_from_name(a.get("stage").and_then(|x| x.as_str()).unwrap_or("")),+        stage_at: a.get("stageAt").and_then(|x| x.as_u64()).unwrap_or(0),+        chain: procs_from_json(a.get("chainPids")),+        baseline_pids: a+            .get("baselinePids")+            .and_then(|x| x.as_array())+            .map(|r| r.iter().filter_map(|p| p.as_u64().map(|v| v as u32)).collect())+            .unwrap_or_default(),+        baseline_known: a.get("baselineKnown").and_then(|x| x.as_bool()).unwrap_or(false),+        attribution: a.get("attribution").filter(|x| x.is_object()).and_then(|x| {+            Some(Attribution {+                pid: x.get("pid")?.as_u64()? as u32,+                created_at: x.get("createdAt").and_then(|c| c.as_u64()),+                source: x.get("source").and_then(|c| c.as_str()).unwrap_or("restored").to_string(),+            })+        }),+        launcher_log: a.get("launcherLog").and_then(|x| x.as_str()).map(String::from),+        run_begin_seen: a.get("runBeginSeen").and_then(|x| x.as_bool()).unwrap_or(false),+        sign_in_seen: a.get("signInSeen").and_then(|x| x.as_bool()).unwrap_or(false),+        possibly_ours: a+            .get("possiblyOurs")+            .and_then(|x| x.as_array())+            .map(|v| v.iter().filter_map(|p| p.as_u64().map(|n| n as u32)).collect())+            .unwrap_or_default(),+        attributed_sldworks: a.get("attributedSolidworks").and_then(|v| {+            Some((+                v.get("pid")?.as_u64()? as u32,+                v.get("createdAt")?.as_u64()?,+            ))+        }),+        chain_last_seen: a+            .get("chainLastSeen")+            .and_then(|x| x.as_array())+            .map(|v| {+                v.iter()+                    .filter_map(|r| {+                        let a = r.as_array()?;+                        Some((+                            a.first()?.as_u64()? as u32,+                            a.get(1)?.as_u64()?,+                            a.get(2)?.as_u64()?,+                        ))+                    })+                    .collect()+            })+            .unwrap_or_default(),+        root_confirmed: a.get("rootConfirmed").and_then(|x| x.as_bool()).unwrap_or(false),+        unattributed_log: a.get("unattributedLog").and_then(|x| x.as_bool()).unwrap_or(false),+        foreign_chain_seen: a.get("foreignChainSeen").and_then(|x| x.as_bool()).unwrap_or(false),+        last_route_before_attach: a+            .get("lastRouteBeforeAttach")+            .and_then(|x| x.get("route"))+            .and_then(|x| x.as_str())+            .map(String::from),+        tries: Vec::new(),+        crash_recovery_clicked: a+            .get("crashRecoveryClicked")+            .and_then(|x| x.as_bool())+            .unwrap_or(false),+        // ABSENT means "written by a bridge that did not record one", which is+        // treated exactly like a pid that is gone: not us, not alive.+        supervisor_pid: a.get("supervisorPid").and_then(|x| x.as_u64()).map(|v| v as u32),+        finished: a.get("finished").and_then(|x| x.as_bool()).unwrap_or(true),+        outcome: a.get("outcome").and_then(|x| x.as_str()).map(String::from),+        error: a.get("error").and_then(|x| x.as_str()).map(String::from),+        os_kind: "restored",+    });+    LaunchStore {+        preferred_route: v.get("preferredRoute").and_then(|x| x.as_str()).map(String::from),+        attempt,+        history: v.get("history").and_then(|x| x.as_array()).cloned().unwrap_or_default(),+        consecutive_failures: v+            .get("consecutiveFailures")+            .and_then(|x| x.as_u64())+            .unwrap_or(0) as u32,+        last_failure_at: v.get("lastFailureAt").and_then(|x| x.as_u64()),+    }+}++/// Persist the store ATOMICALLY: write a temp file, then rename over the real+/// one. A plain `fs::write` truncates first, so a kill (or a full disk) in the+/// middle of one leaves a half-file — and the launch machine would then read+/// "no attempt in flight" from a bridge that has one.+pub fn save(store: &LaunchStore) {+    let mut history = store.history.clone();+    if history.len() > HISTORY_MAX {+        let drop = history.len() - HISTORY_MAX;+        history.drain(0..drop);+    }+    let mut attempt = store.attempt.as_ref().map(|a| a.to_json());+    if let (Some(obj), Some(a)) = (attempt.as_mut().and_then(|x| x.as_object_mut()), &store.attempt) {+        obj.insert("stageAt".into(), json!(a.stage_at));+        obj.insert("crashRecoveryClicked".into(), json!(a.crash_recovery_clicked));+    }+    let body = json!({+        "preferredRoute": store.preferred_route,+        "attempt": attempt,+        "history": history,+        "consecutiveFailures": store.consecutive_failures,+        "lastFailureAt": store.last_failure_at,+    });+    if let Err(e) = write_atomic(&state_path(), &body.to_string()) {+        // Loud, once per failure. An in-flight guard that silently stopped+        // persisting would let the next swx_start start a second launch.+        eprintln!("[swx] LAUNCH STATE NOT PERSISTED: {e}");+    }+}++/// Temp file + rename, with the previous version kept as `.bak`.+///+/// RETRIES THE RENAME. On Windows an antivirus scanner or the search indexer+/// holds a brief exclusive handle on a file it has just seen created, and the+/// rename fails with ACCESS_DENIED for a few milliseconds — on a file this+/// bridge rewrites hundreds of times during one assembly build. A single+/// attempt therefore drops writes at random, and the one it drops might be the+/// one that recorded a document the bridge owns.+///+/// Returns whether the write landed. A failure is REPORTED (the callers log it)+/// rather than swallowed: "the bridge could not write its own notes" is a fact+/// somebody needs, and it is the beginning of every ownership bug in this file.+pub fn write_atomic(path: &std::path::Path, body: &str) -> Result<(), String> {+    if let Some(parent) = path.parent() {+        let _ = std::fs::create_dir_all(parent);+    }+    // UNIQUE PER WRITE. The temp name used to be the pid alone, which is one+    // name shared by every HTTP worker thread in this process — and the+    // ownership registry is rewritten from several of them. Two concurrent+    // writes then raced on one temp file: both wrote it, one renamed it away,+    // and the other's rename failed with "no such file" (or, worse, renamed a+    // half-written file into place).+    static SEQ: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);+    let tmp = path.with_extension(format!(+        "tmp{}-{}",+        std::process::id(),+        SEQ.fetch_add(1, Ordering::SeqCst)+    ));+    if let Err(e) = std::fs::write(&tmp, body) {+        let _ = std::fs::remove_file(&tmp);+        return Err(format!("could not write {}: {e}", tmp.display()));+    }+    // THE BACKUP IS STAGED TOO. `copy` straight onto `.bak` is not atomic+    // either, so two concurrent writers could leave a torn backup — and the+    // backup is what `owned::restore` falls back to when the live file cannot+    // be parsed. Copy to a unique name, then rename it into place.+    if path.exists() {+        let bak_tmp = path.with_extension(format!("bak.tmp{}", std::process::id()));+        if std::fs::copy(path, &bak_tmp).is_ok() {+            if std::fs::rename(&bak_tmp, path.with_extension("bak")).is_err() {+                let _ = std::fs::remove_file(&bak_tmp);+            }+        } else {+            let _ = std::fs::remove_file(&bak_tmp);+        }+    }+    let mut last = String::new();+    for attempt in 0..3 {+        match std::fs::rename(&tmp, path) {+            Ok(()) => return Ok(()),+            Err(e) => {+                last = e.to_string();+                // ACCESS_DENIED / PermissionDenied is the scanner; anything+                // else will not improve by waiting.+                if e.kind() != std::io::ErrorKind::PermissionDenied {+                    break;+                }+                std::thread::sleep(Duration::from_millis(30 * (attempt + 1)));+            }+        }+    }+    let _ = std::fs::remove_file(&tmp);+    Err(format!("could not replace {} after 3 attempts: {last}", path.display()))+}++// ── process-wide state ──────────────────────────────────────────────────────++static STORE: Mutex<Option<LaunchStore>> = Mutex::new(None);+static SUPERVISOR: AtomicBool = AtomicBool::new(false);+/// The sldworks pid whose crash reporter this bridge has already clicked.+/// Per-PROCESS, not per-attempt: a retry must not re-arm the click.+static CLICKED_FOR: Mutex<Option<u32>> = Mutex::new(None);++/// Read the store WITHOUT writing it back.+///+/// The first version saved on every read, so `swx_status` — the verb ab tells+/// callers to POLL — rewrote `launch-state.json` a few times a second, for no+/// change, on the one file whose integrity the in-flight guard depends on.+fn read_store<T>(f: impl FnOnce(&LaunchStore) -> T) -> T {+    let mut guard = STORE.lock().unwrap_or_else(|e| e.into_inner());+    if guard.is_none() {+        *guard = Some(load());+    }+    f(guard.as_ref().expect("initialised above"))+}++/// Change the store and persist it. The ONLY path that writes.+fn mutate_store<T>(f: impl FnOnce(&mut LaunchStore) -> T) -> T {+    let mut guard = STORE.lock().unwrap_or_else(|e| e.into_inner());+    if guard.is_none() {+        *guard = Some(load());+    }+    let out = f(guard.as_mut().expect("initialised above"));+    save(guard.as_ref().expect("initialised above"));+    out+}++/// The route that last worked on this machine, if any.+pub fn preferred_route() -> Option<String> {+    read_store(|s| s.preferred_route.clone())+}++/// The current attempt, if there is one.+pub fn attempt() -> Option<Attempt> {+    read_store(|s| s.attempt.clone())+}++/// Is a launch genuinely in flight RIGHT NOW?+///+/// Three questions, in order, and the last two are what make this honest rather+/// than a timer:+///+///   1. is THIS PROCESS supervising it? (the common case, and free)+///   2. is the process that recorded it still alive? An attempt whose+///      `supervisorPid` is absent, is not us, and is not running belongs to a+///      bridge that is GONE — it is marked `abandoned` on the spot, so it stops+///      being reported and stops blocking the next launch.+///   3. is OUR OWN CHAIN still alive? Note what is NOT here: "is any+///      sldworks.exe running". The first version accepted that, so a bridge+///      restarted while the user's SOLIDWORKS sat at a sign-in reported a+///      launch in flight forever and told the caller to poll a supervisor that+///      did not exist.+pub fn in_flight(os: &dyn LaunchOs) -> Option<Attempt> {+    let a = attempt()?;+    if a.finished {+        return None;+    }+    if SUPERVISOR.load(Ordering::SeqCst) {+        return Some(a);+    }+    if a.age_secs() > inflight_budget().as_secs() {+        abandon("the attempt outlived its in-flight budget with no supervisor in this process");+        return None;+    }+    let ours = a.supervisor_pid == Some(os.self_pid());+    if !ours {+        let alive = a.supervisor_pid.and_then(|p| os.pid_alive(p));+        if alive != Some(true) {+            abandon(match a.supervisor_pid {+                None => "the attempt records no supervising bridge process, so nothing is watching it",+                Some(_) => "the bridge process that started this launch is gone",+            });+            return None;+        }+    }+    // Another live bridge owns it (or ours restarted the supervisor): believe it+    // only while OUR OWN recorded chain is still running.+    let census = os.processes().ok()?;+    let chain_alive = !a.chain.is_empty()+        && a.chain.iter().any(|c| census.iter().any(|p| p.same_process(c)));+    if chain_alive {+        Some(a)+    } else {+        abandon("no process from this attempt's own launcher chain is still running");+        None+    }+}++/// Mark the current attempt as belonging to nobody.+fn abandon(why: &str) {+    mutate_store(|s| {+        if let Some(a) = s.attempt.as_mut() {+            if !a.finished {+                a.finished = true;+                a.outcome = Some("abandoned".into());+                a.error = Some(why.to_string());+            }+        }+    });+    crate::ledger::record("solidworks_launch_abandoned", json!({"reason": why}));+}++/// May a new attempt start, or is the machine in backoff after a failure?+pub fn backoff_remaining() -> u64 {+    read_store(|s| {+        if s.consecutive_failures == 0 {+            return 0;+        }+        let Some(at) = s.last_failure_at else { return 0 };+        let wait = backoff_budget().as_secs() * (s.consecutive_failures.min(4) as u64);+        wait.saturating_sub(epoch_secs().saturating_sub(at))+    })+}++// ── the supervisor ──────────────────────────────────────────────────────────++/// What the supervisor needs: invoke a route, and probe for a COM server. Both+/// go through the com host — the invoke because a `.lnk` needs the shell (and+/// `ShellExecuteExW` needs the host's STA thread), the probe because the com+/// host is the only thing that speaks COM.+pub struct Channel {+    pub com: Arc<crate::comhost::ComHost>,+}++impl Channel {+    fn invoke(&self, shortcut: &str, route: &str) -> Result<Value, String> {+        self.com+            .call(+                "launch_shortcut",+                json!({"shortcut": shortcut, "route": route}),+                Duration::from_secs(60),+            )+            .map_err(|e| e.message)+    }++    fn attached(&self) -> bool {+        self.com+            .call("start", json!({"visible": true, "launch": false}), Duration::from_secs(15))+            .is_ok()+    }+}++/// Why a launch cannot start right now.+pub enum BeginRefusal {+    /// One is already running; report it, launch nothing.+    InFlight(Attempt),+    /// The machine failed recently; a full re-sweep would start four more+    /// chains. `seconds` until it may try again.+    Backoff { seconds: u64, attempt: Option<Attempt> },+}++/// Begin an attempt and hand it to a background supervisor.+pub fn begin(+    channel: Channel,+    shortcut: &str,+    reason: &str,+    caller: &str,+) -> Result<Attempt, BeginRefusal> {+    let wait = backoff_remaining();+    if wait > 0 {+        return Err(BeginRefusal::Backoff { seconds: wait, attempt: attempt() });+    }+    if SUPERVISOR.compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst).is_err() {+        return Err(BeginRefusal::InFlight(+            attempt().unwrap_or_else(|| unfinished_placeholder(shortcut)),+        ));+    }+    let os = crate::launchos::os();+    // AFTER A FAILURE, TRY ONE ROUTE — not the whole plan again. A caller that+    // retries in a loop would otherwise start four launcher chains per retry,+    // which is the exact failure this release exists to end.+    let (plan, failures) = read_store(|s| {+        let full = route_plan(s.preferred_route.as_deref());+        if s.consecutive_failures == 0 {+            (full, 0)+        } else {+            let idx = (s.consecutive_failures as usize) % full.len();+            (vec![full[idx].clone()], s.consecutive_failures)+        }+    });+    let started = mutate_store(|s| {+        let id = s.attempt.as_ref().map(|a| a.id + 1).unwrap_or(1);+        if let Some(old) = s.attempt.take() {+            s.history.push(old.to_json());+        }+        let a = Attempt {+            id,+            started_at: epoch_secs(),+            shortcut: shortcut.to_string(),+            reason: reason.to_string(),+            caller: caller.to_string(),+            plan: plan.clone(),+            route: plan.first().cloned().unwrap_or_default(),+            invoked_at: 0,+            stage: Stage::Invoked,+            stage_at: epoch_secs(),+            chain: Vec::new(),+            baseline_pids: Vec::new(),+            baseline_known: false,+            attribution: None,+            launcher_log: None,+            run_begin_seen: false,+            sign_in_seen: false,+            possibly_ours: Vec::new(),+            chain_last_seen: Vec::new(),+            attributed_sldworks: None,+            root_confirmed: false,+            unattributed_log: false,+            foreign_chain_seen: false,+            last_route_before_attach: None,+            tries: Vec::new(),+            crash_recovery_clicked: false,+            supervisor_pid: Some(os.self_pid()),+            finished: false,+            outcome: None,+            error: None,+            os_kind: os.kind(),+        };+        s.attempt = Some(a.clone());+        a+    });+    crate::ledger::record(+        "solidworks_launch_started",+        json!({+            "attempt": started.id,+            "launchRoute": "platformShortcut",+            "routePlan": started.plan,+            "afterFailures": failures,+            "shortcut": shortcut,+            "reason": reason,+            "caller": caller,+        }),+    );+    let spawned = std::thread::Builder::new()+        .name("swx-launch-supervisor".into())+        .spawn(move || {+            run_supervisor(channel, os);+            SUPERVISOR.store(false, Ordering::SeqCst);+        });+    if spawned.is_err() {+        SUPERVISOR.store(false, Ordering::SeqCst);+        finish("failed", Some("could not start the launch supervisor thread".into()));+    }+    Ok(started)+}++fn unfinished_placeholder(shortcut: &str) -> Attempt {+    Attempt {+        id: 0,+        started_at: epoch_secs(),+        shortcut: shortcut.to_string(),+        reason: String::new(),+        caller: String::new(),+        plan: Vec::new(),+        route: String::new(),+        invoked_at: 0,+        stage: Stage::Invoked,+        stage_at: epoch_secs(),+        chain: Vec::new(),+        baseline_pids: Vec::new(),+        baseline_known: false,+        attribution: None,+        launcher_log: None,+        run_begin_seen: false,+        sign_in_seen: false,+        possibly_ours: Vec::new(),+        chain_last_seen: Vec::new(),+        attributed_sldworks: None,+        root_confirmed: false,+        unattributed_log: false,+        foreign_chain_seen: false,+        last_route_before_attach: None,+        tries: Vec::new(),+        crash_recovery_clicked: false,+        supervisor_pid: Some(std::process::id()),+        finished: false,+        outcome: None,+        error: None,+        os_kind: "unknown",+    }+}++fn update(f: impl FnOnce(&mut Attempt)) {+    mutate_store(|s| {+        if let Some(a) = s.attempt.as_mut() {+            f(a);+        }+    });+}++fn set_stage(stage: Stage) {+    let mut changed = false;+    update(|a| {+        if a.stage != stage {+            a.stage = stage;+            a.stage_at = epoch_secs();+            changed = true;+        }+    });+    if changed {+        crate::ledger::record("solidworks_launch_stage", json!({"stage": stage.name()}));+    }+}++fn finish(outcome: &str, error: Option<String>) {+    let mut already = false;+    mutate_store(|s| {+        if let Some(a) = s.attempt.as_mut() {+            // IDEMPOTENT. A second call must not re-decide the outcome, and+            // above all must not bump `consecutive_failures` a second time for+            // one attempt — which would double the backoff for free.+            if a.finished {+                already = true;+                return;+            }+            a.finished = true;+            a.outcome = Some(outcome.to_string());+            a.error = error.clone();+            if outcome == "attached" {+                // MEMORISE THE ROUTE ONLY IF IT DID THE WORK. A user who starts+                // SOLIDWORKS from their Start Menu mid-flight makes the attach+                // succeed; recording the route we happened to be trying as+                // "the one that works" would teach the bridge the wrong lesson+                // from somebody else's click. `Run Begin` in OUR OWN launcher+                // log is the evidence that OUR route started the application.+                if a.run_begin_seen {+                    s.preferred_route = Some(a.route.clone());+                }+                s.consecutive_failures = 0;+                s.last_failure_at = None;+            } else {+                s.consecutive_failures = s.consecutive_failures.saturating_add(1);+                s.last_failure_at = Some(epoch_secs());+            }+        }+    });+    if !already {+        crate::ledger::record(+            "solidworks_launch_finished",+            json!({"outcome": outcome, "error": error}),+        );+    }+}++/// Mark the current attempt done because SOLIDWORKS is attached.+pub fn mark_attached() {+    let running = read_store(|s| s.attempt.as_ref().map(|a| !a.finished).unwrap_or(false));+    if running {+        set_stage(Stage::Attached);+        finish("attached", None);+    }+}++/// THE STATE MACHINE. One route at a time; a stall ends the route, never the+/// attempt, and never anything that was running before we started.+fn run_supervisor(channel: Channel, os: Box<dyn LaunchOs>) {+    let plan = attempt().map(|a| a.plan).unwrap_or_default();+    let shortcut = attempt().map(|a| a.shortcut).unwrap_or_default();+    for (index, route) in plan.iter().enumerate() {+        // EVERY PER-ROUTE FACT RESETS. `root_confirmed` and `unattributed_log`+        // did not, with two consequences: `notConfirmed` became unreachable+        // after route 1 (so H2 was restored for routes 2-4), and the log gate's+        // root-confirmed half was pre-satisfied by an EARLIER route's chain.+        update(|a| {+            a.route = route.clone();+            a.chain.clear();+            a.launcher_log = None;+            a.run_begin_seen = false;+            a.root_confirmed = false;+            a.unattributed_log = false;+            a.foreign_chain_seen = false;+        });+        set_stage(Stage::Invoked);++        // THE BASELINE, taken immediately BEFORE the invoke. Everything+        // terminable that is already running is recorded as NOT OURS, whatever+        // its creation time says afterwards.+        let baseline = os.processes();+        let baseline_pids: Vec<u32> = baseline+            .as_ref()+            .map(|c| c.iter().map(|p| p.pid).collect())+            .unwrap_or_default();+        let baseline_known = baseline.is_ok();+        // THE LOG BASELINE, and whether we could take one at all. A FAILED+        // listing is UNKNOWN — `unwrap_or_default()` turned it into "there were+        // no logs", and an absent baseline used to make ANY log ours. Five of+        // the nine logs on the real machine contain `Run Begin`, so that read+        // somebody else's launch from three days ago and jumped the machine+        // straight past stall detection.+        let logs = os.launcher_logs();+        let log_baseline_known = logs.is_ok();+        let (base_stamp, base_created) = newest_log(logs.as_deref().unwrap_or(&[]));+        let invoked_at = os.now();+        update(|a| {+            a.invoked_at = invoked_at;+            a.baseline_pids = baseline_pids.clone();+            a.baseline_known = baseline_known;+            a.attribution = None;+        });++        let invoked = match channel.invoke(&shortcut, route) {+            Err(e) => {+                record_try(+                    route,+                    invoked_at,+                    false,+                    Cleanup { kind: "nothingToClean", ..Default::default() },+                    Some(format!("the invoke itself failed: {e}")),+                );+                crate::ledger::record(+                    "solidworks_launch_route_failed",+                    json!({"route": route, "error": e}),+                );+                continue;+            }+            Ok(r) => {+                if r.get("alreadyRunning").and_then(|v| v.as_bool()).unwrap_or(false)+                    || r.get("attached").and_then(|v| v.as_bool()).unwrap_or(false)+                {+                    set_stage(Stage::Attached);+                    finish("attached", None);+                    return;+                }+                r+            }+        };++        // WHAT DID THE INVOKE SAY IT STARTED? This, and nothing found by+        // searching the machine afterwards, is authority to terminate.+        let attribution = invoked+            .get("rootPid")+            .and_then(|v| v.as_u64())+            .filter(|p| *p > 0)+            .map(|pid| Attribution {+                pid: pid as u32,+                created_at: invoked.get("rootCreatedAt").and_then(|v| v.as_u64()),+                source: invoked+                    .get("attributionSource")+                    .and_then(|v| v.as_str())+                    .unwrap_or("invoke")+                    .to_string(),+            })+            // An attribution with no creation time is not an identity, and this+            // bridge will not terminate a bare number.+            .filter(|a| a.created_at.is_some());+        update(|a| a.attribution = attribution.clone());+        if attribution.is_none() {+            crate::ledger::record(+                "solidworks_launch_not_attributable",+                json!({+                    "route": route,+                    "why": invoked.get("attributionNote").cloned().unwrap_or(Value::Null),+                    "consequence": "no process from this route will be terminated by the bridge",+                }),+            );+        }++        let watched = Watch {+            baseline_pids,+            base_stamp,+            base_created,+            log_baseline_known,+            invoked_at,+            attribution: attribution.clone(),+        };+        match watch_route(&channel, os.as_ref(), route, &watched) {+            RouteOutcome::Attached => {+                // The WINNING route belongs in the per-route table too, or the+                // gate's central measurement is missing its most important row.+                record_try(+                    route,+                    invoked_at,+                    false,+                    Cleanup { attributed: attribution.is_some(), kind: "nothingToClean", ..Default::default() },+                    Some(format!("route '{route}' ended with SOLIDWORKS COM-attached")),+                );+                // AN ORDERING HINT, NOT A PROOF. Which route was in flight when+                // the attach happened is worth recording — but it is not+                // evidence that this route did it (the user may have started+                // SOLIDWORKS themselves), so it never satisfies `run_begin_seen`+                // and is never promoted to `preferredRoute`.+                let last = route.clone();+                mutate_store(|st| {+                    if let Some(a) = st.attempt.as_mut() {+                        a.last_route_before_attach = Some(last.clone());+                    }+                });+                finish("attached", None);+                return;+            }+            RouteOutcome::Stop => {+                // A STOPPED ROUTE BELONGS IN THE TABLE TOO. `Stop` is the+                // `sldworksUpNotAttached` ending — SOLIDWORKS is on the user's+                // screen and COM has not answered, which on this edition usually+                // means a sign-in only they can clear. It recorded NO row at all,+                // so `routesTried` came back empty for a route that had reached+                // Run Begin and started the application; the attempt-level+                // `runBeginSeen:true` sat beside an empty table, and+                // `reattribute_after_attach` — which looks for the route that+                // proved itself — found nothing to point at. The most important+                // outcome for sign-in recovery was the one with no evidence row.+                record_try(+                    route,+                    invoked_at,+                    false,+                    Cleanup {+                        attributed: attribution.is_some(),+                        kind: "nothingToClean",+                        ..Default::default()+                    },+                    Some(format!(+                        "route '{route}' started SOLIDWORKS and stopped: the application is up and \+                         COM has not attached. Nothing was cleaned up — the chain did its job."+                    )),+                );+                return;+            }+            RouteOutcome::Stalled { note, saw_log, unattributed_log } => {+                // THE FOUR WAYS A ROUTE CAN END, and they are not the same.+                //   * attributed AND confirmed: the invoke told us its root and+                //     we saw it, so the chain is ours by proof and we end it;+                //   * attributed but NEVER CONFIRMED: we were told a root and+                //     never once saw it or anything descending from it, so we+                //     cannot say what is running;+                //   * blind: we could not even take a census when we invoked;+                //   * not attributable: the route ran but cannot say what it+                //     started, so nothing may be terminated on its behalf.+                let confirmed = attempt().map(|a| a.root_confirmed).unwrap_or(false);+                let cleanup = match (attribution.as_ref(), baseline_known) {+                    (Some(_), true) | (Some(_), false) if confirmed => {+                        clean_up_chain(os.as_ref(), invoked_at)+                    }+                    (Some(root), _) => Cleanup::not_confirmed(route, root),+                    (None, false) => Cleanup::blind(),+                    (None, true) => Cleanup::not_attributable(route, unattributed_log),+                };+                let note = if saw_log {+                    note+                } else {+                    format!(+                        "route '{route}' produced NO launcher log at all within {}s: nothing got \+                         as far as writing one, because nothing started. The invocation returned \+                         successfully, which for a process spawn only means the EXE ran — it says \+                         nothing about whether the shell resolved the .lnk or the launcher chain \+                         came up.",+                        run_begin_budget().as_secs()+                    )+                };+                let failed = cleanup.failed;+                let kind = cleanup.kind;+                let error = cleanup.error.clone();+                let killed: Vec<Value> = cleanup.killed.iter().map(|p| p.to_json()).collect();+                let left = cleanup.left_running.len();+                record_try(route, invoked_at, true, cleanup, Some(note.clone()));+                set_stage(Stage::Stalled);+                crate::ledger::record(+                    "solidworks_launch_stalled",+                    json!({+                        "route": route,+                        "note": note,+                        "killed": killed,+                        "cleanup": kind,+                        "cleanupFailed": failed,+                        "cleanupError": error,+                        "nextRoute": plan.get(index + 1),+                    }),+                );+                // MAY THE MACHINE GO ON? Only when nothing was left behind+                // that it cannot account for. A route that started NOTHING (no+                // launcher log ever appeared) leaves nothing behind whether or+                // not it was attributable — that is what makes it safe to try+                // the next one. A route that started something it cannot+                // identify is where the machine stops: another route would put+                // a second chain beside one nobody can find.+                let may_continue = match kind {+                    "cleaned" | "nothingToClean" => true,+                    // A route that cannot say what it started may be followed+                    // by another ONLY if nothing appears to have started: no+                    // log of ours (there can be none) and no log we could not+                    // attribute either. A new log is evidence that SOMETHING+                    // ran, and we cannot say whose it is.+                    "notAttributable" => !saw_log && !unattributed_log,+                    _ => false,+                };+                if !may_continue {+                    set_stage(Stage::Exhausted);+                    finish(+                        "exhausted",+                        Some(format!(+                            "stopped after route '{route}' ({kind}): {}. This bridge will not \+                             start another launcher chain while processes it cannot account for \+                             may still be running. {left} launcher process(es) are known to be \+                             still running; ASK THE USER to start SOLIDWORKS from their Start \+                             Menu, which works when these routes do not.",+                            error.unwrap_or_else(|| "reason unknown".into())+                        )),+                    );+                    return;+                }+            }+        }+    }+    set_stage(Stage::Exhausted);+    finish(+        "exhausted",+        Some("every launch route was tried and none produced a COM-attachable SOLIDWORKS".into()),+    );+}++fn record_try(route: &str, invoked_at: u64, stalled: bool, c: Cleanup, note: Option<String>) {+    update(|a| {+        let stage = a.stage;+        // The evidence is COPIED off the attempt HERE, at the end of the route,+        // while it still describes this route and nothing else — every one of+        // these fields is reset when the next route begins.+        let (log, run_begin, unattributed, root_pid, root_confirmed) = (+            a.launcher_log.clone(),+            a.run_begin_seen,+            a.unattributed_log,+            a.attribution.as_ref().map(|r| r.pid),+            a.root_confirmed,+        );+        a.tries.push(RouteTry {+            route: route.to_string(),+            invoked_at,+            stage,+            stalled,+            killed: c.killed,+            cleanup_failed: c.failed,+            cleanup_error: c.error,+            chain_left_running: c.left_running,+            attributed: c.attributed,+            cleanup: c.kind,+            chain_may_remain: c.may_remain,+            launcher_log: log,+            run_begin_seen: run_begin,+            unattributed_log: unattributed,+            root_pid,+            root_confirmed,+            note,+        });+    });+}++/// WHICH OF THESE LOGS IS OURS? Three tests, in order of how much they prove.+///+/// `root.created_at <= written` — round four's rule — is NECESSARY AND NOT+/// SUFFICIENT: it is true of every log written after our chain started,+/// including one written by a launch the user began while ours was stalling.+/// And `launcher_logs()` is newest-first, so a bare `find` preferentially+/// picked THEIRS. Our own route's log stops at `SecurityContext:`; theirs has+/// `Run Begin` in it; the bridge reported that it had seen `Run Begin`.+///+///   1. **AUTHORSHIP.** The launcher stamps the writing thread's id on every+///      line. If that thread belongs to a process in OUR OWN chain, the log is+///      ours — positively, not by elimination. (A miss proves nothing: threads+///      exit, and the writing one usually has.)+///   2. **SOLE CANDIDATE.** Exactly one log post-dates the baseline, our chain+///      has been SEEN and existed before the log was written, and no launcher+///      chain that is not ours was alive in the meantime. Then there is nothing+///      else it could be.+///   3. **Otherwise: none.** Two candidates and no authorship proof is+///      `unattributedLog`. Never "pick the newest".+fn choose_our_log(+    os: &dyn LaunchOs,+    candidates: &[&crate::launchos::LogFile],+    w: &Watch,+    chain_pids: &[u32],+    foreign_chain_seen: bool,+    root_confirmed: bool,+) -> Option<String> {+    let root = w.attribution.as_ref()?;+    // 1. AUTHORSHIP.+    for l in candidates {+        let Ok(text) = os.read_log(&l.path) else { continue };+        let Some(tid) = crate::launchos::writer_thread_of(&text) else { continue };+        let Some(owner) = os.thread_owner(tid) else { continue };+        if owner == root.pid || chain_pids.contains(&owner) {+            return Some(l.path.clone());+        }+    }+    // 2. SOLE CANDIDATE, bounded from both sides — and only once our own chain+    //    has actually been SEEN. A root we were promised and never found is no+    //    evidence that anything of ours ran, so it cannot claim a log either.+    if candidates.len() == 1 && !foreign_chain_seen && root_confirmed {+        let l = candidates[0];+        let born_before = match (root.created_at, l.created_at) {+            (Some(born), Some(written)) => born <= written,+            _ => false,+        };+        if born_before {+            return Some(l.path.clone());+        }+    }+    None+}++/// The pids currently recorded as our chain.+fn chain_pids_now() -> Vec<u32> {+    attempt().map(|a| a.chain.iter().map(|p| p.pid).collect()).unwrap_or_default()+}++/// The newest (stamp, created_at) across a set of logs.+fn newest_log(logs: &[crate::launchos::LogFile]) -> (Option<u64>, Option<u64>) {+    (+        logs.iter().filter_map(|l| l.stamp).max(),+        logs.iter().filter_map(|l| l.created_at).max(),+    )+}++struct Watch {+    baseline_pids: Vec<u32>,+    base_stamp: Option<u64>,+    base_created: Option<u64>,+    /// Could the launcher-log directory be listed before we invoked? When it+    /// could not, NO log is read at all — see `LogFile::is_newer_than`.+    log_baseline_known: bool,+    invoked_at: u64,+    attribution: Option<Attribution>,+}++enum RouteOutcome {+    /// COM attached. The only success.+    Attached,+    /// This route stalled; clean up its chain and try the next one. `saw_log`+    /// records whether a launcher log for THIS invoke was ever found, so the+    /// note can say what actually happened instead of assuming.+    Stalled { note: String, saw_log: bool, unattributed_log: bool },+    /// Terminal for the WHOLE attempt, already finished and recorded.+    Stop,+}++/// Watch ONE route from its invoke to attach, a stall, or its budget.+fn watch_route(channel: &Channel, os: &dyn LaunchOs, route: &str, w: &Watch) -> RouteOutcome {+    let started = std::time::Instant::now();+    let mut last_attach_probe = std::time::Instant::now() - attach_poll_interval();+    let mut seen_run_begin = false;+    let mut seen_sldworks = false;+    let mut saw_log = false;+    let mut unattributed_log = false;+    let mut root_confirmed = attempt().map(|a| a.root_confirmed).unwrap_or(false);+    let mut log_baseline_unknown = false;+    // WAS ANOTHER LAUNCH RUNNING? A terminable-image process that is neither in+    // our chain nor in the baseline is somebody else's launcher chain, and its+    // existence is what makes "the only new log must be ours" stop being true.+    let mut foreign_chain_seen = false;+    let mut sldworks_pid: Option<u32> = None;+    // ── THE SIGN-IN PAUSE. Time spent with a 3DEXPERIENCE ID window on screen+    //    does not count against any launch deadline: the chain is not stalled,+    //    it is waiting for a person. `sign_in_since` is the current wait,+    //    `signed_in_paused` the total of the ones that ended, and+    //    `sign_in_unreadable` records that we could not even ask — which pauses+    //    too, because resuming a deadline on an unreadable census is how the+    //    machine killed the window it could not see.+    let mut sign_in_since: Option<std::time::Instant> = None;+    let mut signed_in_paused = Duration::ZERO;+    let mut sign_in_announced = false;+    let mut sign_in_hwnd: Option<i64> = None;+    loop {+        if last_attach_probe.elapsed() >= attach_poll_interval() {+            last_attach_probe = std::time::Instant::now();+            if channel.attached() {+                set_stage(Stage::Attached);+                return RouteOutcome::Attached;+            }+        }++        // THE LAUNCHER'S OWN LOG. Read only when we had a BASELINE to compare+        // against: without one, "is this log ours?" has no answer, and the old+        // code answered "yes, all of them".+        if !w.log_baseline_known {+            log_baseline_unknown = true;+        } else if let Ok(logs) = os.launcher_logs() {+            // A VERIFIABLY EMPTY directory and a FAILED listing both produce no+            // baseline stamps, and they are opposite facts. `is_newer_than`+            // refuses the second by refusing an absent baseline, so the first is+            // recognised HERE — where we know the listing succeeded.+            let baseline_was_empty = w.base_stamp.is_none() && w.base_created.is_none();+            let candidates: Vec<&crate::launchos::LogFile> = logs+                .iter()+                .filter(|l| baseline_was_empty || l.is_newer_than(w.base_stamp, w.base_created))+                .collect();++            // Once a log is OURS it stays ours: re-selecting on every poll is+            // how a log that appears later (a second launch) displaces the one+            // we were reading.+            let already: Option<String> = attempt().and_then(|a| a.launcher_log);+            let chosen: Option<String> = match &already {+                Some(path) if candidates.iter().any(|l| &l.path == path) => Some(path.clone()),+                _ => choose_our_log(+                    os,+                    &candidates,+                    w,+                    &chain_pids_now(),+                    foreign_chain_seen,+                    root_confirmed,+                ),+            };++            match chosen {+                Some(path) => {+                    saw_log = true;+                    update(|a| a.launcher_log = Some(path.clone()));+                    set_stage_at_least(Stage::LauncherStarted);+                    if let Ok(text) = os.read_log(&path) {+                        if text.contains("Run Begin") {+                            seen_run_begin = true;+                            update(|a| a.run_begin_seen = true);+                            set_stage_at_least(Stage::RunBegin);+                        }+                    }+                }+                None if !candidates.is_empty() && !unattributed_log => {+                    unattributed_log = true;+                    update(|a| a.unattributed_log = true);+                    crate::ledger::record(+                        "solidworks_launch_unattributed_log",+                        json!({+                            "route": route,+                            "candidates": candidates.iter().map(|l| l.path.clone()).collect::<Vec<_>>(),+                            "why": if w.attribution.is_none() {+                                "this route does not report what it started, so no launcher log \+                                 can be attributed to it"+                            } else if candidates.len() > 1 {+                                "more than one launcher log post-dates this invoke and none could \+                                 be tied to a process in our own chain — picking the newest would \+                                 be a guess, and on this machine the newest is as likely to be \+                                 somebody else's launch as ours"+                            } else {+                                "no process from this route's own chain has been confirmed, or \+                                 another launcher chain was running, so nothing proves this log \+                                 is ours"+                            },+                            "consequence": "it is NOT read as this bridge's own evidence; no stage \+                                            transition and no route memory comes from it",+                        }),+                    );+                }+                None => {}+            }+        }++        if seen_run_begin && w.log_baseline_known {+            let baseline_was_empty = w.base_stamp.is_none() && w.base_created.is_none();+            if let Ok(logs) = os.helper_logs() {+                if logs+                    .iter()+                    .any(|l| baseline_was_empty || l.is_newer_than(w.base_stamp, w.base_created))+                {+                    set_stage_at_least(Stage::HelperSignIn);+                }+            }+        }++        // THE PROCESSES. Our chain is recorded BY IDENTITY, grown from the+        // pids we already know are ours — never re-derived from the clock.+        if let Ok(census) = os.processes() {+            // ── RECORD THE CHAIN FIRST, THEN JUDGE WHAT IS FOREIGN. The order+            //    was the other way round, and it made a launch call ITSELF+            //    foreign: on the first census after an invoke the recorded chain+            //    is still EMPTY and only the attribution ROOT (CATSTART) was+            //    excluded by pid — so our own `SWXDesktopLauncher`, the root's+            //    own child, matched "terminable, not ours, not baseline, not the+            //    root" and latched `foreignChainSeen` on every ordinary run.+            //+            //    That is not cosmetic. `reattribute_after_attach` bails on+            //    `foreign_chain_seen` BEFORE it ever reaches the lineage proof,+            //    so sign-in recovery — the whole point of 0.6.0 — was inert. It+            //    is the `foreignChainSeen:true` seen live on 2026-09-11.+            //+            // THE CHAIN, ONLY FROM THE ATTRIBUTED ROOT. `attributed_chain`+            // returns None when the invoke could not say what it started, and+            // None means we record nothing — not "look around and guess".+            let recorded: Vec<ProcInfo> = attempt().map(|a| a.chain).unwrap_or_default();+            if let Some(mine) =+                attributed_chain(&census, w.attribution.as_ref(), &recorded, &w.baseline_pids, w.invoked_at)+            {+                if !mine.is_empty() {+                    // SEEING THE CHAIN AT LEAST ONCE is what makes an attributed+                    // route accountable: it is the difference between "there was+                    // nothing left to kill" and "I never found what I started".+                    root_confirmed = true;+                    // ...and WHEN we saw each of them, which is what bounds the+                    // window a later process may claim one of them as its parent.+                    let now = crate::launchos::epoch_secs();+                    let seen: Vec<(u32, u64, u64)> = mine+                        .iter()+                        .filter_map(|p| p.created_at.map(|c| (p.pid, c, now)))+                        .collect();+                    update(|a| {+                        a.chain = mine;+                        a.root_confirmed = true;+                        for (pid, created, at) in &seen {+                            match a+                                .chain_last_seen+                                .iter_mut()+                                .find(|(p, c, _)| p == pid && c == created)+                            {+                                Some(row) => row.2 = *at,+                                None => a.chain_last_seen.push((*pid, *created, *at)),+                            }+                        }+                    });+                }+            }+            // ...and only now ask what is somebody else's, against the chain as+            // it stands AFTER this census — plus every descendant of our own+            // root, because the launcher IS our chain whether or not the walk has+            // caught up with it yet.+            let ours: Vec<u32> = chain_pids_now();+            let root_pids: Vec<u32> = w.attribution.as_ref().map(|r| vec![r.pid]).unwrap_or_default();+            let descendants: Vec<u32> = if root_pids.is_empty() {+                Vec::new()+            } else {+                chain_candidates(&census, &w.baseline_pids, &root_pids, w.invoked_at)+                    .into_iter()+                    .map(|p| p.pid)+                    .collect()+            };+            // ── FOREIGNNESS NEEDS POSITIVE EVIDENCE, and an UNATTRIBUTABLE route+            //    supplies none either way. `explorer` and `cmdStart` cannot say+            //    what they started, so `root_pids` and `descendants` are both+            //    empty and their own launcher chains matched every clause of this+            //    test — the machine called the processes it had just started+            //    somebody else's, on a machine whose only launcher processes were+            //    the ones it started. Same shape as the 0.6.3 finding, one route+            //    further down the ladder.+            //+            //    A launcher process that appeared AFTER our invoke, is not in the+            //    baseline, and belongs to a route that cannot name its own root is+            //    UNATTRIBUTED — POSSIBLY OURS. It is recorded as such and excluded+            //    from the foreign set, and it never enters the kill path: an+            //    unattributable route still cleans up nothing, which is the whole+            //    point of the attribution law. "Possibly ours" is a reason NOT to+            //    kill and NOT to accuse, which are the same answer here.+            let mut possibly_ours: Vec<u32> = Vec::new();+            let foreign: Vec<&ProcInfo> = census+                .iter()+                .filter(|p| {+                    TERMINABLE_IMAGES.iter().any(|t| t.eq_ignore_ascii_case(&p.image))+                        && !ours.contains(&p.pid)+                        && !w.baseline_pids.contains(&p.pid)+                        && !root_pids.contains(&p.pid)+                        && !descendants.contains(&p.pid)+                })+                .filter(|p| {+                    // POSITIVE EVIDENCE that it is not ours: it predates our+                    // invoke (so no invoke of ours could have started it). A+                    // launcher that appeared after our invoke, while a route of+                    // ours was running that cannot name what it started, is not+                    // evidence of anybody else.+                    let predates = p.created_at.map(|c| c + 1 < w.invoked_at).unwrap_or(false);+                    if !predates {+                        possibly_ours.push(p.pid);+                    }+                    predates+                })+                .collect();+            if !possibly_ours.is_empty() {+                let seen = possibly_ours.clone();+                update(|a| {+                    for pid in &seen {+                        if !a.possibly_ours.contains(pid) {+                            a.possibly_ours.push(*pid);+                        }+                    }+                });+            }+            if !foreign.is_empty() && !foreign_chain_seen {+                let names: Vec<String> =+                    foreign.iter().map(|p| format!("{} (pid {})", p.image, p.pid)).collect();+                foreign_chain_seen = true;+                update(|a| a.foreign_chain_seen = true);+                crate::ledger::record(+                    "solidworks_launch_foreign_chain",+                    json!({+                        "processes": names,+                        "why": "these launcher processes PREDATE this bridge's invoke, so no route \+                                of ours started them — somebody else's launch is running",+                    }),+                );+            }+            if let Some(sw) = census.iter().find(|p| p.is("SLDWORKS.exe")) {+                seen_sldworks = true;+                sldworks_pid = Some(sw.pid);+                set_stage_at_least(Stage::SldworksUp);+                set_stage_at_least(Stage::Attaching);+            }+        }++        if seen_run_begin {+            recover_crash_reporter(sldworks_pid);+        }++        // ── IS THE USER BEING ASKED TO SIGN IN? Asked of OUR chain's pids only,+        //    and only once the chain exists to ask about.+        {+            let ours = chain_pids_now();+            let found = if ours.is_empty() {+                Some(None)+            } else {+                sign_in_window(os, &ours)+            };+            match found {+                // A window is up, or the census could not be read while our chain+                // is alive. Both pause.+                Some(Some((hwnd, title))) => {+                    if sign_in_since.is_none() {+                        sign_in_since = Some(std::time::Instant::now());+                        sign_in_hwnd = Some(hwnd);+                        set_stage_at_least(Stage::HelperSignIn);+                        update(|a| a.sign_in_seen = true);+                        crate::ledger::record(+                            "solidworks_launch_sign_in",+                            json!({+                                "route": route,+                                "hwnd": hwnd,+                                "title": title,+                                "effect": "every launch deadline is PAUSED while this window is on \+                                           screen; nothing in this chain will be killed or \+                                           escalated. Only the user can answer it.",+                            }),+                        );+                        if !sign_in_announced {+                            sign_in_announced = true;+                            announce_sign_in(&title);+                        }+                    }+                }+                None => {+                    // Census unreadable for every pid we hold. Pause rather than+                    // assume the screen is clear.+                    if sign_in_since.is_none() {+                        sign_in_since = Some(std::time::Instant::now());+                    }+                }+                Some(None) => {+                    if let Some(t) = sign_in_since.take() {+                        signed_in_paused += t.elapsed();+                        crate::ledger::record(+                            "solidworks_launch_sign_in_done",+                            json!({+                                "route": route,+                                "hwnd": sign_in_hwnd,+                                "waitedSeconds": t.elapsed().as_secs(),+                                "effect": "the sign-in window is gone; the launch deadlines resume \+                                           from where they were paused",+                            }),+                        );+                    }+                }+            }+        }+        // EVERY DEADLINE BELOW is measured on this clock, which does not run+        // while a human is being asked for a password.+        let elapsed = started+            .elapsed()+            .saturating_sub(signed_in_paused + sign_in_since.map(|t| t.elapsed()).unwrap_or_default());++        if !seen_run_begin && elapsed > run_begin_budget() {+            if log_baseline_unknown {+                // NO EVIDENCE EITHER WAY. The launcher-log directory could not+                // be listed before the invoke, so no log can be attributed to+                // this launch — and a stall is a statement ABOUT a log.+                return RouteOutcome::Stalled {+                    note: format!(+                        "route '{route}' could not be judged: the launcher's log directory could \+                         not be listed before the invoke, so no log can be attributed to this \+                         launch. NOTHING is concluded about whether the chain started, reached \+                         SecurityContext or stalled."+                    ),+                    saw_log: true, // suppress the "nothing started" note: we do not know that+                    unattributed_log,+                };+            }+            return RouteOutcome::Stalled {+                note: format!(+                    "route '{route}' started a launcher chain that reached SecurityContext but \+                     never logged 'Run Begin' within {}s",+                    run_begin_budget().as_secs()+                ),+                saw_log,+                unattributed_log,+            };+        }+        if seen_run_begin && !seen_sldworks && elapsed > sldworks_budget() {+            return RouteOutcome::Stalled {+                note: format!(+                    "route '{route}' logged 'Run Begin' but no sldworks.exe appeared within {}s",+                    sldworks_budget().as_secs()+                ),+                saw_log,+                unattributed_log,+            };+        }+        if elapsed > attach_budget() {+            // SOLIDWORKS IS UP AND NOT ANSWERING COM. Not a stall of the+            // launcher chain, and the chain must NOT be killed for it: the+            // application is on the user's screen, possibly at a sign-in only+            // they can answer. Stop; do not try another route.+            if seen_sldworks {+                set_stage_at_least(Stage::Attaching);+                finish(+                    "sldworksUpNotAttached",+                    Some(format!(+                        "sldworks.exe is running but COM did not attach within {}s — it may be at a \+                         3DEXPERIENCE sign-in only the user can answer",+                        attach_budget().as_secs()+                    )),+                );+                return RouteOutcome::Stop;+            }+            return RouteOutcome::Stalled {+                note: format!(+                    "route '{route}' produced no COM server within {}s",+                    attach_budget().as_secs()+                ),+                saw_log,+                unattributed_log,+            };+        }+        std::thread::sleep(poll_interval());+    }+}++fn set_stage_at_least(stage: Stage) {+    let current = attempt().map(|a| a.stage).unwrap_or(Stage::Invoked);+    if current < stage && current < Stage::Attached {+        set_stage(stage);+    }+}++/// What a cleanup did, and what it could not do.+#[derive(Default)]+struct Cleanup {+    killed: Vec<ProcInfo>,+    left_running: Vec<ProcInfo>,+    failed: bool,+    error: Option<String>,+    attributed: bool,+    kind: &'static str,+    may_remain: bool,+}++impl Cleanup {+    /// The route could not say what it started, so nothing may be terminated.+    /// This is NOT a failure of the cleanup — it is a property of the route,+    /// and the difference matters to whoever reads the report.+    fn not_attributable(route: &str, a_log_appeared: bool) -> Cleanup {+        Cleanup {+            kind: "notAttributable",+            may_remain: a_log_appeared,+            error: Some(format!(+                "route '{route}' does not report what it started (the shell forwards the link and \+                 returns nothing), so this bridge cannot prove which launcher chain is its own \+                 and will not terminate any. {} The user can end any stray chain from Task \+                 Manager, and starting SOLIDWORKS from their Start Menu is unaffected by it.",+                if a_log_appeared {+                    "A launcher log WAS written while this route was watched, so a \+                     CATSTART/SWXDesktopLauncher chain from this attempt MAY still be running."+                } else {+                    "No launcher log appeared at all, so most likely nothing started."+                }+            )),+            ..Default::default()+        }+    }++    /// The invoke DID hand back a root, and across the whole watch neither that+    /// process nor anything descending from it was ever seen. We cannot say+    /// whether the chain we started is still running, which is a failure to+    /// account for it — not a clean "there was nothing to kill".+    fn not_confirmed(route: &str, root: &Attribution) -> Cleanup {+        Cleanup {+            kind: "notConfirmed",+            failed: true,+            attributed: true,+            may_remain: true,+            error: Some(format!(+                "route '{route}' reported starting pid {} ({}), and neither that process nor any \+                 descendant of it was ever seen in the process census. This bridge cannot tell \+                 whether the chain it started is still running, so it stopped rather than \+                 starting another.",+                root.pid, root.source+            )),+            ..Default::default()+        }+    }++    /// The baseline census failed, so this bridge cannot see the machine it is+    /// starting processes on.+    fn blind() -> Cleanup {+        Cleanup {+            kind: "failed",+            failed: true,+            error: Some(+                "the process census could not be taken when this route was invoked, so nothing \+                 could be attributed and nothing could be cleaned up. Any launcher chain this \+                 attempt started is still running and this bridge cannot identify it."+                    .to_string(),+            ),+            ..Default::default()+        }+    }+}++/// End OUR OWN launcher chain — the processes recorded on the attempt, and+/// nothing else.+///+/// The list is NOT re-derived from the census here. It was, and that is how a+/// launch the user started during ours ended up in it: everything terminable+/// younger than our invoke was swept in, whoever started it. Now each recorded+/// process is re-confirmed as the SAME process (pid + image + creation time)+/// and then killed through a handle that verifies the same thing again.+fn clean_up_chain(os: &dyn LaunchOs, invoked_at: u64) -> Cleanup {+    let recorded = attempt().map(|a| a.chain).unwrap_or_default();+    if recorded.is_empty() {+        // Nothing was ever attributed to us. If the census is working, that is+        // a genuine "nothing to clean"; if it is not, we cannot say.+        return match os.processes() {+            Ok(_) => Cleanup { attributed: true, kind: "nothingToClean", ..Default::default() },+            Err(e) => Cleanup {+                failed: true,+                attributed: true,+                kind: "failed",+                error: Some(format!(+                    "the process census failed ({e}), so this bridge cannot tell whether the \+                     launcher chain it started is still running"+                )),+                ..Default::default()+            },+        };+    }+    let census = match os.processes() {+        Ok(c) => c,+        Err(e) => {+            crate::ledger::record(+                "solidworks_launch_cleanup_skipped",+                json!({"reason": format!("the process census failed: {e}")}),+            );+            return Cleanup {+                left_running: recorded,+                failed: true,+                attributed: true,+                kind: "failed",+                error: Some(format!("the process census failed: {e}")),+                ..Default::default()+            };+        }+    };+    let mut killed = Vec::new();+    let mut left = Vec::new();+    let mut errors: Vec<String> = Vec::new();+    for p in recorded {+        // Still the same process? A pid alone is not an identity.+        let Some(live) = census.iter().find(|c| c.same_process(&p)) else {+            continue; // it exited on its own, or the number belongs to somebody else now+        };+        if !may_terminate(&live.image, live.created_at, invoked_at) {+            left.push(live.clone());+            errors.push(format!("pid {} ({}) is not on the kill allowlist", live.pid, live.image));+            continue;+        }+        match os.terminate(live.pid, &live.image, live.created_at) {+            Ok(()) => killed.push(live.clone()),+            Err(e) => {+                left.push(live.clone());+                errors.push(format!("pid {}: {e}", live.pid));+                crate::ledger::record(+                    "solidworks_launch_cleanup_failed",+                    json!({"pid": live.pid, "image": live.image, "error": e}),+                );+            }+        }+    }+    Cleanup {+        failed: !left.is_empty(),+        kind: if left.is_empty() { "cleaned" } else { "failed" },+        attributed: true,+        may_remain: !left.is_empty(),+        error: (!errors.is_empty()).then(|| errors.join("; ")),+        killed,+        left_running: left,+    }+}++// ── crash-reporter recovery ─────────────────────────────────────────────────++/// If the SOLIDWORKS crash reporter is on screen with a "Restart SOLIDWORKS+/// Design" button, click it ONCE and let the state machine carry on.+///+/// OFF BY DEFAULT (`SWX_CRASH_RECOVERY=on`). The decision to click rests+/// entirely on the shape of ab's `desktop_find_control` reply, and that shape+/// has never been observed on a real desktop — see docs/LAUNCH-RESILIENCE.md+/// §9. Shipping it armed would mean guessing about a click on somebody's screen.+///+/// The rules, when it IS armed:+///   * the window must be OWNED BY the SOLIDWORKS process we are watching —+///     a title is not attribution;+///   * ab must report the button STRUCTURALLY (see `mentions_button`);+///   * once per attempt AND once per bridge process per sldworks pid, so a+///     retry cannot re-arm it;+///   * nothing else is ever clicked.+pub fn recover_crash_reporter(sldworks_pid: Option<u32>) -> Option<Value> {+    if !crash_recovery_enabled() {+        return None;+    }+    if attempt().map(|a| a.crash_recovery_clicked).unwrap_or(true) {+        return None;+    }+    let pid = sldworks_pid?;+    {+        // Once per bridge lifetime for a given SOLIDWORKS process. A new pid+        // means a genuinely new session, and re-arms it.+        let clicked = CLICKED_FOR.lock().unwrap_or_else(|e| e.into_inner());+        if *clicked == Some(pid) {+            return None;+        }+    }+    if !crate::caller::ab_available() {+        return None;+    }+    let windows = crate::abwin::list_windows(Duration::from_secs(10)).ok()?;+    for w in &windows {+        let title = w.get("title").and_then(|t| t.as_str()).unwrap_or("");+        let Some(hwnd) = w.get("hwnd").and_then(|h| h.as_i64()) else { continue };+        if !is_crash_reporter_candidate(title) {+            continue;+        }+        // ATTRIBUTION BEFORE ACTION. The crash reporter belongs to the crashed+        // process (or is its child); a window we cannot attribute to the+        // SOLIDWORKS we are launching is not ours to touch.+        if w.get("pid").and_then(|p| p.as_i64()) != Some(pid as i64) {+            continue;+        }+        let found = crate::caller::ad_callback(+            "desktop_find_control",+            json!({"hwnd": hwnd, "contains": CRASH_RESTART_BUTTON, "role": "button"}),+            Duration::from_secs(20),+        );+        if !mentions_button(&found) {+            continue;+        }+        let reason = format!(+            "SOLIDWORKS crashed while the Adom bridge was starting it; clicking the crash \+             reporter's \"{CRASH_RESTART_BUTTON}\" button once to finish the launch"+        );+        let clicked = crate::caller::ad_callback(+            "desktop_ui_click",+            json!({+                "hwnd": hwnd,+                "contains": CRASH_RESTART_BUTTON,+                "role": "button",+                "reason": reason,+                "label": "Restarting SOLIDWORKS after a crash",+            }),+            Duration::from_secs(30),+        );+        update(|a| a.crash_recovery_clicked = true);+        *CLICKED_FOR.lock().unwrap_or_else(|e| e.into_inner()) = Some(pid);+        crate::ledger::record(+            "solidworks_crash_reporter_restarted",+            json!({+                "hwnd": hwnd,+                "windowTitle": title,+                "solidworksPid": pid,+                "button": CRASH_RESTART_BUTTON,+                "reason": reason,+                "ab": clicked.get("success").cloned().unwrap_or(Value::Null),+            }),+        );+        return Some(clicked);+    }+    None+}++// ── hung / exhausted ────────────────────────────────────────────────────────++/// A memory figure worth MENTIONING. Above the highest reading ever measured on+/// a session that had genuinely run out (17.4 GB), so it cannot fire on a+/// working one — and it is ADVISORY, never a verdict.+pub const MEMORY_ADVISORY_MB: u64 = 17_800;++/// How long a busy-vs-dead sample must span before ~0 CPU means anything.+pub const DEAD_SAMPLE_SECS: u64 = 15;++/// BUSY, DEAD, OR UNKNOWN — and the difference is what a caller should tell the+/// user to do.+///+/// LIVE EVIDENCE, 2026-09-08: SOLIDWORKS at 17.9 GB with an unsaved assembly+/// went not-responding with a COM timeout for about five minutes. Windows said+/// "not responding", so `is_hung` said hung and the honest-sounding hint said+/// "only the user can end it". It was burning ~70% of a core, memory was still+/// creeping, there was NO dialog, and it RECOVERED once Drew saved. Telling+/// somebody to end a task that is about to finish is a worse answer than saying+/// "wait".+///+/// So a not-responding window is only DEAD when it has also done essentially no+/// work over a sample long enough to mean it (`DEAD_SAMPLE_SECS`) and has raised+/// no new window. Anything else with CPU moving is BUSY. Without two readings —+/// or with the sample too short — the answer is UNKNOWN, never "dead".+pub fn liveness_verdict(+    responding: Option<bool>,+    cpu_active_seconds: Option<f64>,+    sample_seconds: Option<f64>,+    memory_delta_mb: Option<i64>,+    new_windows: Option<usize>,+) -> &'static str {+    liveness_verdict_for(responding, cpu_active_seconds, sample_seconds, memory_delta_mb, new_windows, None)+}++/// Above this fraction of one core, a not-responding process is doing WORK.+/// 2% of a core over the sample: comfortably below the ~70% measured on the+/// session that recovered, and far above the idle jitter a truly wedged process+/// shows.+pub const BUSY_CPU_FRACTION: f64 = 0.02;+/// Memory moving at least this fast (MB per minute) is work too.+pub const BUSY_MEM_MB_PER_MIN: f64 = 8.0;+/// After this long not responding, "busy" stops being a useful answer even if a+/// trickle of work continues: nobody should be told to keep waiting forever.+pub const BUSY_PATIENCE_SECS: u64 = 15 * 60;++/// The verdict, with the total time spent not-responding taken into account.+///+/// B1: the first version compared ABSOLUTE figures — `cpu > 0.25s` or+/// `|Δmem| >= 8MB` — with no reference to the span they were measured over. A+/// third of a second of CPU across a ten-minute sample is a process doing+/// essentially nothing, and it read as `busy`, which tells the user to wait+/// forever. Work is a RATE.+pub fn liveness_verdict_for(+    responding: Option<bool>,+    cpu_active_seconds: Option<f64>,+    sample_seconds: Option<f64>,+    memory_delta_mb: Option<i64>,+    new_windows: Option<usize>,+    not_responding_for_secs: Option<u64>,+) -> &'static str {+    match responding {+        Some(true) => return "responding",+        // We do not KNOW the window is unresponsive, so we cannot call the+        // process busy or dead on the strength of its CPU alone.+        None => return "unknown",+        Some(false) => {}+    }+    // A RATE, not a total. Without a span there is no rate and no verdict.+    let (Some(cpu), Some(span)) = (cpu_active_seconds, sample_seconds) else {+        return "unknown";+    };+    if span <= 0.0 {+        // Two readings in the same instant measure nothing.+        return "unknown";+    }+    let cpu_fraction = cpu / span;+    let mem_rate = memory_delta_mb.map(|d| (d.abs() as f64) * 60.0 / span).unwrap_or(0.0);+    let working = cpu_fraction > BUSY_CPU_FRACTION || mem_rate >= BUSY_MEM_MB_PER_MIN;+    if working {+        // ...but not forever. A session that has been like this for a very long+        // time is no longer something to keep waiting on, whatever the trickle.+        if not_responding_for_secs.unwrap_or(0) >= BUSY_PATIENCE_SECS {+            return "unknown";+        }+        return "busy";+    }+    // From here we are considering DEAD, which needs a sample worth the name.+    if span < DEAD_SAMPLE_SECS as f64 {+        return "unknown";+    }+    // B2: an UNREADABLE window census cannot support a dead verdict. A new+    // window means something is being ASKED; not knowing whether there is one is+    // not the same as knowing there is none.+    match new_windows {+        None => "unknown",+        Some(n) if n > 0 => "unknown",+        Some(_) => "dead",+    }+}++/// What to TELL the user, per verdict. The busy case must not read as a+/// death sentence and the dead case must not read as "wait a bit".+pub fn verdict_advice(verdict: &str) -> &'static str {+    match verdict {+        "responding" => "SOLIDWORKS is answering; nothing is wrong with the message loop.",+        "busy" => "SOLIDWORKS IS NOT RESPONDING BUT IT IS WORKING — CPU is being burned and/or                    memory is still moving, and no dialog is up. This is a long rebuild, a big                    save, or memory pressure, and it usually finishes: on 2026-09-08 a session in                    exactly this state recovered after about five minutes. TELL THE USER TO WAIT,                    and say what it was doing. Do NOT advise ending the task, and do not retry in a                    loop — every retry adds work to a machine that is already behind.",+        "dead" => "SOLIDWORKS is not responding and is doing NO measurable work (no CPU over the                    sample, memory flat, no dialog). Nothing this bridge can send will get through.                    ONLY THE USER CAN END IT — tell them what it was doing when it stopped and let                    them decide.",+        _ => "UNKNOWN: there were not two readings far enough apart to tell a thrashing session               from a dead one. Poll swx_status again in 15-30 seconds rather than concluding               anything — 'not responding' alone has already been observed on a session that               recovered.",+    }+}++/// Is SOLIDWORKS hung?+///+/// `None` = UNKNOWN, and unknown is the answer far more often than the first+/// version allowed. BOTH signals must be present and both must be knowable:+/// Windows says the window is not answering messages, AND a COM call this+/// bridge made EXCEEDED ITS BUDGET.+///+/// `com_timed_out` is `None` when there was no COM call to judge — in+/// particular when the com host is BUSY WITH OUR OWN LONG VERB. The first+/// version counted busy as a timeout, so a rebuild this bridge started made+/// both "independent" signals fire from one cause and reported the user's+/// working session as hung.+pub fn is_hung(responding: Option<bool>, com_timed_out: Option<bool>) -> Option<bool> {+    match (responding, com_timed_out) {+        (Some(r), Some(t)) => Some(!r && t),+        _ => None,+    }+}++/// Why SOLIDWORKS is out of room, if it PROVABLY is.+///+/// ONE signal is sufficient and it is not a threshold: **SOLIDWORKS accepted a+/// NewDocument against its own stock template and handed back nothing.** That is+/// what exhaustion looks like from the API, and it is what was actually observed.+///+/// Memory and document counts are NOT sufficient, in either direction. The+/// first version raised `host_app_exhausted` above 12 GB / 40 documents, and the+/// same machine the same week ran a healthy session at 13.1 GB with 33+/// documents open — so the verb told a working session to close its documents+/// and restart. Those figures are now advisory only ([`memory_advisory`]).+pub fn exhaustion(_private_mb: Option<u64>, _open_docs: Option<u64>, new_doc_empty: bool) -> Option<String> {+    new_doc_empty.then(|| {+        "SOLIDWORKS returned no document from its own stock template — the signature of a session \+         that has run out of room"+            .to_string()+    })+}++/// The COMPOUND verdict, for a session that is not answering at all: it is+/// wedged AND a COM call timed out AND its memory is still climbing between two+/// reads. Any one of those alone is ordinary.+pub fn exhaustion_confirmed(+    new_doc_empty: bool,+    responding: Option<bool>,+    com_timed_out: Option<bool>,+    memory_rising: bool,+    private_mb: Option<u64>,+) -> Option<String> {+    if let Some(why) = exhaustion(private_mb, None, new_doc_empty) {+        return Some(why);+    }+    if is_hung(responding, com_timed_out) == Some(true) && memory_rising {+        return Some(format!(+            "SOLIDWORKS is not responding, a COM call timed out, and its private memory is still \+             climbing ({} MB)",+            private_mb.map(|m| m.to_string()).unwrap_or_else(|| "unknown".into())+        ));+    }+    None+}++/// A figure worth putting in front of a human — and nothing more.+pub fn memory_advisory(private_mb: Option<u64>, working_set_mb: Option<u64>, open_docs: Option<u64>) -> Option<String> {+    let mb = private_mb?;+    if mb < MEMORY_ADVISORY_MB {+        return None;+    }+    Some(format!(+        "sldworks.exe is holding {mb} MB of private memory ({} MB resident{}). At 17.4 GB on \+         2026-09-03 this session stopped being able to create documents. This is an OBSERVATION, \+         not a verdict — SOLIDWORKS may be working perfectly.",+        working_set_mb.map(|w| w.to_string()).unwrap_or_else(|| "unknown".into()),+        open_docs.map(|d| format!(", {d} documents open")).unwrap_or_default(),+    ))+}++/// The hint that goes with `host_app_exhausted`.+pub const EXHAUSTED_HINT: &str =+    "SOLIDWORKS is still running, but it has no room left: new documents come back empty and \+     further work will fail in ways that look like unrelated bugs. Close the documents this \+     bridge created (swx_reset_workspace) and try again. If that is not enough, ASK THE USER to \+     restart SOLIDWORKS — it is their session and their unsaved work, and this bridge will not \+     end it for them. Do NOT retry the same call in a loop; each attempt costs more memory.";++/// The hint that goes with `host_app_hung`.+pub const HUNG_HINT: &str =+    "Windows reports the SOLIDWORKS window is not responding AND a COM call from this bridge \+     exceeded its budget. Nothing this bridge can send will get through: the message loop is not \+     running. ONLY THE USER CAN END IT — tell them SOLIDWORKS is not responding, say what it was \+     doing when it stopped, and let them decide whether to wait or end the task. This bridge will \+     not kill their CAD session to unblock itself; swx_kill exists but is gated behind their \+     explicit opt-in for exactly this reason.";++// ── the report ──────────────────────────────────────────────────────────────++/// The `launch` block on `swx_status` and `swx_start`.+/// THE SESSION CAME UP AFTER WE GAVE UP — and it was still ours.+///+/// Live, 2026-09-11: the launch machine wrote the attempt off as `exhausted`+/// while the user was at the sign-in window, and SOLIDWORKS then started from a+/// surviving launcher window. `attributed` stayed FALSE on a session this bridge+/// really did launch, and everything that keys on attribution followed it down:+/// the quit gate's bridge-launched proof failed, and `swx_close_all_documents`+/// refused as though the session were the user's own.+///+/// The evidence that it is ours is already recorded and does not expire:+///+///   * some route of THIS attempt had a launcher log we could prove was ours+///     and it logged `Run Begin` — the chain really built something;+///   * the running `sldworks.exe` was created AT OR AFTER our invoke, so it+///     cannot be a session that predates us;+///   * and no other launcher chain was seen (`foreign_chain_seen`), so there is+///     no second candidate for whose launch this was.+///+/// All three, or nothing changes. Re-attribution on two of them would be the+/// "first CATSTART after our invoke" guess this bridge spent four adversarial+/// rounds removing.+/// Walk `sldworks.exe`'s parents. Returns HOW it is ours, or `None`.+///+/// Bounded, because a parent chain read from a live census can contain a cycle if+/// a pid was reused while we walked it.+fn descends_from_our_chain(census: &[ProcInfo], mut pid: u32, a: &Attempt) -> Option<String> {+    let start = pid;+    // ── A PID IS NOT AN IDENTITY, and Windows does not validate a parent id:+    //    `ppid` is recorded at creation and never cleared, so once our launcher+    //    exits (which it always does — the chain exits as soon as sldworks.exe is+    //    up) that NUMBER can belong to something else entirely. A bare+    //    `ours.contains(&parent)` would then accept a process whose parent merely+    //    REUSED the number of a launcher of ours that is long dead. Every other+    //    identity in this crate is (pid, creation time); so is this one.+    let ours: Vec<ProcInfo> = our_identities(a);+    if ours.is_empty() {+        return reattr_refuse("no_identities");+    }+    let mut seen: Vec<u32> = Vec::new();+    for _ in 0..16 {+        if seen.contains(&pid) {+            return reattr_refuse("parent_walk_cycle");+        }+        seen.push(pid);+        let Some(p) = census.iter().find(|p| p.pid == pid) else {+            return reattr_refuse("walk_pid_not_in_census");+        };+        let Some(parent) = p.ppid else { return reattr_refuse("no_parent_recorded") };+        if let Some(mine) = ours.iter().find(|m| m.pid == parent) {+            // THE PARENT IS USUALLY DEAD, and that is normal: the launcher chain+            // exits the moment sldworks.exe is up. So it cannot be required to be+            // alive — but if something IS alive on that pid, it must be the+            // process we recorded, or the number has been reused and this is+            // somebody else's tree.+            if let Some(live) = census.iter().find(|c| c.pid == parent) {+                if !mine.same_process(live) {+                    return reattr_refuse("alive_but_different_process");+                }+            }+            let Some(child) = census.iter().find(|c| c.pid == start) else {+                return reattr_refuse("child_not_in_census");+            };+            let Some(child_created) = child.created_at else {+                return reattr_refuse("child_creation_time_unknown");+            };+            let Some(parent_created) = mine.created_at else {+                return reattr_refuse("parent_creation_time_unknown");+            };+            // ── THE WINDOW. "A pid we once recorded" is not enough once that+            //    process is dead: the NUMBER is free, and a user's launcher that+            //    reuses it would have its SOLIDWORKS record our dead pid as its+            //    parent with nothing alive left to contradict it — and "the child+            //    is younger than the parent" is vacuously true for anything that+            //    started later. So the parent must have been SEEN ALIVE with this+            //    exact (pid, creation time) during the attempt, and the child must+            //    have been created between that creation time and shortly after we+            //    last watched it run. A process that appeared long after we last+            //    saw the parent alive is not its child.+            let Some(last_seen) = a+                .chain_last_seen+                .iter()+                .find(|(p, c, _)| *p == parent && *c == parent_created)+                .map(|(_, _, t)| *t)+            else {+                return reattr_refuse("no_last_seen_record");+            };+            // CREATED WHILE THE PARENT RAN: at or after the parent's own+            // creation, and no later than the last moment we saw the parent+            // alive, plus one census interval for the gap between polls.+            let grace = lineage_grace_secs();+            if child_created < parent_created || child_created > last_seen + grace {+                return reattr_refuse("child_outside_window");+            }+            return Some(format!(+                "sldworks.exe descends from pid {parent} ({}, created {parent_created}), a process \+                 this attempt WATCHED RUN until {last_seen}, and was created at {child_created} — \+                 while that process was running (plus {grace}s for the census interval)",+                mine.image+            ));+        }+        pid = parent;+    }+    reattr_refuse("parent_not_in_ours")+}++/// How long after we last SAW a parent alive a child may still be called its+/// descendant.+///+/// A REAL CHILD IS CREATED WHILE ITS PARENT RUNS. The only reason this is not+/// zero is that our knowledge of "while it ran" is a POLL: the parent can die in+/// the gap between two censuses, and a child created in that gap was still+/// created while it ran — we just did not look at the right moment. So the grace+/// is exactly the census interval, and nothing wider: a flat 30s was three+/// census intervals of slack invented to be safe, and slack in an identity rule+/// is the space a recycled pid lives in.+pub fn lineage_grace_secs() -> u64 {+    poll_interval().as_secs().max(1)+}++/// The processes this attempt can prove it started, as IDENTITIES.+///+/// A recorded chain entry already carries its creation time. An `Attribution`+/// root may not (a `Start-Process -PassThru` pid arrives without one), and one+/// without a creation time cannot be matched by `same_process` — so it is only+/// usable if the census still holds a process of that pid whose creation time we+/// can read, which is exactly the "no handle, no kill" standard applied to a+/// question about lineage rather than about termination.+fn our_identities(a: &Attempt) -> Vec<ProcInfo> {+    let mut out: Vec<ProcInfo> = Vec::new();+    for p in a.chain.iter() {+        if p.created_at.is_some() {+            out.push(p.clone());+        }+    }+    if let Some(r) = a.attribution.as_ref() {+        if let Some(c) = r.created_at {+            out.push(ProcInfo {+                pid: r.pid,+                image: "CATSTART.exe".into(),+                created_at: Some(c),+                ppid: None,+            });+        }+    }+    out+}++// NOTE, 0.6.3: there was a `log_authored_by_our_chain` here, offered as a second+// lineage proof. It is gone, and deliberately not replaced: a launcher log written+// by a thread of our chain proves OUR LAUNCHER RAN, which is a different claim+// from "the SOLIDWORKS now running came from it". A user starting SOLIDWORKS from+// the Start Menu while our chain was also running satisfied it, and the bridge+// would have adopted their session on that evidence. The parent walk is the only+// thing that answers the question actually being asked.++/// WHY RE-ATTRIBUTION DID NOT HAPPEN, recorded every time it does not.+///+/// This exists because the feature was inert for three releases and each time the+/// evidence for WHY was reconstructed by reading code and guessing. A refusal+/// that names its own clause turns that into one line of output. It is written to+/// the launch report (`reattributionRefusedBecause`) and to the ledger.+static REATTR_REASON: Mutex<Option<String>> = Mutex::new(None);++/// The pid of the SOLIDWORKS this bridge is ATTACHED to, as last reported by the+/// com host. 0 means unknown. Set by `swx_status`, which is the only place that+/// asks; read by the lineage walk so the process a caller MEANS is tested first.+static ATTACHED_SW_PID: AtomicU32 = AtomicU32::new(0);++pub fn note_attached_solidworks(pid: Option<u32>) {+    ATTACHED_SW_PID.store(pid.unwrap_or(0), Ordering::SeqCst);+}++fn reattr_refuse(reason: &str) -> Option<String> {+    *REATTR_REASON.lock().unwrap_or_else(|e| e.into_inner()) = Some(reason.to_string());+    None+}++fn reattr_clear() {+    *REATTR_REASON.lock().unwrap_or_else(|e| e.into_inner()) = None;+}++/// THE SOLIDWORKS THIS BRIDGE'S ATTRIBUTION IS ABOUT, if any.+///+/// A verb that ENDS a session asks this before it acts: an attribution record is+/// a claim about ONE process, and it may not authorise acting on another. `None`+/// means no claim has been made, which is not a licence either — it simply means+/// this check has nothing to say.+pub fn attributed_solidworks() -> Option<(u32, u64)> {+    attempt().and_then(|a| a.attributed_sldworks)+}++pub fn reattribution_refused_because() -> Option<String> {+    REATTR_REASON.lock().unwrap_or_else(|e| e.into_inner()).clone()+}++pub fn reattribute_after_attach(os: &dyn LaunchOs, attached: bool) -> Option<String> {+    // COM MUST ACTUALLY BE ATTACHED. The first version of this took "SOLIDWORKS+    // is in the census" as its trigger and relabelled the attempt `attached`+    // — which is a false claim about the only thing this bridge counts as+    // success, and it broke the case the launch machine exists to report+    // honestly: sldworks up, COM not answering, probably a sign-in. Being up is+    // not being usable.+    if !attached {+        return reattr_refuse("not_attached");+    }+    let Some(a) = attempt() else { return reattr_refuse("no_attempt_recorded") };+    if !a.finished || a.outcome.as_deref() == Some("attached") {+        return reattr_refuse("outcome_not_eligible");+    }+    if a.foreign_chain_seen {+        return reattr_refuse("foreign_chain_seen");+    }+    // A route of ours that reached Run Begin, WITH the root the invoke handed+    // back — the same evidence standard as everywhere else in this module.+    // THE ROUTE THAT PROVED ITSELF. Preferably the per-route row; failing that,+    // the attempt's own `run_begin_seen`, which is the same first-hand fact+    // recorded one level up (a route can end without a row — see `Stop`).+    let proven_route: String = match a+        .tries+        .iter()+        .find(|t| t.run_begin_seen && t.root_pid.is_some())+        .or_else(|| a.tries.iter().find(|t| t.run_begin_seen))+    {+        Some(t) => t.route.to_string(),+        None if a.run_begin_seen => a+            .last_route_before_attach+            .clone()+            .or_else(|| a.tries.last().map(|t| t.route.to_string()))+            .unwrap_or_else(|| "unknown".to_string()),+        None => return reattr_refuse("route_unattributable"),+    };+    let Ok(census) = os.processes() else { return reattr_refuse("census_unreadable") };+    // ── EVERY sldworks.exe, NOT "the first one in the census".+    //+    //    `find` took whichever the census listed first, and if that process had no+    //    parent recorded the walk ended there — `no_parent_recorded` — while a+    //    second sldworks.exe sitting further down the list descended from our own+    //    launcher. That is the same defect `host_app_health` was rewritten for in+    //    0.4.x ("EVERY sldworks.exe is reported, not just the first"), reappearing+    //    in the lineage walk.+    //+    //    More than one is ordinary: a zombie from a crashed session, or the user's+    //    own session beside ours. The question is not "what is the SOLIDWORKS" but+    //    "does ANY running SOLIDWORKS descend from the chain we started", and the+    //    one we are ATTACHED to is asked first because it is the one a caller+    //    means.+    let all_sw: Vec<&ProcInfo> = census.iter().filter(|p| p.is("SLDWORKS.exe")).collect();+    if all_sw.is_empty() {+        return reattr_refuse("no_sldworks_in_census");+    }+    // ── THE PROCESS THAT DESCENDS FROM OUR CHAIN MUST BE THE ONE COM IS+    //    ATTACHED TO. 0.6.6 used the attached pid only to ORDER the candidates+    //    and took the first that descended — so with three SOLIDWORKS on the+    //    machine (one COM-attached with no parent, one of ours, one of the+    //    user's) it proved lineage for OUR launcher's child and then labelled the+    //    session `attributed:true` while COM was attached to a different process+    //    entirely. Everything downstream reads that label: the quit gate's+    //    bridge-launched proof, and a quit ladder that builds its Identity from+    //    the COM pid. The bridge would have been willing to END a session nothing+    //    had proved was ours.+    //+    //    Ordering is not a substitute for equality. The claim being made is "the+    //    session this bridge is talking to is the one it launched", and only the+    //    attached process can satisfy it.+    let attached_pid = ATTACHED_SW_PID.load(Ordering::SeqCst);+    let attached_pid = if attached_pid == 0 { None } else { Some(attached_pid) };+    let Some(want) = attached_pid else {+        return reattr_refuse("attached_pid_unknown");+    };+    // EVERY candidate is examined and every verdict recorded, so the ledger says+    // what was considered rather than "the last one stands".+    let mut per_candidate: Vec<Value> = Vec::new();+    let mut proved: Option<(&ProcInfo, String)> = None;+    for cand in &all_sw {+        let why = descends_from_our_chain(&census, cand.pid, &a);+        let clause = match &why {+            Some(_) => "descendsFromOurChain".to_string(),+            None => reattribution_refused_because().unwrap_or_else(|| "unknown".into()),+        };+        per_candidate.push(json!({+            "pid": cand.pid,+            "createdAt": cand.created_at,+            "isAttachedProcess": cand.pid == want,+            "verdict": clause,+        }));+        if why.is_some() && cand.pid == want && proved.is_none() {+            proved = Some((cand, why.unwrap()));+        }+    }+    let descends_but_not_attached: Vec<u32> = per_candidate+        .iter()+        .filter(|c| {+            c.get("verdict").and_then(|v| v.as_str()) == Some("descendsFromOurChain")+                && c.get("isAttachedProcess").and_then(|v| v.as_bool()) == Some(false)+        })+        .filter_map(|c| c.get("pid").and_then(|v| v.as_u64()).map(|p| p as u32))+        .collect();+    let Some((sw, lineage)) = proved else {+        crate::ledger::record(+            "solidworks_launch_reattribution_refused",+            json!({+                "attachedPid": want,+                "candidates": per_candidate,+                "why": if descends_but_not_attached.is_empty() {+                    "no running SOLIDWORKS could be proved to descend from this attempt's chain"+                } else {+                    "a SOLIDWORKS descending from our chain exists, but it is NOT the process COM \+                     is attached to — so nothing proves the ATTACHED session is ours, and it is \+                     the attached session every other verb acts on"+                },+            }),+        );+        return reattr_refuse(if descends_but_not_attached.is_empty() {+            "no_candidate_descends"+        } else {+            "attached_pid_not_ours"+        });+    };+    // The identity must be COMPLETE: a pid without a creation time is not one.+    if sw.created_at.is_none() {+        return reattr_refuse("sldworks_creation_time_unknown");+    }+    let Some(created) = sw.created_at else { return reattr_refuse("sldworks_creation_time_unknown") };+    // ── LINEAGE, not just timing. "No foreign chain was seen" is the ABSENCE of+    //    an observation, and absence is not evidence — a launcher chain that+    //    started and finished between two censuses was never seen at all, and on+    //    that reading its SOLIDWORKS would have been adopted as ours purely for+    //    starting after our invoke. So there must be a POSITIVE link from this+    //    process back to something we know we started: a parent walk that reaches+    //    our own chain, or a launcher log authored by a thread of it.+    //+    //    THE PARENT WALK IS THE ONLY LINEAGE PROOF. 0.6.1 also accepted "a+    //    launcher log written by a thread of our chain", and that was the wrong+    //    proposition: it proves OUR LAUNCHER RAN, which is not the same claim as+    //    "the SOLIDWORKS now running came from it". A user who starts SOLIDWORKS+    //    from the Start Menu while our chain is also running satisfies it, and+    //    the bridge would have adopted their session. Proving the wrong thing+    //    confidently is worse than proving nothing.++    // NO SLACK. The bridge reads its own clock through the same call the+    // creation times come from (GetSystemTimeAsFileTime), so "created at or+    // after our invoke" needs none — see the Cargo.toml note on+    // Win32_System_SystemInformation.+    if created < a.invoked_at {+        // It predates our invoke: somebody else's session, and ours never came.+        return reattr_refuse("sldworks_predates_our_invoke");+    }+    let route = proven_route;+    let (sw_pid, sw_created) = (sw.pid, created);+    let root = a+        .tries+        .iter()+        .find(|t| t.run_begin_seen && t.root_pid.is_some())+        .and_then(|t| t.root_pid)+        .or_else(|| a.attribution.as_ref().map(|r| r.pid));+    mutate_store(|s| {+        if let Some(at) = s.attempt.as_mut() {+            at.outcome = Some("attachedAfterSignIn".into());+            at.stage = Stage::Attached;+            at.run_begin_seen = true;+            // THE EXACT SESSION THIS CLAIM IS ABOUT. Everything downstream that+            // acts on "the bridge launched this" — the quit gate's proof, and the+            // ladder that builds its Identity from the COM pid — can now check+            // that it is talking to the same process the claim was made about.+            at.attributed_sldworks = Some((sw_pid, sw_created));+            at.last_route_before_attach = Some(route.clone());+            if at.attribution.is_none() {+                if let (Some(pid), Some(c)) = (root, Some(created)) {+                    // The ROOT this route reported, with the creation time we+                    // have for it — not the SOLIDWORKS pid, which was never ours+                    // to claim as a launcher root.+                    let _ = c;+                    at.attribution = Some(Attribution {+                        pid,+                        created_at: None,+                        source: "reattributedAfterSignIn".to_string(),+                    });+                }+            }+        }+    });+    reattr_clear();+    crate::ledger::record(+        "solidworks_launch_reattributed",+        json!({+            "route": route,+            "sldworksPid": sw.pid,+            "sldworksCreatedAt": created,+            "attachedPid": want,+            "isAttachedProcess": true,+            "candidates": per_candidate,+            "invokedAt": a.invoked_at,+            "wasOutcome": a.outcome,+            "lineage": lineage,+            "why": "this attempt was written off while the user was at the 3DEXPERIENCE sign-in, \+                    and the session that came up afterwards is the one it started: our own chain \+                    logged Run Begin, sldworks.exe was created at or after our invoke, and no \+                    other launcher chain was seen",+        }),+    );+    Some(format!(+        "{lineage}; and that process (pid {sw_pid}, created {sw_created}) IS the one COM is \+         attached to (pid {want}) — which is what makes this a claim about the session every other \+         verb acts on, rather than about some other SOLIDWORKS that happens to be running"+    ))+}++pub fn report(os: &dyn LaunchOs) -> Value {+    report_with_attach(os, false)+}++/// The same report, told whether COM is attached RIGHT NOW — which is what lets+/// a session that came up after a sign-in be re-claimed (see+/// [`reattribute_after_attach`]). Only `swx_status` knows that fact, so only+/// `swx_status` passes it.+pub fn report_with_attach(os: &dyn LaunchOs, attached: bool) -> Value {+    // THE SESSION MAY HAVE COME UP AFTER WE GAVE UP. Asked here because this is+    // the function every caller reads attribution from — and the live failure was+    // that `attributed:false` outlived the launch that earned it. Cheap: it does+    // nothing at all unless the attempt is finished, un-attached, and SOLIDWORKS+    // is now running.+    let evidence = reattribute_after_attach(os, attached);+    let refused = reattribution_refused_because();+    let store = read_store(|s| s.clone());+    let live = in_flight(os);+    let backoff = backoff_remaining();+    match store.attempt {+        None => json!({+            "inFlight": false,+            "preferredRoute": store.preferred_route,+            "routesAvailable": ROUTES,+            "crashRecovery": if crash_recovery_enabled() { "armed" } else { "off" },+            "_hint": "No launch has been attempted by this bridge. swx_start begins one.",+        }),+        Some(a) => {+            let mut v = a.to_json();+            if let Some(obj) = v.as_object_mut() {+                // WHY THE SESSION WAS OR WAS NOT RE-CLAIMED, every time. This+                // feature was inert for three releases and each diagnosis meant+                // reading code and guessing; a named clause makes it one line of+                // output.+                obj.insert("reattributionEvidence".into(), json!(evidence));+                obj.insert("reattributionRefusedBecause".into(), json!(refused));+                obj.insert("inFlight".into(), json!(live.is_some()));+                obj.insert("preferredRoute".into(), json!(store.preferred_route));+                obj.insert("routesAvailable".into(), json!(ROUTES));+                obj.insert("advice".into(), json!(a.stage.advice()));+                obj.insert("consecutiveFailures".into(), json!(store.consecutive_failures));+                obj.insert("backoffSeconds".into(), json!(backoff));+            }+            v+        }+    }+}++// ── the host-app health block ───────────────────────────────────────────────++/// Remembered private-memory readings, so "still climbing" is a MEASUREMENT+/// rather than a guess: (pid, previous, latest).+#[derive(Clone, Copy)]+struct Sample {+    pid: u32,+    mb: Option<u64>,+    cpu: Option<f64>,+    /// When this reading was taken, at MILLISECOND resolution. Whole seconds made+    /// the sample span collapse to 0 whenever two reads landed inside one second+    /// — and a zero span is "unknown", so a caller who asked twice quickly was+    /// told the instrument had nothing, on a machine that was plainly working.+    at_ms: u128,+    /// When this process was FIRST seen not responding in an unbroken run. A+    /// "busy" answer is only useful while it is still plausible, so the ladder of+    /// advice needs to know how long the user has already been waiting.+    not_responding_since: Option<u64>,+}++static MEM_SAMPLES: Mutex<Option<Sample>> = Mutex::new(None);++/// What the PREVIOUS reading of this process said, and how long ago.+///+/// Two readings are the whole instrument: a single "not responding" has already+/// been observed on a session that recovered, so a verdict from one reading is a+/// guess. Returns (rising, cpu delta, sample span seconds, memory delta MB).+#[allow(clippy::type_complexity)]+fn sample_process(+    pid: u32,+    mb: Option<u64>,+    cpu: Option<f64>,+    responding: Option<bool>,+) -> (bool, Option<f64>, Option<f64>, Option<i64>, Option<u64>) {+    let now = epoch_secs();+    let mut g = MEM_SAMPLES.lock().unwrap_or_else(|e| e.into_inner());+    let prev = match *g {+        Some(p) if p.pid == pid => Some(p),+        _ => None,+    };+    // An unbroken run of not-responding readings; any responding reading resets it.+    let since = match (responding, prev.and_then(|p| p.not_responding_since)) {+        (Some(false), Some(t)) => Some(t),+        (Some(false), None) => Some(now),+        _ => None,+    };+    let now_ms = crate::launchos::epoch_ms();+    *g = Some(Sample { pid, mb, cpu, at_ms: now_ms, not_responding_since: since });+    let not_responding_for = since.map(|t| now.saturating_sub(t));+    let Some(p) = prev else { return (false, None, None, None, not_responding_for) };+    let span = Some(now_ms.saturating_sub(p.at_ms) as f64 / 1000.0);+    let cpu_delta = match (cpu, p.cpu) {+        (Some(a), Some(b)) => Some((a - b).max(0.0)),+        _ => None,+    };+    let mem_delta = match (mb, p.mb) {+        (Some(a), Some(b)) => Some(a as i64 - b as i64),+        _ => None,+    };+    let rising = mem_delta.map(|d| d > 0).unwrap_or(false);+    (rising, cpu_delta, span, mem_delta, not_responding_for)+}++/// What SOLIDWORKS is doing, read WITHOUT COM — the three questions COM cannot+/// answer when the answer is "it is wedged".+///+/// EVERY sldworks.exe is reported, not just the first. The first version took+/// whichever the census listed first, so a zombie left by a crashed session+/// supplied the memory, the handles and the `hung` verdict for a caller asking+/// about the session the user is working in.+pub fn host_app_health(+    os: &dyn LaunchOs,+    open_docs: Option<u64>,+    com_timed_out: Option<bool>,+    com_pid: Option<u32>,+) -> Value {+    let census = os.processes();+    let all: Vec<ProcInfo> = census+        .as_ref()+        .ok()+        .map(|c| c.iter().filter(|p| p.is("SLDWORKS.exe")).cloned().collect())+        .unwrap_or_default();+    if all.is_empty() {+        return json!({+            "processId": Value::Null,+            "running": match census { Ok(_) => json!(false), Err(_) => Value::Null },+            "responding": Value::Null,+            "hung": Value::Null,+            "processes": [],+            "processCount": match census { Ok(_) => json!(0), Err(_) => Value::Null },+            "censusError": census.err(),+        });+    }+    // WHICH ONE are the numbers about? The process COM is attached to, when COM+    // can say; otherwise the newest, which is the one a user just started — and+    // the answer says which rule was used.+    let (chosen, basis) = match com_pid.and_then(|p| all.iter().find(|x| x.pid == p)) {+        Some(p) => (p.clone(), "the process COM is attached to"),+        None => {+            let newest = all+                .iter()+                .max_by_key(|p| p.created_at.unwrap_or(0))+                .cloned()+                .expect("non-empty");+            (newest, "the newest sldworks.exe (COM could not say which it is attached to)")+        }+    };+    let hwnd = os.main_window_of_pid(chosen.pid);+    let responding = hwnd.and_then(|h| os.window_responding(h));+    let metrics = os.process_metrics(chosen.pid);+    let (rising, cpu_delta, sample_span, mem_delta, not_responding_for) =+        sample_process(chosen.pid, metrics.private_mb, metrics.cpu_seconds, responding);+    // `None` when the census could not be read — which must NOT support a dead+    // verdict (B2).+    let new_windows = os.windows_of_pid(chosen.pid).ok().map(|w| {+        w.iter().filter(|x| x.is_dialog() && x.visible).count()+    });+    let verdict = liveness_verdict_for(+        responding,+        cpu_delta,+        sample_span,+        mem_delta,+        new_windows,+        not_responding_for,+    );+    let hung = is_hung(responding, com_timed_out);+    let confirmed = exhaustion_confirmed(false, responding, com_timed_out, rising, metrics.private_mb);+    json!({+        "processId": chosen.pid,+        "running": true,+        "startedAt": chosen.created_at,+        "mainHwnd": hwnd,+        "responding": responding,+        "privateMemoryMB": metrics.private_mb,+        "workingSetMB": metrics.working_set_mb,+        "memoryRising": rising,+        "handles": metrics.handles,+        "openDocs": open_docs,+        "hung": hung,+        // BUSY vs DEAD. `hung` answers "is the message loop running"; this+        // answers "is anything actually happening", which is the question a+        // caller needs to decide between "wait" and "only the user can end it".+        "verdict": verdict,+        "verdictAdvice": verdict_advice(verdict),+        "cpuActiveSeconds": cpu_delta,+        "cpuSampleSeconds": sample_span,+        // The RATE the verdict was decided on, and how long the user has been+        // waiting — so "busy" can be reported as "like this for N minutes".+        "cpuFractionOfCore": match (cpu_delta, sample_span) {+            (Some(c), Some(s)) if s > 0.0 => json!((c / s * 1000.0).round() / 1000.0),+            _ => Value::Null,+        },+        "notRespondingForSeconds": not_responding_for,+        "memoryDeltaMB": mem_delta,+        "visibleDialogs": new_windows,+        "hungNote": if hung.is_none() {+            json!("UNKNOWN: 'hung' needs BOTH a not-responding window AND a COM call that \+                   exceeded its budget. One of those could not be read — in particular, a com \+                   host busy with this bridge's own long verb is not evidence of anything.")+        } else { Value::Null },+        "exhausted": confirmed,+        "memoryAdvisory": memory_advisory(metrics.private_mb, metrics.working_set_mb, open_docs),+        "processCount": all.len(),+        "processes": all.iter().map(|p| p.to_json()).collect::<Vec<_>>(),+        "reportedProcessBasis": basis,+    })+}++/// Is SOLIDWORKS running at all, as far as the OS layer can tell?+/// `None` means the census failed — never read that as "no".+pub fn sldworks_running(os: &dyn LaunchOs) -> Option<bool> {+    os.processes().ok().map(|c| c.iter().any(|p| p.is("SLDWORKS.exe")))+}++#[cfg(test)]+mod tests {+    use super::*;++    fn p(pid: u32, image: &str, created: Option<u64>, ppid: Option<u32>) -> ProcInfo {+        ProcInfo { pid, image: image.to_string(), created_at: created, ppid }+    }++    /// An attempt that watched one launcher run, for the lineage tests.+    fn watched(launcher_pid: u32, created: u64, last_seen: u64) -> Attempt {+        let mut a = unfinished_placeholder("test.lnk");+        a.chain = vec![p(launcher_pid, "SWXDesktopLauncher.exe", Some(created), None)];+        a.chain_last_seen = vec![(launcher_pid, created, last_seen)];+        a+    }++    /// PID REUSE, which is the whole reason lineage is not "the pid matches".+    ///+    /// Our launcher dies. The user's launcher is issued the SAME NUMBER. Their+    /// SOLIDWORKS records that number as its parent, and every cheap test passes:+    /// the pid matches one we recorded, the child is younger than our dead+    /// parent, and nothing is alive to contradict it. Only "created while the+    /// parent we WATCHED was still running" refuses it.+    #[test]+    fn a_child_created_after_we_last_saw_the_parent_alive_is_not_its_descendant() {+        let created = 1_000_000u64;+        let last_seen = 1_000_010u64;+        let a = watched(4242, created, last_seen);+        let grace = lineage_grace_secs();++        // WHILE WE WATCHED IT RUN: this is a child.+        let ok = vec![+            p(9001, "SLDWORKS.exe", Some(last_seen), Some(4242)),+            p(4242, "SWXDesktopLauncher.exe", Some(created), None),+        ];+        assert!(descends_from_our_chain(&ok, 9001, &a).is_some(), "created while the parent ran");++        // The parent is DEAD and the child appeared inside the census gap: still+        // a child, because our knowledge of "while it ran" is a poll.+        let gap = vec![p(9001, "SLDWORKS.exe", Some(last_seen + grace), Some(4242))];+        assert!(+            descends_from_our_chain(&gap, 9001, &a).is_some(),+            "one census interval after we last looked is still inside its lifetime as far as we know"+        );++        // LONG AFTER: the number was recycled, and this is somebody else's.+        let reused = vec![p(9001, "SLDWORKS.exe", Some(last_seen + grace + 60), Some(4242))];+        assert!(+            descends_from_our_chain(&reused, 9001, &a).is_none(),+            "a process created long after we last saw that pid alive is not its child — the NUMBER \+             was reused, and nothing alive is left to say so"+        );++        // OLDER THAN THE PARENT: impossible either way.+        let older = vec![p(9001, "SLDWORKS.exe", Some(created - 1), Some(4242))];+        assert!(descends_from_our_chain(&older, 9001, &a).is_none(), "a child cannot predate its parent");++        // ALIVE ON THAT PID, but a DIFFERENT process: the number is in use by+        // someone else right now, so the walk refuses even inside the window.+        let alive_other = vec![+            p(9001, "SLDWORKS.exe", Some(last_seen), Some(4242)),+            p(4242, "SWXDesktopLauncher.exe", Some(created + 5), None),+        ];+        assert!(+            descends_from_our_chain(&alive_other, 9001, &a).is_none(),+            "something else holds that pid now: not our process, not our child"+        );++        // NEVER SEEN ALIVE: a pid in `chain` with no `chain_last_seen` row is a+        // pid we recorded and never watched, which cannot bound anything.+        let mut unseen = watched(4242, created, last_seen);+        unseen.chain_last_seen.clear();+        assert!(+            descends_from_our_chain(&ok, 9001, &unseen).is_none(),+            "a parent we never watched run cannot date its children"+        );+    }++    /// RE-ATTRIBUTION IS ONLY POSSIBLE FOR AN ATTRIBUTED ROUTE — a RULE, not an+    /// accident of how `our_identities` happens to be built.+    ///+    /// `explorer` and `cmdStart` cannot say what they started, so nothing of+    /// theirs is ever recorded as our chain and there is no identity to walk a+    /// parent back to. A session that came up after one of them may well BE ours,+    /// and this bridge still will not claim it, because it cannot prove it.+    #[test]+    fn an_unattributable_route_has_no_identities_to_walk_back_to() {+        let mut a = unfinished_placeholder("test.lnk");+        // An unattributable route: no attribution root, and nothing recorded as+        // our chain because `attributed_chain` returns None without one.+        a.attribution = None;+        a.chain = Vec::new();+        assert!(+            our_identities(&a).is_empty(),+            "with no attributed root there is no identity to prove lineage against"+        );+        let census = vec![p(9001, "SLDWORKS.exe", Some(2_000_000), Some(4242))];+        assert!(+            descends_from_our_chain(&census, 9001, &a).is_none(),+            "so no session can descend from it, however plausible the timing"+        );+        // ...and a root WITHOUT a creation time is equally unusable: a pid that+        // arrived without one cannot be matched by `same_process`.+        a.attribution = Some(Attribution { pid: 4242, created_at: None, source: "test".into() });+        assert!(+            our_identities(&a).is_empty(),+            "a root with no creation time is not an identity — same rule as 'no handle, no kill'"+        );+    }++    #[test]+    fn the_allowlist_never_reaches_a_daemon_or_anything_older_than_our_invoke() {+        let invoked = 1_000_000;+        assert!(may_terminate("CATSTART.exe", Some(invoked), invoked), "created AT our invoke");+        assert!(may_terminate("catstart.exe", Some(invoked + 1), invoked), "image match is case-insensitive");+        // NO BACKWARD SLACK. One second is exactly how long it takes to click a+        // Start Menu, and the 0.4.0 version adopted anything within it.+        assert!(!may_terminate("CATSTART.exe", Some(invoked - 1), invoked), "one second older is THEIRS");+        assert!(!may_terminate("CATSTART.exe", None, invoked), "unknown age is never ours");+        for daemon in [+            "3DEXPERIENCELauncher.exe",+            "3DEXPERIENCELauncherSysTray.exe",+            "3DEXPERIENCELauncherService.exe",+            "3DEXPERIENCELauncherAnythingElse.exe",+        ] {+            assert!(!may_terminate(daemon, Some(invoked + 1), invoked), "{daemon} is never terminable");+        }+        for never in ["SLDWORKS.exe", "sldworks.exe", "explorer.exe", "swx-bridge.exe", "notepad.exe"] {+            assert!(!may_terminate(never, Some(invoked + 1), invoked), "{never} is never terminable");+        }+    }++    #[test]+    fn nothing_is_adopted_without_a_root_the_invoke_handed_back() {+        let invoked = 1_000_000;+        // Two indistinguishable chains, both younger than our invoke, neither+        // in the baseline. Same parent — which is what route `explorer`+        // produces for OUR launch too, so parentage cannot break the tie.+        let census = vec![+            p(90010, "CATSTART.exe", Some(invoked + 1), Some(4444)),+            p(90011, "SWXDesktopLauncher.exe", Some(invoked + 2), Some(90010)),+            p(70003, "CATSTART.exe", Some(invoked + 2), Some(4444)),+            p(70004, "SWXDesktopLauncher.exe", Some(invoked + 3), Some(70003)),+            p(40, "SLDWORKS.exe", Some(invoked + 5), Some(90011)),+        ];+        // NO ROOT: nothing is ours, however obvious it looks.+        assert!(+            attributed_chain(&census, None, &[], &[], invoked).is_none(),+            "without an attribution the answer is 'I cannot tell', not a guess"+        );+        assert!(+            chain_candidates(&census, &[], &[], invoked).is_empty(),+            "the descendant walk cannot invent a root"+        );++        // WITH the root the invoke handed back, the chain is exact.+        let root = Attribution {+            pid: 90010,+            created_at: Some(invoked + 1),+            source: "shellExecuteHandle".into(),+        };+        let mine = attributed_chain(&census, Some(&root), &[], &[], invoked).unwrap();+        let pids: Vec<u32> = mine.iter().map(|x| x.pid).collect();+        assert_eq!(pids, vec![90010, 90011], "the root and its descendants only: {mine:?}");+        assert!(!pids.contains(&40), "sldworks.exe descends from our chain and is still never terminable");+        assert!(!pids.contains(&70003) && !pids.contains(&70004), "the user's chain is untouched");++        // A root whose creation time we could not read is not an identity at+        // all — the answer is "no attribution", not "an empty chain".+        let bare = Attribution { pid: 90010, created_at: None, source: "x".into() };+        assert!(+            attributed_chain(&census, Some(&bare), &[], &[], invoked).is_none(),+            "this bridge does not terminate a bare number"+        );+        // A root whose number the MACHINE says now belongs to something else:+        // the lineage is void, so its apparent children are not adopted either.+        let stale = Attribution { pid: 90010, created_at: Some(invoked - 500), source: "x".into() };+        assert!(+            attributed_chain(&census, Some(&stale), &[], &[], invoked).unwrap().is_empty(),+            "a contradicted root seeds nothing"+        );++        // ...but a root the census CANNOT SEE is not contradicted, and still+        // carries its children. `ShellExecuteExW` hands back whatever the shell+        // created, which may not be one of the two terminable launcher images.+        let unwatched = Attribution { pid: 500, created_at: Some(invoked + 1), source: "shellExecuteHandle".into() };+        let via_shim = vec![+            p(501, "CATSTART.exe", Some(invoked + 2), Some(500)),+            p(502, "SWXDesktopLauncher.exe", Some(invoked + 3), Some(501)),+        ];+        let found = attributed_chain(&via_shim, Some(&unwatched), &[], &[], invoked).unwrap();+        let pids: Vec<u32> = found.iter().map(|x| x.pid).collect();+        assert_eq!(pids, vec![501, 502], "lineage crosses a root we may not terminate: {found:?}");+    }++    #[test]+    fn a_recorded_member_is_re_confirmed_by_identity_not_by_its_number() {+        let invoked = 1_000_000;+        let recorded = vec![p(90011, "SWXDesktopLauncher.exe", Some(invoked + 2), Some(90010))];+        let root = Attribution { pid: 90010, created_at: Some(invoked + 1), source: "x".into() };+        // CATSTART has exited (it does, ~3s into a healthy launch) and its+        // number now belongs to a chain the user started two minutes later.+        let census = vec![+            p(90010, "CATSTART.exe", Some(invoked + 120), Some(4444)),+            p(90011, "SWXDesktopLauncher.exe", Some(invoked + 2), Some(90010)),+        ];+        let mine = attributed_chain(&census, Some(&root), &recorded, &[], invoked).unwrap();+        let pids: Vec<u32> = mine.iter().map(|x| x.pid).collect();+        assert_eq!(pids, vec![90011], "the recycled root is not re-adopted: {mine:?}");+    }++    #[test]+    fn a_process_is_only_the_same_process_when_its_start_time_agrees() {+        let a = p(10, "CATSTART.exe", Some(1000), None);+        assert!(a.same_process(&p(10, "CATSTART.exe", Some(1000), None)));+        assert!(!a.same_process(&p(10, "CATSTART.exe", Some(1001), None)), "a reused pid");+        assert!(!a.same_process(&p(10, "SWXDesktopLauncher.exe", Some(1000), None)));+        assert!(+            !p(10, "CATSTART.exe", None, None).same_process(&p(10, "CATSTART.exe", None, None)),+            "two unknowns are not a match"+        );+    }++    #[test]+    fn the_route_plan_starts_with_what_worked_and_still_tries_everything() {+        assert_eq!(route_plan(None), ROUTES.to_vec());+        let plan = route_plan(Some("cmdStart"));+        assert_eq!(plan[0], "cmdStart");+        assert_eq!(plan.len(), ROUTES.len(), "no route is dropped, and none is repeated");+        assert_eq!(route_plan(Some("rm -rf /")), ROUTES.to_vec(), "a bogus route is ignored, not run");+        assert!(!is_route("rm -rf /"));+    }++    #[test]+    fn a_thrashing_solidworks_is_busy_not_dead() {+        // LIVE, 2026-09-08: 17.9 GB, unsaved assembly, not-responding + COM+        // timeout for ~5 minutes — and burning ~70% of a core with memory+        // creeping and no dialog. It RECOVERED. "Only the user can end it" was+        // the wrong advice, and telling somebody to end a task that is about to+        // finish is worse than telling them to wait.+        assert_eq!(+            liveness_verdict(Some(false), Some(21.0), Some(30.0), Some(40), Some(0)),+            "busy"+        );+        // Memory moving on its own is work too.+        assert_eq!(liveness_verdict(Some(false), Some(0.0), Some(30.0), Some(60), Some(0)), "busy");+        // BUSY is a RATE, so a SHORT sample is fine — but a ZERO-length one+        // measures nothing at all and is UNKNOWN, not busy.+        assert_eq!(liveness_verdict(Some(false), Some(5.0), Some(2.0), Some(0), Some(0)), "busy");+        assert_eq!(liveness_verdict(Some(false), Some(12.0), Some(0.0), Some(0), Some(0)), "unknown");+        // A TRICKLE over a long sample is NOT work: 0.3s of CPU across ten+        // minutes is a process doing essentially nothing, and calling that busy+        // tells the user to wait for ever.+        assert_eq!(liveness_verdict(Some(false), Some(0.3), Some(600.0), Some(0), Some(0)), "dead");+        // ...and an unreadable window census cannot support a dead verdict.+        assert_eq!(liveness_verdict(Some(false), Some(0.3), Some(600.0), Some(0), None), "unknown");+        // Real work that has been going on far too long stops being a reason to+        // keep waiting.+        assert_eq!(+            liveness_verdict_for(Some(false), Some(300.0), Some(600.0), Some(0), Some(0), Some(20 * 60)),+            "unknown"+        );+        // NO work over a long enough sample, and nothing on screen: dead.+        assert_eq!(liveness_verdict(Some(false), Some(0.0), Some(30.0), Some(0), Some(0)), "dead");+        // A dialog means something is being ASKED, not that nothing is happening.+        assert_eq!(liveness_verdict(Some(false), Some(0.0), Some(30.0), Some(0), Some(1)), "unknown");+        // ONE reading, or a sample too short to mean anything, is UNKNOWN —+        // never "dead". This is the guard that would have stopped the wrong call.+        assert_eq!(liveness_verdict(Some(false), None, None, None, None), "unknown");+        assert_eq!(liveness_verdict(Some(false), Some(0.0), Some(3.0), Some(0), Some(0)), "unknown");+        assert!(DEAD_SAMPLE_SECS >= 15, "a dead verdict needs a sample worth the name");+        // A responding app is not a liveness question at all.+        assert_eq!(liveness_verdict(Some(true), None, None, None, None), "responding");+        assert_eq!(liveness_verdict(None, Some(0.0), Some(30.0), Some(0), Some(0)), "unknown");+    }++    #[test]+    fn the_verdict_advice_says_wait_for_busy_and_never_for_dead() {+        let busy = verdict_advice("busy").to_lowercase();+        assert!(busy.contains("wait"), "busy must advise waiting: {busy}");+        assert!(!busy.contains("only the user can end"), "busy must not read as a death sentence");+        assert!(busy.contains("do not advise ending"));+        let dead = verdict_advice("dead").to_lowercase();+        assert!(dead.contains("only the user can end it"));+        assert!(!dead.contains("tell the user to wait"));+        let unknown = verdict_advice("unknown").to_lowercase();+        assert!(unknown.contains("poll") && unknown.contains("again"));+    }++    #[test]+    fn hung_needs_two_independent_signals_and_answers_unknown_otherwise() {+        assert_eq!(is_hung(Some(false), Some(true)), Some(true));+        assert_eq!(is_hung(Some(false), Some(false)), Some(false), "a rebuild is not a hang");+        assert_eq!(is_hung(Some(true), Some(true)), Some(false), "a COM timeout alone is a modal");+        // UNKNOWN, not false. `None` is what a com host BUSY WITH OUR OWN LONG+        // VERB produces — the 0.4.0 code counted that as a timeout, so the+        // bridge reported a working session as hung whenever it was itself+        // doing something slow.+        assert_eq!(is_hung(Some(false), None), None);+        assert_eq!(is_hung(None, Some(true)), None);+    }++    #[test]+    fn exhaustion_is_claimed_only_from_the_one_signal_that_proves_it() {+        // THE measured healthy session on the same machine the same week.+        assert!(exhaustion(Some(13_100), Some(33), false).is_none());+        assert!(exhaustion(Some(17_465), Some(52), false).is_none(), "even the wedged session's numbers");+        assert!(exhaustion(None, None, false).is_none());+        // SOLIDWORKS accepting a NewDocument and handing back nothing is the+        // signature, and it is sufficient on its own.+        assert!(exhaustion(None, None, true).unwrap().contains("stock template"));++        // The compound verdict needs all three, and is UNKNOWN-safe.+        assert!(exhaustion_confirmed(false, Some(false), Some(true), true, Some(20_000)).is_some());+        assert!(exhaustion_confirmed(false, Some(false), Some(true), false, Some(20_000)).is_none(), "not rising");+        assert!(exhaustion_confirmed(false, Some(false), None, true, Some(20_000)).is_none(), "no COM verdict");+        assert!(exhaustion_confirmed(false, Some(true), Some(true), true, Some(20_000)).is_none(), "responding");+    }++    #[test]+    fn the_memory_figure_is_advisory_and_only_above_what_was_ever_measured() {+        assert!(memory_advisory(Some(13_100), Some(9_000), Some(33)).is_none(), "a healthy big session");+        assert!(memory_advisory(Some(17_465), Some(12_000), Some(52)).is_none(), "even AT the measurement");+        let hint = memory_advisory(Some(18_000), Some(12_000), Some(52)).unwrap();+        assert!(hint.contains("18000") && hint.contains("12000"), "both figures, side by side: {hint}");+        assert!(hint.contains("not a verdict"), "{hint}");+        assert!(memory_advisory(None, None, None).is_none(), "no reading is not an observation");+    }++    #[test]+    fn a_control_lookup_is_a_find_only_when_it_says_so_structurally() {+        // The QUERY ECHO: the bridge sent `contains: "Restart SOLIDWORKS"`, so+        // any reply quoting it back contains the button name. Zero controls.+        assert!(!mentions_button(&json!({+            "success": true,+            "query": {"hwnd": 111, "contains": "Restart SOLIDWORKS", "role": "button"},+            "controls": [], "count": 0+        })));+        assert!(!mentions_button(&json!({"success": false})));+        assert!(!mentions_button(&json!({"success": true, "found": false, "name": "Restart SOLIDWORKS Design"})));+        assert!(!mentions_button(&json!({"success": true, "controls": [{"name": "Close"}]})));+        assert!(!mentions_button(&json!({"success": true, "somethingUnrecognised": 1})), "an unknown shape is a NO");+        // ...and the shapes that ARE a find.+        assert!(mentions_button(&json!({+            "success": true, "controls": [{"name": "Restart SOLIDWORKS Design", "invokable": true}]+        })));+        assert!(mentions_button(&json!({"success": true, "found": true, "name": "Restart SOLIDWORKS Design"})));+        assert!(mentions_button(&json!({+            "success": true, "control": {"automationId": "btnRestart SOLIDWORKS", "invokable": true}+        })));+    }++    #[test]+    fn a_crash_reporter_says_a_crash_happened_it_does_not_merely_mention_solidworks() {+        for yes in [+            "SOLIDWORKS Design has stopped working",+            "SOLIDWORKS Error Report",+            "SOLIDWORKS has stopped responding",+            "SOLIDWORKS Document Recovery",+        ] {+            assert!(is_crash_reporter_candidate(yes), "{yes} should be a candidate");+        }+        for no in [+            "SOLIDWORKS crash on save — how to fix it - Google Chrome",+            "Restart SOLIDWORKS to finish installing the update",+            "SOLIDWORKS Installation Manager — restart required",+            "Re: SOLIDWORKS keeps crashing - Outlook",+            "SOLIDWORKS",+            "Save changes to Part1?",+            "gallia - Google Chrome",+        ] {+            assert!(!is_crash_reporter_candidate(no), "{no} must NOT be a candidate");+        }+    }++    #[test]+    fn stages_ramp_in_order_and_carry_advice() {+        let ramp = [+            Stage::Invoked,+            Stage::LauncherStarted,+            Stage::RunBegin,+            Stage::HelperSignIn,+            Stage::SldworksUp,+            Stage::Attaching,+            Stage::Attached,+        ];+        for pair in ramp.windows(2) {+            assert!(pair[0] < pair[1], "{:?} must precede {:?}", pair[0], pair[1]);+        }+        for s in ramp {+            assert!(!s.name().is_empty());+            assert!(s.advice().len() > 20, "{s:?} needs advice a caller can act on");+        }+        assert_eq!(Stage::RunBegin.name(), "runBegin");+    }++    #[test]+    fn a_launcher_log_is_ours_only_when_the_evidence_says_so() {+        use crate::launchos::{stamp_as_utc_epoch, stamp_of, LogFile};+        let log = |stamp: Option<u64>, created: Option<u64>| LogFile {+            path: "x".into(),+            created_at: created,+            stamp,+        };+        // A REALISTIC pair: the stamp is local time, the fs time is UTC, and+        // they agree to within a timezone.+        let s1 = stamp_of("20260904172307_V6R2026x.HF4.13.log").unwrap();+        let s0 = stamp_of("20260904121543_V6R2026x.HF4.13.log").unwrap();+        let utc1 = stamp_as_utc_epoch(s1).unwrap();+        assert!(log(Some(s1), Some(utc1)).is_newer_than(Some(s0), Some(utc1 - 18_000)));+        assert!(!log(Some(s0), Some(utc1 - 18_000)).is_newer_than(Some(s1), Some(utc1)));++        // NO BASELINE = NO. This is what a FAILED directory listing produced,+        // and the old rule made every old log ours — five of the nine on the+        // real machine contain `Run Begin`.+        assert!(!log(Some(s1), Some(utc1)).is_newer_than(None, None));+        assert!(!log(None, Some(100)).is_newer_than(None, None));++        // EITHER clock may answer yes. Across a daylight-saving repeat the+        // local stamp goes BACKWARDS while the filesystem does not.+        let dst_ours = stamp_of("20261101013000_V6R2026x.HF4.13.log").unwrap();+        let dst_base = stamp_of("20261101015900_V6R2026x.HF4.13.log").unwrap();+        let dst_utc = stamp_as_utc_epoch(dst_ours).unwrap();+        assert!(+            log(Some(dst_ours), Some(dst_utc + 1_800)).is_newer_than(Some(dst_base), Some(dst_utc)),+            "the filesystem is monotonic even when the wall clock is not"+        );++        // Fall back to fs time when there is no stamp; refuse when neither reads.+        assert!(log(None, Some(100)).is_newer_than(None, Some(50)));+        assert!(!log(None, Some(50)).is_newer_than(None, Some(100)));+        assert!(!log(None, None).is_newer_than(None, Some(50)));++        // A stamp the filesystem contradicts is NOT trusted — one log copied+        // from another machine would otherwise poison a directory nothing prunes.+        assert!(log(Some(s1), Some(0)).trusted_stamp().is_none(), "a stamp 56 years off its file");+        assert!(log(Some(s1), Some(utc1)).trusted_stamp().is_some());+        // ...and neither is one from the future.+        let future = 20990101000000u64;+        assert!(log(Some(future), Some(crate::launchos::epoch_secs())).trusted_stamp().is_none());++        assert_eq!(stamp_of("20260904172307_V6R2026x.HF4.13.log"), Some(20260904172307));+        assert_eq!(stamp_of("V6R2026x.HF4.13.log"), None);+        assert_eq!(stamp_of("2026090417230_short.log"), None, "13 digits is not a stamp");+        // The civil-date maths, against a known instant.+        assert_eq!(stamp_as_utc_epoch(19700101000000), Some(0));+        assert_eq!(stamp_as_utc_epoch(20260904172307), Some(1_788_542_587));+        assert_eq!(stamp_as_utc_epoch(20261399000000), None, "month 13 is not a date");+    }++    #[test]+    fn only_the_two_routes_that_can_say_what_they_started_may_ever_kill() {+        assert!(route_is_attributable("shellExecute"));+        assert!(route_is_attributable("powershell"));+        assert!(!route_is_attributable("explorer"), "the shell forwards the link and returns nothing");+        assert!(!route_is_attributable("cmdStart"), "`start` returns as soon as it has handed off");+        // ...and the attributable ones are tried FIRST.+        assert_eq!(ROUTES[0], "shellExecute");+        assert_eq!(ROUTES[1], "powershell");+        assert!(ROUTES.iter().all(|r| is_route(r)));+    }+}

@@ -0,0 +1,1616 @@+//! THE OS FACTS THE LAUNCH STATE MACHINE RUNS ON — and the fake that makes+//! every one of its transitions testable off Windows.+//!+//! `launch.rs` decides WHAT to do about a stalled 3DEXPERIENCE launcher chain.+//! This module answers the four questions it needs to decide anything, and+//! nothing else:+//!+//!   * which launcher-chain processes exist, and **when each was created**+//!     (the creation time is the whole safety property — see+//!     [`crate::launch::may_terminate`]);+//!   * which `SWXDesktopLauncher` / `SWXDesktopHelper` log files exist, when+//!     each was created, and what is in them;+//!   * is SOLIDWORKS' main window answering messages, and how much memory and+//!     how many handles is the process holding;+//!   * terminate ONE process, BY PID.+//!+//! WHY BY PID AND NEVER BY IMAGE NAME. `taskkill /IM CATSTART.exe` would kill a+//! chain the USER started thirty seconds earlier as readily as the one this+//! bridge started, and `taskkill /F /T` would take its children with it. Every+//! terminate here opens ONE pid, checks the image name it was opened for still+//! matches, and terminates that handle. There is no image-name kill anywhere in+//! this bridge's launch path.+//!+//! Off Windows (and under `SWX_LAUNCH_FAKE_DIR`) the whole surface is served by+//! [`FakeOs`], a directory-backed simulator the test suite drives. A launch+//! state machine that can only be exercised on one particular Windows desktop+//! with one particular CAD application installed is a state machine that is+//! never exercised at all.++use serde_json::{json, Value};+use std::time::{SystemTime, UNIX_EPOCH};++/// Point the OS layer at a simulated machine. Test-only; never set in+/// production. Its presence is what selects [`FakeOs`] over the real one.+pub const ENV_FAKE_DIR: &str = "SWX_LAUNCH_FAKE_DIR";++/// The images the launch machine looks at. Deliberately short: this is a+/// process census for ONE purpose, not a task manager.+pub const WATCHED_IMAGES: &[&str] = &[+    "CATSTART.exe",+    "SWXDesktopLauncher.exe",+    "SLDWORKS.exe",+    "3DEXPERIENCELauncher.exe",+    "3DEXPERIENCELauncherSysTray.exe",+    "3DEXPERIENCELauncherService.exe",+    // THE QUIT LADDER'S CENSUS (docs/QUIT-INVESTIGATION.md §5.4): the+    // per-session children a graceful exit must REAP, and the platform daemons+    // that must SURVIVE one. Their survival is consent, not a failure — see+    // `quit::EXPECTED_SURVIVORS`.+    "sldProcMon.exe",+    "sldsurfacing.exe",+    "sldimport.exe",+    "swCefSubProc.exe",+    "ENOPLMCSAClient.exe",+    "EdmServerV6.exe",+    "SWXDesktopHelper.exe",+    "sldBgDwld.exe",+    // PARENT LINKS ONLY — never terminable (see `launch::NEVER_TERMINATE`).+    // A CATSTART's parent is the shell that ran the .lnk, and without these in+    // the census every parent link out of a chain root dangles: the walk could+    // not tell a chain descended from OUR invoke from one descended from the+    // user's double-click, because neither parent existed to compare.+    "explorer.exe",+    "cmd.exe",+    "powershell.exe",+    "pwsh.exe",+];++/// One process, with the two facts that matter: WHEN it started, and WHO+/// started it.+#[derive(Clone, Debug, PartialEq)]+pub struct ProcInfo {+    pub pid: u32,+    /// The image name as the OS reports it (`CATSTART.exe`). Compared+    /// case-insensitively everywhere — Windows paths and image names are.+    pub image: String,+    /// Unix epoch seconds. `None` means the creation time could not be read,+    /// which [`crate::launch::may_terminate`] treats as "not ours".+    pub created_at: Option<u64>,+    /// Parent pid, so a chain member that appeared after we stopped looking can+    /// still be attributed to the CATSTART we started. `None` = unknown, which+    /// attributes nothing.+    pub ppid: Option<u32>,+}++impl ProcInfo {+    pub fn to_json(&self) -> Value {+        json!({"pid": self.pid, "image": self.image, "createdAt": self.created_at, "ppid": self.ppid})+    }+    pub fn is(&self, image: &str) -> bool {+        self.image.eq_ignore_ascii_case(image)+    }+    /// Identity for the kill path: a pid ALONE is not one, because Windows+    /// reuses pids. (pid, image, creation time) is.+    pub fn same_process(&self, other: &ProcInfo) -> bool {+        self.pid == other.pid+            && self.is(&other.image)+            && self.created_at.is_some()+            && self.created_at == other.created_at+    }+}++/// A launcher/helper log file and when it appeared. The launch machine cares+/// only about logs created AFTER its own invoke — an older one describes+/// somebody else's launch.+#[derive(Clone, Debug, PartialEq)]+pub struct LogFile {+    pub path: String,+    pub created_at: Option<u64>,+    /// The `yyyyMMddHHmmss` the LAUNCHER ITSELF put in the filename, as a plain+    /// comparable integer.+    ///+    /// Preferred over the filesystem's creation time for "did this log appear+    /// after our invoke?": the launcher writes the stamp when it starts, so it+    /// is the launcher's own account of when it ran, while `created()` can be+    /// absent on some filesystems, can be the time the file was COPIED, and on+    /// Windows survives a delete-and-recreate of the same name (file-system+    /// tunnelling) — which would make a brand-new log look older than our+    /// invoke and hide the very stall we are watching for. Compared only+    /// against other stamps, never converted to epoch, so no timezone is+    /// guessed.+    pub stamp: Option<u64>,+}++/// The widest real UTC offset is +14:00 and the widest negative -12:00; add an+/// hour of DST and some slack. A filename stamp is written in LOCAL time and+/// the filesystem records UTC, so the two may legitimately differ by up to+/// this much — and by no more.+const MAX_TZ_SKEW_SECS: u64 = 26 * 3600;+/// A stamp this far ahead of now (allowing for any timezone) did not come from+/// a clock this machine is keeping.+const FUTURE_STAMP_SLACK_SECS: u64 = 300;++/// `yyyyMMddHHmmss` read as if it were UTC. Used only to CORROBORATE a stamp+/// against the filesystem's own time — never as a timestamp in its own right,+/// because the launcher writes local time and this function does not know the+/// offset.+pub fn stamp_as_utc_epoch(stamp: u64) -> Option<u64> {+    let (y, mo, d) = ((stamp / 10_000_000_000) as i64, ((stamp / 100_000_000) % 100) as i64, ((stamp / 1_000_000) % 100) as i64);+    let (h, mi, sec) = ((stamp / 10_000) % 100, (stamp / 100) % 100, stamp % 100);+    if !(1970..=9999).contains(&y) || !(1..=12).contains(&mo) || !(1..=31).contains(&d) {+        return None;+    }+    if h > 23 || mi > 59 || sec > 60 {+        return None;+    }+    // days-from-civil (Howard Hinnant): exact, no table, no leap-year special case.+    let y2 = y - i64::from(mo <= 2);+    let era = if y2 >= 0 { y2 } else { y2 - 399 } / 400;+    let yoe = y2 - era * 400;+    let mp = (mo + 9) % 12;+    let doy = (153 * mp + 2) / 5 + d - 1;+    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;+    let days = era * 146_097 + doe - 719_468;+    u64::try_from(days * 86_400 + (h * 3600 + mi * 60 + sec) as i64).ok()+}++impl LogFile {+    /// The filename stamp, but ONLY when the filesystem corroborates it.+    ///+    /// The launcher stamps LOCAL time. A stamp that cannot be reconciled with+    /// the file's own UTC creation time — a log copied from another machine, a+    /// clock correction, a file written by a different timezone's session —+    /// is not evidence of anything, and one such file in that directory (which+    /// nothing ever prunes) would poison every comparison after it.+    pub fn trusted_stamp(&self) -> Option<u64> {+        let stamp = self.stamp?;+        let as_utc = stamp_as_utc_epoch(stamp)?;+        if as_utc > epoch_secs() + MAX_TZ_SKEW_SECS + FUTURE_STAMP_SLACK_SECS {+            return None; // from the future, whatever timezone this is+        }+        let created = self.created_at?;+        (as_utc.abs_diff(created) <= MAX_TZ_SKEW_SECS).then_some(stamp)+    }++    /// Is this log NEWER than the newest one that existed before our invoke?+    ///+    /// TWO INDEPENDENT CLOCKS, and EITHER may answer yes — the launcher's own+    /// local-time stamp, or the filesystem's UTC creation time. Three defects+    /// in the first version, all of them making the gate's central measurement+    /// a fabrication:+    ///+    ///   * it SHORT-CIRCUITED on the stamps and never consulted the filesystem.+    ///     For the one hour a year a local clock repeats, our own log carries a+    ///     LOWER stamp than one written before it, so the bridge concluded its+    ///     own log did not exist and reported that nothing started.+    ///   * `(Some(_), None) => true` accepted ANY log when there was no+    ///     baseline — and no baseline is exactly what a FAILED directory+    ///     listing produced. Five of the nine logs on the real machine contain+    ///     `Run Begin`, so the bridge would read somebody else's launch from+    ///     three days ago and jump straight past stall detection.+    ///   * a future-dated stamp poisoned the directory permanently.+    ///+    /// With NO baseline the answer is NO. An unreadable listing is UNKNOWN, and+    /// unknown is never "the directory was empty".+    pub fn is_newer_than(&self, baseline_stamp: Option<u64>, baseline_created: Option<u64>) -> bool {+        if baseline_stamp.is_none() && baseline_created.is_none() {+            return false;+        }+        let stamp_newer = matches!(+            (self.trusted_stamp(), baseline_stamp),+            (Some(mine), Some(base)) if mine > base+        );+        let created_newer = matches!(+            (self.created_at, baseline_created),+            (Some(mine), Some(base)) if mine > base+        );+        stamp_newer || created_newer+    }+}++/// The thread id the launcher stamps on its own lines: `17:23:09 [116244] info`.+///+/// Read from the FIRST line that has one, because that line is written by the+/// launcher's main thread at startup — the thread most likely still alive while+/// we are watching. (`Run Begin` comes from a second thread ~2s later, which is+/// exactly the pair the ground-truth log shows: [107936] then [116244].)+pub fn writer_thread_of(log_text: &str) -> Option<u32> {+    for line in log_text.lines().take(40) {+        let open = line.find('[')?;+        let close = line[open..].find(']')? + open;+        if let Ok(tid) = line[open + 1..close].trim().parse::<u32>() {+            return Some(tid);+        }+    }+    None+}++/// `20260904172307_V6R2026x.HF4.13.log` -> `20260904172307`.+pub fn stamp_of(file_name: &str) -> Option<u64> {+    let digits: String = file_name.chars().take_while(|c| c.is_ascii_digit()).collect();+    (digits.len() == 14).then(|| digits.parse().ok())?+}++/// One top-level window, as the OS reports it — read WITHOUT ab.+///+/// Two callers need this and neither can depend on ab: the busy-vs-dead verdict+/// ("did a dialog appear, or is it silently doing nothing?") and, in 0.5.1, the+/// quit ladder's "no blocking dialog" precondition. `swx_status` on the dev+/// bridge reports `abAvailable:false`, and an unanswerable precondition refuses,+/// so depending on ab would make those permanently unavailable during an outage.+#[derive(Clone, Debug, PartialEq)]+pub struct WindowInfo {+    pub hwnd: i64,+    pub class_name: String,+    pub title: String,+    pub visible: bool,+}++impl WindowInfo {+    pub fn to_json(&self) -> Value {+        json!({+            "hwnd": self.hwnd,+            "className": self.class_name,+            "title": self.title,+            "visible": self.visible,+        })+    }+    /// The Win32 dialog class every SOLIDWORKS modal is.+    pub fn is_dialog(&self) -> bool {+        self.class_name == "#32770"+    }+}++/// What SOLIDWORKS is costing the machine right now.+#[derive(Clone, Debug, Default, PartialEq)]+pub struct ProcMetrics {+    /// Total CPU time (kernel + user) the process has consumed, in seconds. The+    /// DELTA over a short sample is what separates a process that is thrashing+    /// from one that is dead: on 2026-09-08 SOLIDWORKS at 17.9 GB went+    /// not-responding with a COM timeout for ~5 minutes and was reported as+    /// hung — while it was burning ~70% of a core and RECOVERED once the user+    /// saved. "Not responding" is a statement about a message loop, not about+    /// whether work is happening.+    pub cpu_seconds: Option<f64>,+    /// `PrivateUsage` — the commit charge, which is what runs out.+    pub private_mb: Option<u64>,+    /// `WorkingSetSize` — RESIDENT memory. Reported BESIDE private rather than+    /// instead of it: the two diverge by many gigabytes on a paged-out CAD+    /// session, and quoting one as "memory" invites a wrong conclusion about+    /// the other.+    pub working_set_mb: Option<u64>,+    pub handles: Option<u32>,+}++/// The OS facts, behind one trait so the state machine has exactly one seam and+/// the suite can drive every branch of it.+pub trait LaunchOs: Send + Sync {+    /// Every process whose image is in [`WATCHED_IMAGES`].+    ///+    /// `Err` means THE CENSUS FAILED — never an empty list. "I could not look"+    /// and "nothing is running" lead to opposite decisions, and collapsing the+    /// first into the second is the defect this whole file was written after.+    fn processes(&self) -> Result<Vec<ProcInfo>, String>;+    /// `SWXDesktopLauncher\*.log`, newest first.+    fn launcher_logs(&self) -> Result<Vec<LogFile>, String>;+    /// `SWXDesktopHelper\*.log`, newest first — the sign-in/licence stage.+    fn helper_logs(&self) -> Result<Vec<LogFile>, String>;+    fn read_log(&self, path: &str) -> Result<String, String>;+    /// Terminate ONE pid, having re-checked that it still is `image` AND was+    /// created at `created_at`.+    ///+    /// The creation time closes the TOCTOU: between the census that chose this+    /// pid and the kill, the process can exit and Windows can hand its number+    /// to something else. The check is re-done on the OPENED HANDLE, which is+    /// the only ordering that cannot be raced — a check against a fresh census+    /// is still a check against a different object from the one the handle+    /// refers to.+    fn terminate(&self, pid: u32, image: &str, created_at: Option<u64>) -> Result<(), String>;++    /// Is this pid running? `None` = cannot tell, which is never read as "yes".+    fn pid_alive(&self, pid: u32) -> Option<bool> {+        self.processes().ok().map(|c| c.iter().any(|p| p.pid == pid))+    }+    /// `IsHungAppWindow` on a top-level window. `None` = unknown, which is+    /// never reported as "responding".+    fn window_responding(&self, hwnd: i64) -> Option<bool>;+    /// The main top-level window owned by `pid`, for when COM cannot tell us.+    fn main_window_of_pid(&self, pid: u32) -> Option<i64>;++    /// WHICH PROCESS OWNS THIS THREAD? The launcher stamps a thread id in every+    /// line it writes (`17:23:09 [116244] info Run Begin`), so a log can be+    /// bound to the process that wrote it — which is the only positive proof+    /// that a log is OURS rather than merely newer than the ones we saw before.+    ///+    /// Best effort in one direction only: a match proves authorship, a miss+    /// proves nothing (threads exit, and the writing thread usually has by the+    /// time we read the file).+    fn thread_owner(&self, _tid: u32) -> Option<u32> {+        None+    }+    fn process_metrics(&self, pid: u32) -> ProcMetrics;+    /// Every top-level window owned by `pid`. `Err` = could not look, which is+    /// UNKNOWN — never "no dialogs".+    fn windows_of_pid(&self, _pid: u32) -> Result<Vec<WindowInfo>, String> {+        Err("this host cannot enumerate windows".into())+    }++    /// This process's own pid — recorded on a launch attempt so a LATER bridge+    /// can tell "somebody is supervising this" from "this was left behind".+    fn self_pid(&self) -> u32 {+        std::process::id()+    }+    fn now(&self) -> u64 {+        epoch_secs()+    }+    /// Name for the ledger, so a reader can tell a simulated run from a real one.+    fn kind(&self) -> &'static str;+}++pub fn epoch_secs() -> u64 {+    SystemTime::now().duration_since(UNIX_EPOCH).map(|d| d.as_secs()).unwrap_or(0)+}++pub fn epoch_ms() -> u128 {+    SystemTime::now().duration_since(UNIX_EPOCH).map(|d| d.as_millis()).unwrap_or(0)+}++/// The OS layer for this process: the real Windows one, or the simulator when+/// `SWX_LAUNCH_FAKE_DIR` is set (or we are not on Windows at all, where the+/// real one could not answer anything).+pub fn os() -> Box<dyn LaunchOs> {+    if let Ok(dir) = std::env::var(ENV_FAKE_DIR) {+        if !dir.is_empty() {+            return Box::new(FakeOs { dir: std::path::PathBuf::from(dir) });+        }+    }+    #[cfg(windows)]+    {+        Box::new(win::WindowsOs)+    }+    #[cfg(not(windows))]+    {+        Box::new(UnknownOs)+    }+}++/// Off Windows with no simulator configured: every question answers UNKNOWN.+/// Not "nothing is running" — the honest answer to a question this host cannot+/// be asked.+pub struct UnknownOs;++impl LaunchOs for UnknownOs {+    fn processes(&self) -> Result<Vec<ProcInfo>, String> {+        Err("no process census on this host (not Windows, and no launch simulator configured)".into())+    }+    fn launcher_logs(&self) -> Result<Vec<LogFile>, String> {+        Err("no 3DEXPERIENCE launcher logs on this host".into())+    }+    fn helper_logs(&self) -> Result<Vec<LogFile>, String> {+        Err("no 3DEXPERIENCE helper logs on this host".into())+    }+    fn read_log(&self, _path: &str) -> Result<String, String> {+        Err("no launcher logs on this host".into())+    }+    fn terminate(&self, _pid: u32, _image: &str, _created_at: Option<u64>) -> Result<(), String> {+        Err("this host cannot terminate processes for the launch machine".into())+    }+    fn pid_alive(&self, _pid: u32) -> Option<bool> {+        None+    }+    fn window_responding(&self, _hwnd: i64) -> Option<bool> {+        None+    }+    fn main_window_of_pid(&self, _pid: u32) -> Option<i64> {+        None+    }+    fn process_metrics(&self, _pid: u32) -> ProcMetrics {+        ProcMetrics::default()+    }+    fn kind(&self) -> &'static str {+        "unavailable"+    }+}++// ── the simulator ───────────────────────────────────────────────────────────++/// A machine on disk. Everything the state machine can observe is derived from+/// two test-authored files plus the invocation log the mock com host appends+/// to, so a test writes a SCENARIO ("route A stalls, route B works") and then+/// measures what the bridge DID about it.+///+/// Layout under `SWX_LAUNCH_FAKE_DIR`:+///+/// ```text+/// routes.json        {"<route>": {"chain":bool,"runBeginAfterMs":n|null,+///                                 "helperAfterMs":n|null,"sldworksAfterMs":n|null,+///                                 "attachAfterMs":n|null}}+/// preexisting.json   [{"pid":6076,"image":"3DEXPERIENCELauncher.exe","ageSeconds":3600}]+/// sldworks.json      {"responding":true,"privateMB":800,"handles":3000,"hwnd":4242}+/// invocations.jsonl  appended by the mock com host: {"seq":1,"route":"explorer","atMs":...}+/// terminated.jsonl   appended by terminate(): {"pid":...,"image":"...","atMs":...}+/// ```+pub struct FakeOs {+    pub dir: std::path::PathBuf,+}++/// What one route does on the simulated machine.+#[derive(Clone, Debug)]+pub struct RouteSpec {+    pub chain: bool,+    /// Can THIS invocation say what it started? Defaults to whatever the route+    /// can do in principle. Set `false` to model the shape `ShellExecuteExW` on+    /// a `.lnk` is most likely to produce: the shell hands the link to an+    /// already-running process (DDE) and returns NO HANDLE, so a route that can+    /// normally attribute does not, on this launch.+    pub attributable: Option<bool>,+    /// The chain runs, but its ROOT never appears in the census — modelling a+    /// handle-proven root whose image this bridge does not watch. Its children+    /// still appear, so lineage can (and must) carry across it.+    pub root_visible: bool,+    /// The chain runs but never appears in the process census — a launcher+    /// whose images this bridge does not watch, or one the census cannot see.+    /// Models "the invoke told us a root and we never found it".+    pub invisible_chain: bool,+    pub run_begin_after_ms: Option<u64>,+    pub helper_after_ms: Option<u64>,+    pub sldworks_after_ms: Option<u64>,+    pub attach_after_ms: Option<u64>,+}++impl Default for RouteSpec {+    /// THE OBSERVED FAILURE, as the default: the chain starts, the log stops at+    /// `SecurityContext:`, and nothing else ever happens. A scenario that does+    /// not mention a route gets the behaviour five of five real bridge launches+    /// produced on 2026-09-04.+    fn default() -> Self {+        RouteSpec {+            chain: true,+            attributable: None,+            root_visible: true,+            invisible_chain: false,+            run_begin_after_ms: None,+            helper_after_ms: None,+            sldworks_after_ms: None,+            attach_after_ms: None,+        }+    }+}++/// One simulated launcher invocation.+#[derive(Clone, Debug)]+pub struct Invocation {+    pub seq: u64,+    pub route: String,+    pub at_ms: u128,+}++impl Invocation {+    /// Deterministic pids, so a test can name the process it expects to die.+    pub fn catstart_pid(&self) -> u32 {+        900_000 + (self.seq as u32) * 10+    }+    pub fn launcher_pid(&self) -> u32 {+        self.catstart_pid() + 1+    }+    pub fn sldworks_pid(&self) -> u32 {+        self.catstart_pid() + 2+    }+    pub fn log_path(&self) -> String {+        format!("fake://launcher/{}", self.seq)+    }+    pub fn helper_log_path(&self) -> String {+        format!("fake://helper/{}", self.seq)+    }+}++impl FakeOs {+    fn read_json(&self, name: &str) -> Value {+        std::fs::read_to_string(self.dir.join(name))+            .ok()+            .and_then(|t| serde_json::from_str(&t).ok())+            .unwrap_or(Value::Null)+    }++    /// Does this route create a launcher chain on the simulated machine?+    pub fn route_starts_chain(&self, route: &str) -> bool {+        self.spec(route).chain+    }++    /// The simulated thread ids a launcher process writes with: two per+    /// process, mirroring the real log's [main] then [run] pair.+    fn thread_of(launcher_pid: u32) -> u32 {+        launcher_pid + 500_000+    }++    /// Does THIS invocation hand back a root? A scenario may say `false` for a+    /// route that normally can, which is how the "no handle" branch is tested.+    pub fn route_reports_root(&self, route: &str) -> bool {+        let spec = self.spec(route);+        spec.chain && spec.attributable.unwrap_or(true)+    }++    fn spec(&self, route: &str) -> RouteSpec {+        let table = self.read_json("routes.json");+        let entry = table.get(route);+        let ms = |k: &str| entry.and_then(|e| e.get(k)).and_then(|v| v.as_u64());+        RouteSpec {+            chain: entry+                .and_then(|e| e.get("chain"))+                .and_then(|v| v.as_bool())+                .unwrap_or(true),+            attributable: entry.and_then(|e| e.get("attributable")).and_then(|v| v.as_bool()),+            root_visible: entry+                .and_then(|e| e.get("rootVisible"))+                .and_then(|v| v.as_bool())+                .unwrap_or(true),+            invisible_chain: entry+                .and_then(|e| e.get("invisibleChain"))+                .and_then(|v| v.as_bool())+                .unwrap_or(false),+            run_begin_after_ms: ms("runBeginAfterMs"),+            helper_after_ms: ms("helperAfterMs"),+            sldworks_after_ms: ms("sldworksAfterMs"),+            attach_after_ms: ms("attachAfterMs"),+        }+    }++    /// Every invocation the mock com host has made, oldest first.+    pub fn invocations(&self) -> Vec<Invocation> {+        std::fs::read_to_string(self.dir.join("invocations.jsonl"))+            .unwrap_or_default()+            .lines()+            .filter_map(|l| serde_json::from_str::<Value>(l).ok())+            .filter_map(|v| {+                Some(Invocation {+                    seq: v.get("seq")?.as_u64()?,+                    route: v.get("route")?.as_str()?.to_string(),+                    at_ms: v.get("atMs")?.as_u64()? as u128,+                })+            })+            .collect()+    }++    fn terminated_pids(&self) -> Vec<u32> {+        std::fs::read_to_string(self.dir.join("terminated.jsonl"))+            .unwrap_or_default()+            .lines()+            .filter_map(|l| serde_json::from_str::<Value>(l).ok())+            .filter_map(|v| v.get("pid").and_then(|p| p.as_u64()).map(|p| p as u32))+            .collect()+    }++    /// An invocation whose chain we killed makes no further progress — exactly+    /// like the real thing, where killing CATSTART ends that attempt.+    fn alive(&self, inv: &Invocation, dead: &[u32]) -> bool {+        !dead.contains(&inv.catstart_pid()) && !dead.contains(&inv.launcher_pid())+    }++    fn elapsed_ms(&self, inv: &Invocation) -> u128 {+        epoch_ms().saturating_sub(inv.at_ms)+    }++    fn reached(&self, inv: &Invocation, after: Option<u64>) -> bool {+        match after {+            None => false,+            Some(ms) => self.elapsed_ms(inv) >= ms as u128,+        }+    }++    /// Record an invocation. Called by the MOCK com backend, which is the+    /// simulated equivalent of "the shortcut was run".+    pub fn record_invoke(dir: &std::path::Path, route: &str, shortcut: &str) -> u64 {+        let _ = std::fs::create_dir_all(dir);+        let path = dir.join("invocations.jsonl");+        let seq = std::fs::read_to_string(&path).unwrap_or_default().lines().count() as u64 + 1;+        let line = json!({"seq": seq, "route": route, "atMs": epoch_ms() as u64, "shortcut": shortcut});+        let mut text = std::fs::read_to_string(&path).unwrap_or_default();+        text.push_str(&line.to_string());+        text.push('\n');+        let _ = std::fs::write(&path, text);+        seq+    }++    /// Is a simulated SOLIDWORKS COM-attachable right now? Read by the MOCK com+    /// backend so the whole simulation has ONE source of truth: a route that+    /// stalls never becomes attachable, however long anybody polls.+    /// The pid of the SOLIDWORKS an ATTACHABLE invocation produced — the process+    /// COM would be talking to.+    ///+    /// The simulator used to publish a second SOLIDWORKS row for the mock's own+    /// "session", with a different pid and no parent, so one simulated session+    /// appeared in the census as two processes: one attached and parentless, one+    /// parented and unattached. That is not a machine state that exists, and it+    /// made the attached process unprovable by construction.+    pub fn attached_sldworks_pid(dir: &std::path::Path) -> Option<u32> {+        let me = FakeOs { dir: dir.to_path_buf() };+        let dead = me.terminated_pids();+        me.invocations()+            .into_iter()+            .filter(|i| me.alive(i, &dead))+            .find(|i| me.reached(i, me.spec(&i.route).attach_after_ms))+            .map(|i| i.sldworks_pid())+    }++    pub fn attachable(dir: &std::path::Path) -> bool {+        let me = FakeOs { dir: dir.to_path_buf() };+        let dead = me.terminated_pids();+        me.invocations()+            .iter()+            .filter(|i| me.alive(i, &dead))+            .any(|i| me.reached(i, me.spec(&i.route).attach_after_ms))+    }+}++impl LaunchOs for FakeOs {+    fn processes(&self) -> Result<Vec<ProcInfo>, String> {+        if self.dir.join("census-fails").exists() {+            return Err("simulated: the process census could not be taken".into());+        }+        let now = epoch_secs();+        let dead = self.terminated_pids();+        // A QUIT THAT HAPPENED reaps SOLIDWORKS and its per-session children from+        // the census. The mock backend (which performs the rung) and this census+        // (which measures it) read the SAME file, so the measurement can never+        // disagree with the act — the whole point of measuring by census.+        // A rung may report success while the process takes SECONDS to actually+        // go (a real `ExitApp` returns first), so each line carries the instant+        // its exit becomes EFFECTIVE. Until then SOLIDWORKS is still in the+        // census — which is exactly the divergence a single post-rung sample used+        // to hide.+        let quit = std::fs::read_to_string(self.dir.join("quit.jsonl"))+            .map(|t| {+                t.lines().filter(|l| !l.trim().is_empty()).any(|l| {+                    let v: Value = serde_json::from_str(l).unwrap_or(Value::Null);+                    let at = v+                        .get("effectiveAtMs")+                        .or_else(|| v.get("atMs"))+                        .and_then(|x| x.as_u64())+                        .unwrap_or(0);+                    at as u128 <= epoch_ms()+                })+            })+            .unwrap_or(false);+        let reaped = |image: &str| -> bool {+            quit && (image.eq_ignore_ascii_case("SLDWORKS.exe")+                || crate::quit::SESSION_CHILDREN.iter().any(|c| c.eq_ignore_ascii_case(image)))+        };+        let mut out: Vec<ProcInfo> = Vec::new();+        // Processes that were ALREADY THERE. The whole point of the creation-time+        // rule is that these survive every stall recovery.+        if let Some(rows) = self.read_json("preexisting.json").as_array() {+            for r in rows {+                let Some(pid) = r.get("pid").and_then(|p| p.as_u64()) else { continue };+                let pid = pid as u32;+                if dead.contains(&pid) {+                    continue;+                }+                let image = r.get("image").and_then(|i| i.as_str()).unwrap_or("").to_string();+                if reaped(&image) {+                    continue;+                }+                out.push(ProcInfo {+                    pid,+                    image,+                    created_at: Some(+                        now.saturating_sub(r.get("ageSeconds").and_then(|a| a.as_u64()).unwrap_or(3600)),+                    ),+                    ppid: r.get("ppid").and_then(|x| x.as_u64()).map(|v| v as u32),+                });+            }+        }+        // The SIMULATED SOLIDWORKS, as the mock backend published it. Present+        // until a quit rung reaps it — so the ladder's success measurement reads+        // the same truth the rung acted on.+        if !quit {+            if let Ok(t) = std::fs::read_to_string(self.dir.join("mock-session")) {+                if let Ok(pid) = t.trim().parse::<i64>() {+                    let pid = (pid.unsigned_abs() % 4_000_000_000) as u32;+                    // ONE SESSION IS ONE PROCESS. If a route of this scenario+                    // already produced a SOLIDWORKS, the mock's session IS that+                    // process — publishing a second row with another pid and no+                    // parent invents a machine state that cannot occur.+                    let route_spawned = Self::attached_sldworks_pid(&self.dir);+                    if route_spawned.is_some() {+                        // fall through: the invocation-derived row below is the one+                    } else if !dead.contains(&pid) && !out.iter().any(|p| p.pid == pid) {+                        // A STABLE creation time, written once and reused. Deriving+                        // it from `now` on every read made it DRIFT — and the quit+                        // ladder's success test is "this pid AND this creation time+                        // are gone", so a drifting one reported the process as gone+                        // on the very next census. A real creation time never moves.+                        let f = self.dir.join("sldworks-created");+                        let created = match std::fs::read_to_string(&f)+                            .ok()+                            .and_then(|t| t.trim().parse::<u64>().ok())+                        {+                            Some(v) => v,+                            None => {+                                let v = now.saturating_sub(3600);+                                let _ = std::fs::write(&f, v.to_string());+                                v+                            }+                        };+                        out.push(ProcInfo {+                            pid,+                            image: "SLDWORKS.exe".into(),+                            created_at: Some(created),+                            // LINEAGE, when a scenario wants to model it: the pid+                            // that started SOLIDWORKS. Re-attribution after a+                            // sign-in requires a POSITIVE link back to our own+                            // chain, and this is how a test supplies (or withholds)+                            // one. `sldworks-parent` holds a pid.+                            ppid: std::fs::read_to_string(self.dir.join("sldworks-parent"))+                                .ok()+                                .and_then(|t| t.trim().parse::<u32>().ok()),+                        });+                        // ITS OWN CHILDREN, parented to it. A 3DEXPERIENCE+                        // sign-in / licence / cloud-save window is a WEB VIEW,+                        // and its hwnd belongs to a `swCefSubProc.exe` child —+                        // so a dialog census that only knows the SOLIDWORKS pid+                        // cannot see the one modal most likely to be up. The+                        // fixture names the images; their pids are derived from+                        // the parent's so a test can predict nothing about them+                        // except the parentage, which is the whole point.+                        for (i, img) in self+                            .read_json("sldworks-children.json")+                            .as_array()+                            .map(|a| a.iter().filter_map(|v| v.as_str().map(String::from)).collect::<Vec<_>>())+                            .unwrap_or_default()+                            .iter()+                            .enumerate()+                        {+                            let child = pid.wrapping_add(1 + i as u32);+                            if dead.contains(&child) || out.iter().any(|p| p.pid == child) {+                                continue;+                            }+                            out.push(ProcInfo {+                                pid: child,+                                image: img.clone(),+                                created_at: Some(created + 1),+                                ppid: Some(pid),+                            });+                        }+                    }+                }+            }+        }+        for inv in self.invocations() {+            let spec = self.spec(&inv.route);+            let started = (inv.at_ms / 1000) as u64;+            if spec.chain && !spec.invisible_chain {+                for (pid, image, ppid) in [+                    (inv.catstart_pid(), "CATSTART.exe", None),+                    (inv.launcher_pid(), "SWXDesktopLauncher.exe", Some(inv.catstart_pid())),+                ] {+                    // `rootVisible:false` hides the CATSTART the invoke reported+                    // as its root while leaving its child in the census, which+                    // is what an unwatched shim looks like from here.+                    if pid == inv.catstart_pid() && !spec.root_visible {+                        continue;+                    }+                    if !dead.contains(&pid) {+                        out.push(ProcInfo { pid, image: image.into(), created_at: Some(started), ppid });+                    }+                }+            }+            if self.alive(&inv, &dead) && self.reached(&inv, spec.sldworks_after_ms) {+                out.push(ProcInfo {+                    pid: inv.sldworks_pid(),+                    image: "SLDWORKS.exe".into(),+                    created_at: Some(started),+                    // A real sldworks.exe is spawned BY the launcher, so the+                    // simulator models it as a child: the descendant walk must+                    // meet it and refuse it, not never meet it.+                    //+                    // `sldworks-parent` OVERRIDES that, which is how a scenario+                    // says "this SOLIDWORKS is the USER'S — it descends from a+                    // launcher that was never ours". Without the override here a+                    // fixture could only express the friendly case, and a+                    // lineage proof that is never asked a hostile question is not+                    // a proof.+                    ppid: std::fs::read_to_string(self.dir.join("sldworks-parent"))+                        .ok()+                        .and_then(|t| t.trim().parse::<u32>().ok())+                        .or(Some(inv.launcher_pid())),+                });+            }+        }+        // ── PID REUSE, which nothing else here could express.+        //+        //    A pid is one number held by DIFFERENT PROCESSES AT DIFFERENT TIMES,+        //    and that is the whole hazard the lineage rule exists for: our+        //    launcher dies, the user's launcher is issued the same number, and+        //    their SOLIDWORKS records it as its parent. Until now a fixture could+        //    only say "this pid exists"; it could not RETIRE one and reissue it,+        //    so the hostile case could only be posed in a unit test and never+        //    end-to-end.+        //+        //    `census-overrides.json` is a list of edits applied last, in order:+        //      {"retire": 900011}                     -> remove that pid+        //      {"pid": 900011, "image": "CATSTART.exe",+        //       "createdAt": 1789…, "ppid": null}     -> (re)issue it+        //    Reissuing a retired pid with a NEW creation time is exactly the+        //    situation `same_process` and the lineage window are written against.+        if let Some(rows) = self.read_json("census-overrides.json").as_array() {+            for r in rows {+                if let Some(pid) = r.get("retire").and_then(|x| x.as_u64()) {+                    out.retain(|p| p.pid != pid as u32);+                    continue;+                }+                let Some(pid) = r.get("pid").and_then(|x| x.as_u64()) else { continue };+                let pid = pid as u32;+                out.retain(|p| p.pid != pid);+                out.push(ProcInfo {+                    pid,+                    image: r+                        .get("image")+                        .and_then(|x| x.as_str())+                        .unwrap_or("CATSTART.exe")+                        .to_string(),+                    // `ageSeconds` (now minus that many, as everywhere else in+                    // this simulator) or an explicit `createdAt` epoch.+                    created_at: r+                        .get("ageSeconds")+                        .and_then(|x| x.as_i64())+                        .map(|age| if age >= 0 {+                            now.saturating_sub(age as u64)+                        } else {+                            now + age.unsigned_abs()+                        })+                        .or_else(|| r.get("createdAt").and_then(|x| x.as_u64())),+                    ppid: r.get("ppid").and_then(|x| x.as_u64()).map(|p| p as u32),+                });+            }+        }+        Ok(out)+    }++    fn launcher_logs(&self) -> Result<Vec<LogFile>, String> {+        let mut out: Vec<LogFile> = self+            .invocations()+            .iter()+            .filter(|i| self.spec(&i.route).chain)+            .map(|i| LogFile {+                path: i.log_path(),+                created_at: Some((i.at_ms / 1000) as u64),+                // Monotone in invocation time, exactly like the launcher's own+                // yyyyMMddHHmmss. Only ever compared with other stamps.+                stamp: Some(i.at_ms as u64),+            })+            .collect();+        out.reverse();+        Ok(out)+    }++    fn helper_logs(&self) -> Result<Vec<LogFile>, String> {+        let dead = self.terminated_pids();+        let mut out: Vec<LogFile> = self+            .invocations()+            .iter()+            .filter(|i| self.alive(i, &dead) && self.reached(i, self.spec(&i.route).helper_after_ms))+            .map(|i| LogFile {+                path: i.helper_log_path(),+                created_at: Some((i.at_ms / 1000) as u64),+                stamp: Some(i.at_ms as u64),+            })+            .collect();+        out.reverse();+        Ok(out)+    }++    fn read_log(&self, path: &str) -> Result<String, String> {+        let seq: u64 = path+            .rsplit('/')+            .next()+            .and_then(|s| s.parse().ok())+            .ok_or_else(|| format!("not a simulated log path: {path}"))?;+        let inv = self+            .invocations()+            .into_iter()+            .find(|i| i.seq == seq)+            .ok_or_else(|| format!("no simulated launch {seq}"))?;+        let dead = self.terminated_pids();+        // The REAL shape: the header and `SecurityContext:` are written by the+        // first thread and always appear; `Run Begin` comes from a SECOND thread+        // about two seconds later, and on the failing route it never comes.+        // The launcher stamps the writing THREAD's id on every line, and the+        // simulator models a distinct thread per launcher process so a log can+        // be bound to the process that wrote it — see `writer_thread_of`.+        let tid = Self::thread_of(inv.launcher_pid());+        let mut text = format!(+            "00:00:00 [{tid}] info PackagingVersionShortName: V6R2026x.HF4.13\n\+             00:00:00 [{tid}] info AppName=SWXCSWK_AP\n\+             00:00:00 [{tid}] info SecurityContext: \n"+        );+        if self.alive(&inv, &dead) && self.reached(&inv, self.spec(&inv.route).run_begin_after_ms) {+            text.push_str(&format!(+                "00:00:02 [{}] info Run Begin\n\+                 00:00:02 [{}] info Located C:\\Program Files\\...\\sldworks.exe majorversion: 34\n",+                tid + 1,+                tid + 1+            ));+        }+        Ok(text)+    }++    fn terminate(&self, pid: u32, image: &str, created_at: Option<u64>) -> Result<(), String> {+        let census = self.processes()?;+        let Some(p) = census.iter().find(|p| p.pid == pid) else {+            return Err(format!("pid {pid} is not running"));+        };+        if !p.is(image) {+            return Err(format!("pid {pid} is {} now, not {image} — refusing", p.image));+        }+        if let Some(want) = created_at {+            if p.created_at != Some(want) {+                return Err(format!(+                    "pid {pid} started at {:?}, not {want} — a different process has this number now",+                    p.created_at+                ));+            }+        }+        let path = self.dir.join("terminated.jsonl");+        let mut text = std::fs::read_to_string(&path).unwrap_or_default();+        text.push_str(&json!({"pid": pid, "image": image, "atMs": epoch_ms() as u64}).to_string());+        text.push('\n');+        std::fs::write(&path, text).map_err(|e| e.to_string())+    }++    fn window_responding(&self, _hwnd: i64) -> Option<bool> {+        self.read_json("sldworks.json").get("responding").and_then(|v| v.as_bool()).or(Some(true))+    }++    fn main_window_of_pid(&self, _pid: u32) -> Option<i64> {+        self.read_json("sldworks.json").get("hwnd").and_then(|v| v.as_i64()).or(Some(4242))+    }++    /// The simulated desktop: `windows.json`, scoped to the pid when a row names+    /// one. `window-census-fails` makes the census UNREADABLE, which callers must+    /// treat as unknown rather than as "nothing on screen".+    fn windows_of_pid(&self, pid: u32) -> Result<Vec<WindowInfo>, String> {+        if self.dir.join("window-census-fails").exists() {+            return Err("simulated: the window census could not be taken".into());+        }+        let mut out: Vec<WindowInfo> = Vec::new();+        let read = |r: &Value| -> Option<WindowInfo> {+            Some(WindowInfo {+                hwnd: r.get("hwnd")?.as_i64()?,+                class_name: r.get("className").and_then(|x| x.as_str()).unwrap_or("").to_string(),+                title: r.get("title").and_then(|x| x.as_str()).unwrap_or("").to_string(),+                visible: r.get("visible").and_then(|x| x.as_bool()).unwrap_or(true),+            })+        };+        if let Some(rows) = self.read_json("windows.json").as_array() {+            for r in rows {+                let owner = r.get("pid").and_then(|x| x.as_u64()).map(|p| p as u32);+                if owner.is_some() && owner != Some(pid) {+                    continue;+                }+                if let Some(w) = read(r) {+                    out.push(w);+                }+            }+        }+        // THE 3DEXPERIENCE ID SIGN-IN, on whichever process the scenario says+        // owns it. `sign-in.json` is {"ownerPid":N,...} and the file is DELETED+        // to model the user answering it — which is what lets a test prove that+        // the paused deadlines resume.+        let si = self.read_json("sign-in.json");+        if si.is_object() {+            let owner = si.get("ownerPid").and_then(|x| x.as_u64()).map(|p| p as u32);+            // No owner named: it belongs to whichever launcher pid asks, which is+            // how a scenario says "our chain is showing it".+            if owner.is_none() || owner == Some(pid) {+                out.push(WindowInfo {+                    hwnd: si.get("hwnd").and_then(|x| x.as_i64()).unwrap_or(777001),+                    class_name: si+                        .get("className")+                        .and_then(|x| x.as_str())+                        .unwrap_or("DSYSysLoginPanelWebView2Class")+                        .to_string(),+                    title: si+                        .get("title")+                        .and_then(|x| x.as_str())+                        .unwrap_or("Login | 3DEXPERIENCE ID | Dassault Systemes")+                        .to_string(),+                    visible: true,+                });+            }+        }+        // A dialog a QUIT RUNG raised. The ladder must stop on it, and this is+        // how a scenario puts one on screen between rungs.+        let d = self.read_json("dialog-open.json");+        if d.is_object() {+            if let Some(w) = read(&d) {+                out.push(w);+            }+        }+        Ok(out)+    }++    fn thread_owner(&self, tid: u32) -> Option<u32> {+        let dead = self.terminated_pids();+        self.invocations()+            .into_iter()+            .find(|i| Self::thread_of(i.launcher_pid()) == tid || Self::thread_of(i.launcher_pid()) + 1 == tid)+            .map(|i| i.launcher_pid())+            .filter(|p| !dead.contains(p))+    }++    fn process_metrics(&self, _pid: u32) -> ProcMetrics {+        let s = self.read_json("sldworks.json");+        let private_mb = s.get("privateMB").and_then(|v| v.as_u64()).or(Some(800));+        // `cpuSecondsPerRead` advances the simulated CPU clock on every read, so+        // a scenario can be "burning CPU" (>0) or "dead" (0).+        let step = s.get("cpuSecondsPerRead").and_then(|v| v.as_f64()).unwrap_or(0.0);+        let reads = {+            let f = self.dir.join("cpu-reads");+            let n = std::fs::read_to_string(&f).ok().and_then(|t| t.trim().parse::<u64>().ok()).unwrap_or(0);+            let _ = std::fs::write(&f, (n + 1).to_string());+            n+        };+        ProcMetrics {+            private_mb,+            working_set_mb: s+                .get("workingSetMB")+                .and_then(|v| v.as_u64())+                .or_else(|| private_mb.map(|p| p * 3 / 4)),+            cpu_seconds: s+                .get("cpuSeconds")+                .and_then(|v| v.as_f64())+                .or(Some(100.0))+                .map(|base| base + step * reads as f64),+            handles: s.get("handles").and_then(|v| v.as_u64()).map(|h| h as u32).or(Some(3000)),+        }+    }++    fn kind(&self) -> &'static str {+        "simulated"+    }+}++// ── the real one ────────────────────────────────────────────────────────────++#[cfg(windows)]+mod win {+    use super::*;+    use windows::core::PCWSTR;+    use windows::core::BOOL;+    use windows::Win32::Foundation::{CloseHandle, FILETIME, HANDLE, HWND, LPARAM};+    use windows::Win32::System::Diagnostics::ToolHelp::{+        CreateToolhelp32Snapshot, Process32FirstW, Process32NextW, PROCESSENTRY32W,+        TH32CS_SNAPPROCESS,+    };+    use windows::Win32::System::ProcessStatus::{+        K32GetProcessMemoryInfo, PROCESS_MEMORY_COUNTERS, PROCESS_MEMORY_COUNTERS_EX,+    };+    use windows::Win32::System::Threading::{+        GetProcessHandleCount, GetProcessTimes, OpenProcess, TerminateProcess,+        PROCESS_QUERY_LIMITED_INFORMATION, PROCESS_TERMINATE,+    };+    use windows::Win32::UI::WindowsAndMessaging::{+        EnumWindows, GetWindowLongW, GetWindowThreadProcessId, IsHungAppWindow, IsWindowVisible,+        GWL_STYLE, WS_VISIBLE,+    };++    pub struct WindowsOs;++    /// Where the 3DEXPERIENCE launcher and its helper write their logs. These+    /// are the two files that say whether a launch is PROGRESSING or has stalled+    /// at `SecurityContext:` — the single most useful signal on the machine, and+    /// the reason this bridge no longer has to guess.+    fn log_dir(sub: &str) -> Option<std::path::PathBuf> {+        let appdata = std::env::var("APPDATA").ok().filter(|s| !s.is_empty())?;+        Some(std::path::Path::new(&appdata).join("DassaultSystemes").join(sub))+    }++    fn logs_in(sub: &str) -> Result<Vec<LogFile>, String> {+        let dir = log_dir(sub).ok_or("APPDATA is not set")?;+        let entries = std::fs::read_dir(&dir)+            .map_err(|e| format!("cannot read {}: {e}", dir.display()))?;+        let mut out = Vec::new();+        for e in entries.flatten() {+            let name = e.file_name().to_string_lossy().to_string();+            // `*_dslcc.log` is the licence client's own trace, not the launcher's+            // progress log — it is large, noisy, and says nothing about Run Begin.+            if !name.to_ascii_lowercase().ends_with(".log") || name.contains("_dslcc") {+                continue;+            }+            // CREATED, falling back to MODIFIED — and they are not the same+            // fact. The launcher appends to its log for as long as it runs, so+            // `modified()` on a live log is "a moment ago" whatever the launch+            // is doing. The fallback is only reached on a filesystem that does+            // not record creation times (some network shares), where it is the+            // only thing available; on NTFS `created()` always answers, and the+            // filename stamp corroborates it either way.+            let created = e+                .metadata()+                .ok()+                .and_then(|m| m.created().or_else(|_| m.modified()).ok())+                .and_then(|t| t.duration_since(UNIX_EPOCH).ok())+                .map(|d| d.as_secs());+            out.push(LogFile {+                path: e.path().to_string_lossy().to_string(),+                created_at: created,+                stamp: stamp_of(&name),+            });+        }+        // Newest first, by the launcher's own stamp where it has one.+        out.sort_by(|a, b| b.stamp.cmp(&a.stamp).then_with(|| b.created_at.cmp(&a.created_at)));+        Ok(out)+    }++    fn filetime_to_epoch(ft: FILETIME) -> Option<u64> {+        let ticks = ((ft.dwHighDateTime as u64) << 32) | ft.dwLowDateTime as u64;+        if ticks == 0 {+            return None;+        }+        // FILETIME counts 100ns ticks from 1601-01-01; 11644473600 seconds to epoch.+        Some((ticks / 10_000_000).saturating_sub(11_644_473_600))+    }++    /// The creation time of an ALREADY-OPEN handle. This is the form that+    /// closes the kill-path TOCTOU: a handle refers to one particular process+    /// object for as long as it is open, so a check made through it cannot be+    /// answered about a different process that took the same pid.+    unsafe fn created_at_of_handle(h: HANDLE) -> Option<u64> {+        let mut created = FILETIME::default();+        let (mut exit, mut kernel, mut user) =+            (FILETIME::default(), FILETIME::default(), FILETIME::default());+        if unsafe { GetProcessTimes(h, &mut created, &mut exit, &mut kernel, &mut user) }.is_ok() {+            filetime_to_epoch(created)+        } else {+            None+        }+    }++    fn created_at_of(pid: u32) -> Option<u64> {+        unsafe {+            let h = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, false, pid).ok()?;+            let out = created_at_of_handle(h);+            let _ = CloseHandle(h);+            out+        }+    }++    /// The EnumWindows callback has nowhere to put its answer but a static, so+    /// only ONE enumeration may be in flight at a time — the supervisor thread+    /// and an HTTP worker answering `swx_status` can both ask at once, and two+    /// overlapping searches would hand one of them the OTHER process's window.+    /// An hwnd attributed to the wrong process is then fed to IsHungAppWindow,+    /// which is a wrong answer to the one question that must not be wrong.+    static ENUM_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());+    /// (pid asked about, hwnds found) for the window census. Serialised by+    /// `ENUM_LOCK` for the same reason `FOUND_HWND` is.+    static CENSUS: std::sync::Mutex<(u32, Vec<i64>)> = std::sync::Mutex::new((0, Vec::new()));+    static FOUND_HWND: std::sync::Mutex<(u32, i64)> = std::sync::Mutex::new((0, 0));++    unsafe extern "system" fn census_proc(hwnd: HWND, _l: LPARAM) -> BOOL {+        let mut guard = match CENSUS.lock() {+            Ok(g) => g,+            Err(e) => e.into_inner(),+        };+        let mut pid = 0u32;+        GetWindowThreadProcessId(hwnd, Some(&mut pid));+        if pid == guard.0 {+            guard.1.push(hwnd.0 as i64);+        }+        BOOL(1)+    }++    unsafe extern "system" fn enum_proc(hwnd: HWND, _l: LPARAM) -> BOOL {+        let mut guard = match FOUND_HWND.lock() {+            Ok(g) => g,+            Err(e) => e.into_inner(),+        };+        if guard.1 != 0 {+            return BOOL(1);+        }+        let mut pid = 0u32;+        GetWindowThreadProcessId(hwnd, Some(&mut pid));+        if pid == guard.0 && IsWindowVisible(hwnd).as_bool() {+            // Only a real top-level application window — a tool window with no+            // WS_VISIBLE style is not what IsHungAppWindow should be asked about.+            if GetWindowLongW(hwnd, GWL_STYLE) as u32 & WS_VISIBLE.0 != 0 {+                guard.1 = hwnd.0 as i64;+            }+        }+        BOOL(1)+    }++    impl LaunchOs for WindowsOs {+        fn processes(&self) -> Result<Vec<ProcInfo>, String> {+            unsafe {+                let snap = CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0)+                    .map_err(|e| format!("CreateToolhelp32Snapshot failed: {e}"))?;+                let mut entry = PROCESSENTRY32W {+                    dwSize: std::mem::size_of::<PROCESSENTRY32W>() as u32,+                    ..Default::default()+                };+                let mut out = Vec::new();+                if Process32FirstW(snap, &mut entry).is_ok() {+                    loop {+                        let len =+                            entry.szExeFile.iter().position(|c| *c == 0).unwrap_or(entry.szExeFile.len());+                        let image = String::from_utf16_lossy(&entry.szExeFile[..len]);+                        if WATCHED_IMAGES.iter().any(|w| w.eq_ignore_ascii_case(&image)) {+                            let pid = entry.th32ProcessID;+                            out.push(ProcInfo {+                                pid,+                                image,+                                created_at: created_at_of(pid),+                                ppid: Some(entry.th32ParentProcessID),+                            });+                        }+                        if Process32NextW(snap, &mut entry).is_err() {+                            break;+                        }+                    }+                }+                let _ = CloseHandle(snap);+                Ok(out)+            }+        }++        fn launcher_logs(&self) -> Result<Vec<LogFile>, String> {+            logs_in("SWXDesktopLauncher")+        }++        fn helper_logs(&self) -> Result<Vec<LogFile>, String> {+            logs_in("SWXDesktopHelper")+        }++        fn read_log(&self, path: &str) -> Result<String, String> {+            // The launcher holds its log open; a plain read still works, but a+            // huge `_dslcc` sibling could be megabytes, so cap what we take.+            let bytes = std::fs::read(path).map_err(|e| format!("cannot read {path}: {e}"))?;+            const CAP: usize = 256 * 1024;+            let slice = if bytes.len() > CAP { &bytes[..CAP] } else { &bytes[..] };+            Ok(String::from_utf8_lossy(slice).to_string())+        }++        /// Terminate ONE pid — image AND creation time re-checked ON THE OPEN+        /// HANDLE, immediately before the kill.+        ///+        /// A pid is reusable, so a census taken even milliseconds earlier is a+        /// statement about a process that may already be gone. The handle is+        /// the only thing that pins the identity: open first, verify through+        /// the handle, then terminate through that same handle. `PROCESS_TERMINATE`+        /// alone cannot answer GetProcessTimes, so the handle is opened with+        /// QUERY_LIMITED_INFORMATION as well.+        fn terminate(&self, pid: u32, image: &str, created_at: Option<u64>) -> Result<(), String> {+            let census = self.processes()?;+            let Some(p) = census.iter().find(|p| p.pid == pid) else {+                return Err(format!("pid {pid} is no longer running"));+            };+            if !p.is(image) {+                return Err(format!("pid {pid} is {} now, not {image} — refusing to terminate it", p.image));+            }+            let Some(want) = created_at else {+                return Err(format!(+                    "pid {pid} has no recorded creation time, so it cannot be proven to be the \+                     process this bridge started — refusing to terminate it"+                ));+            };+            unsafe {+                let h: HANDLE =+                    OpenProcess(PROCESS_TERMINATE | PROCESS_QUERY_LIMITED_INFORMATION, false, pid)+                        .map_err(|e| format!("OpenProcess({pid}) failed: {e}"))?;+                let live = created_at_of_handle(h);+                if live != Some(want) {+                    let _ = CloseHandle(h);+                    return Err(format!(+                        "pid {pid} started at {live:?}, not {want}: between the census and the \+                         kill this number was reused — refusing to terminate it"+                    ));+                }+                let r = TerminateProcess(h, 1);+                let _ = CloseHandle(h);+                r.map_err(|e| format!("TerminateProcess({pid}) failed: {e}"))+            }+        }++        /// Liveness WITHOUT a full census — used to ask whether the bridge that+        /// recorded a launch attempt is still around. A pid we cannot open at+        /// all is reported as unknown, not as dead.+        fn pid_alive(&self, pid: u32) -> Option<bool> {+            unsafe {+                match OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, false, pid) {+                    Ok(h) => {+                        let alive = created_at_of_handle(h).is_some();+                        let _ = CloseHandle(h);+                        Some(alive)+                    }+                    // ERROR_INVALID_PARAMETER is "no such process"; anything+                    // else (access denied on a service, say) is UNKNOWN.+                    Err(e) if e.code().0 as u32 == 0x8007_0057 => Some(false),+                    Err(_) => None,+                }+            }+        }++        /// The SAME clock the process creation times come from, converted the+        /// SAME way — so "created at or after our invoke" is a comparison+        /// between two readings of one clock, and needs no slack to absorb a+        /// conversion difference.+        fn now(&self) -> u64 {+            use windows::Win32::System::SystemInformation::GetSystemTimeAsFileTime;+            filetime_to_epoch(unsafe { GetSystemTimeAsFileTime() }).unwrap_or_else(epoch_secs)+        }++        fn window_responding(&self, hwnd: i64) -> Option<bool> {+            if hwnd == 0 {+                return None;+            }+            unsafe { Some(!IsHungAppWindow(HWND(hwnd as *mut std::ffi::c_void)).as_bool()) }+        }++        /// Walk the thread table for the owner of one thread id. The launcher+        /// stamps that id on every line it writes, so this is what turns "a log+        /// appeared" into "OUR launcher wrote this log".+        fn thread_owner(&self, tid: u32) -> Option<u32> {+            use windows::Win32::System::Diagnostics::ToolHelp::{+                Thread32First, Thread32Next, TH32CS_SNAPTHREAD, THREADENTRY32,+            };+            unsafe {+                let snap = CreateToolhelp32Snapshot(TH32CS_SNAPTHREAD, 0).ok()?;+                let mut entry = THREADENTRY32 {+                    dwSize: std::mem::size_of::<THREADENTRY32>() as u32,+                    ..Default::default()+                };+                let mut owner = None;+                if Thread32First(snap, &mut entry).is_ok() {+                    loop {+                        if entry.th32ThreadID == tid {+                            owner = Some(entry.th32OwnerProcessID);+                            break;+                        }+                        if Thread32Next(snap, &mut entry).is_err() {+                            break;+                        }+                    }+                }+                let _ = CloseHandle(snap);+                owner+            }+        }++        /// Every top-level window owned by `pid`, with its class — the quit+        /// ladder's P3 instrument, and readable with no ab and no COM.+        fn windows_of_pid(&self, pid: u32) -> Result<Vec<WindowInfo>, String> {+            use windows::Win32::UI::WindowsAndMessaging::{GetClassNameW, GetWindowTextW};+            let _serialised = ENUM_LOCK.lock().unwrap_or_else(|e| e.into_inner());+            *CENSUS.lock().unwrap_or_else(|e| e.into_inner()) = (pid, Vec::new());+            unsafe {+                let _ = EnumWindows(Some(census_proc), LPARAM(0));+            }+            let hwnds = CENSUS.lock().unwrap_or_else(|e| e.into_inner()).1.clone();+            let mut out = Vec::new();+            for h in hwnds {+                let hwnd = HWND(h as *mut std::ffi::c_void);+                let mut class = [0u16; 256];+                let mut title = [0u16; 512];+                let (cl, tl) = unsafe {+                    (GetClassNameW(hwnd, &mut class), GetWindowTextW(hwnd, &mut title))+                };+                out.push(WindowInfo {+                    hwnd: h,+                    class_name: String::from_utf16_lossy(&class[..cl.max(0) as usize]),+                    title: String::from_utf16_lossy(&title[..tl.max(0) as usize]),+                    visible: unsafe { IsWindowVisible(hwnd) }.as_bool(),+                });+            }+            Ok(out)+        }++        fn main_window_of_pid(&self, pid: u32) -> Option<i64> {+            let _serialised = ENUM_LOCK.lock().unwrap_or_else(|e| e.into_inner());+            let mut guard = FOUND_HWND.lock().unwrap_or_else(|e| e.into_inner());+            *guard = (pid, 0);+            drop(guard);+            unsafe {+                let _ = EnumWindows(Some(enum_proc), LPARAM(0));+            }+            let found = FOUND_HWND.lock().unwrap_or_else(|e| e.into_inner()).1;+            (found != 0).then_some(found)+        }++        fn process_metrics(&self, pid: u32) -> ProcMetrics {+            unsafe {+                let Ok(h) = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, false, pid) else {+                    return ProcMetrics::default();+                };+                let mut counters = PROCESS_MEMORY_COUNTERS_EX::default();+                let got = K32GetProcessMemoryInfo(+                    h,+                    &mut counters as *mut _ as *mut PROCESS_MEMORY_COUNTERS,+                    std::mem::size_of::<PROCESS_MEMORY_COUNTERS_EX>() as u32,+                )+                .as_bool();+                let mut handles = 0u32;+                let got_handles = GetProcessHandleCount(h, &mut handles).is_ok();+                // Kernel + user time, in 100ns ticks. The absolute value is+                // meaningless; the DELTA across two reads is the busy-vs-dead+                // signal.+                let mut cpu = None;+                {+                    let (mut c, mut e, mut k, mut u) = (+                        FILETIME::default(),+                        FILETIME::default(),+                        FILETIME::default(),+                        FILETIME::default(),+                    );+                    if GetProcessTimes(h, &mut c, &mut e, &mut k, &mut u).is_ok() {+                        let ticks = |f: FILETIME| {+                            ((f.dwHighDateTime as u64) << 32) | f.dwLowDateTime as u64+                        };+                        cpu = Some((ticks(k) + ticks(u)) as f64 / 10_000_000.0);+                    }+                }+                let _ = CloseHandle(h);+                ProcMetrics {+                    private_mb: got.then(|| (counters.PrivateUsage as u64) / (1024 * 1024)),+                    working_set_mb: got.then(|| (counters.WorkingSetSize as u64) / (1024 * 1024)),+                    cpu_seconds: cpu,+                    handles: got_handles.then_some(handles),+                }+            }+        }++        fn kind(&self) -> &'static str {+            "windows"+        }+    }++    /// Run a `.lnk` through `ShellExecuteExW` with an EXPLICIT NORMAL show+    /// state — and BRING BACK THE IDENTITY OF WHAT IT STARTED.+    ///+    /// `SEE_MASK_NOCLOSEPROCESS` makes the shell hand us `hProcess` for the+    /// process it created. `GetProcessId` + `GetProcessTimes` on that handle+    /// give a (pid, creation time) pair that came from the invoke ITSELF, not+    /// from a census we searched afterwards hoping to recognise our own work.+    /// That is the only attribution this bridge accepts as authority to+    /// terminate anything — see `launch::AttributionRule`.+    ///+    /// Called from the com host, whose thread is STA-initialised: the shell's+    /// link resolver needs an apartment, and the HTTP workers have none.+    pub fn shell_execute_lnk(path: &str) -> Result<Option<(u32, Option<u64>)>, String> {+        use windows::Win32::System::Threading::GetProcessId;+        use windows::Win32::UI::Shell::{+            ShellExecuteExW, SEE_MASK_FLAG_NO_UI, SEE_MASK_NOASYNC, SEE_MASK_NOCLOSEPROCESS,+            SHELLEXECUTEINFOW,+        };+        use windows::Win32::UI::WindowsAndMessaging::SW_SHOWNORMAL;+        let wide: Vec<u16> = path.encode_utf16().chain(std::iter::once(0)).collect();+        let mut info = SHELLEXECUTEINFOW {+            cbSize: std::mem::size_of::<SHELLEXECUTEINFOW>() as u32,+            fMask: SEE_MASK_FLAG_NO_UI | SEE_MASK_NOASYNC | SEE_MASK_NOCLOSEPROCESS,+            lpFile: PCWSTR(wide.as_ptr()),+            nShow: SW_SHOWNORMAL.0,+            ..Default::default()+        };+        unsafe { ShellExecuteExW(&mut info) }.map_err(|e| format!("ShellExecuteExW failed: {e}"))?;+        if info.hProcess.is_invalid() {+            // The shell handed the link to an ALREADY-RUNNING process (DDE) or+            // declined to say. No handle, no attribution — and therefore, later,+            // no kill.+            return Ok(None);+        }+        let pid = unsafe { GetProcessId(info.hProcess) };+        let created = unsafe { created_at_of_handle(info.hProcess) };+        let _ = unsafe { CloseHandle(info.hProcess) };+        Ok((pid != 0).then_some((pid, created)))+    }++    /// `Start-Process -PassThru` and READ THE PID IT PRINTS.+    ///+    /// Waits on the PowerShell child (which returns as soon as it has started+    /// the target, not when the target exits), so a non-zero exit or anything+    /// on stderr is reported as "this route did not start anything" rather than+    /// being mistaken for a stall in a launcher that never ran.+    pub fn powershell_start_lnk(path: &str) -> Result<Option<(u32, Option<u64>)>, String> {+        use std::os::windows::process::CommandExt;+        const CREATE_NO_WINDOW: u32 = 0x0800_0000;+        let quoted = path.replace('\'', "''");+        let out = std::process::Command::new("powershell.exe")+            .args([+                "-NoProfile",+                "-NonInteractive",+                "-Command",+                &format!("(Start-Process -FilePath '{quoted}' -PassThru).Id"),+            ])+            .creation_flags(CREATE_NO_WINDOW)+            .output()+            .map_err(|e| format!("could not run powershell: {e}"))?;+        if !out.status.success() {+            return Err(format!(+                "powershell exited {} — the route started nothing. stderr: {}",+                out.status.code().unwrap_or(-1),+                String::from_utf8_lossy(&out.stderr).trim()+            ));+        }+        let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();+        if !stderr.is_empty() {+            return Err(format!("powershell wrote to stderr, so the route is not trusted to have started anything: {stderr}"));+        }+        let pid: u32 = match String::from_utf8_lossy(&out.stdout).trim().parse() {+            Ok(p) => p,+            Err(_) => return Ok(None), // it ran, but would not say what it started+        };+        Ok(Some((pid, created_at_of(pid))))+    }+}++#[cfg(windows)]+pub use win::{powershell_start_lnk, shell_execute_lnk};++#[cfg(test)]+mod tests {+    use super::*;++    fn fake(tag: &str) -> (std::path::PathBuf, FakeOs) {+        let dir = std::env::temp_dir().join(format!("swx-fakeos-{}-{tag}", std::process::id()));+        let _ = std::fs::remove_dir_all(&dir);+        std::fs::create_dir_all(&dir).unwrap();+        (dir.clone(), FakeOs { dir })+    }++    #[test]+    fn a_failed_census_is_an_error_never_an_empty_list() {+        let (dir, os) = fake("census");+        std::fs::write(dir.join("census-fails"), "").unwrap();+        assert!(os.processes().is_err(), "'I could not look' must not read as 'nothing is running'");+        let _ = std::fs::remove_dir_all(&dir);+    }++    #[test]+    fn the_simulator_models_the_stall_and_the_working_route() {+        let (dir, os) = fake("stall");+        std::fs::write(+            dir.join("routes.json"),+            r#"{"cmdStart":{"chain":true},+                "explorer":{"chain":true,"runBeginAfterMs":0,"sldworksAfterMs":0,"attachAfterMs":0}}"#,+        )+        .unwrap();+        FakeOs::record_invoke(&dir, "cmdStart", "x.lnk");+        let procs = os.processes().unwrap();+        assert_eq!(procs.len(), 2, "the stalled route still starts a chain: {procs:?}");+        let log = os.read_log(&os.launcher_logs().unwrap()[0].path).unwrap();+        assert!(log.contains("SecurityContext:"));+        assert!(!log.contains("Run Begin"), "the stall is the ABSENCE of Run Begin");+        assert!(!FakeOs::attachable(&dir));++        FakeOs::record_invoke(&dir, "explorer", "x.lnk");+        let log2 = os.read_log(&os.launcher_logs().unwrap()[0].path).unwrap();+        assert!(log2.contains("Run Begin"), "the working route reaches Run Begin");+        assert!(FakeOs::attachable(&dir));+        assert!(os.processes().unwrap().iter().any(|p| p.is("SLDWORKS.exe")));+        let _ = std::fs::remove_dir_all(&dir);+    }++    #[test]+    fn terminate_refuses_a_pid_that_is_not_the_image_it_was_asked_for() {+        let (dir, os) = fake("terminate");+        std::fs::write(dir.join("routes.json"), r#"{"cmdStart":{"chain":true}}"#).unwrap();+        let seq = FakeOs::record_invoke(&dir, "cmdStart", "x.lnk");+        let inv = os.invocations().into_iter().find(|i| i.seq == seq).unwrap();+        let live = os.processes().unwrap();+        let cat = live.iter().find(|p| p.pid == inv.catstart_pid()).unwrap().clone();+        // The wrong IMAGE for that pid is refused...+        assert!(os.terminate(cat.pid, "SWXDesktopLauncher.exe", cat.created_at).is_err());+        // ...and so is the right image with the WRONG CREATION TIME, which is+        // what a reused pid looks like.+        assert!(+            os.terminate(cat.pid, "CATSTART.exe", Some(1)).is_err(),+            "a pid whose creation time does not match is a different process now"+        );+        assert!(os.terminate(cat.pid, "CATSTART.exe", cat.created_at).is_ok());+        assert!(+            !os.processes().unwrap().iter().any(|p| p.pid == inv.catstart_pid()),+            "a terminated process leaves the census"+        );+        let _ = std::fs::remove_dir_all(&dir);+    }+}