Altium - the Altium Bridge

@@ -0,0 +1,120 @@+# Publishing altium-bridge++How a build of this bridge reaches users. The tool is `scripts/release.py`; the developer recipe+with the wiki details is `publish-skills/altium-bridge-publish/SKILL.md`. Page: `adom/altium-bridge`.++## Two tiers++Every publish goes to the INSIDERS tier. The PUBLIC tier moves only when a human says so.++| | Insiders | Public |+|---|---|---|+| Manifest | `altium-bridge/version.json` on the `adom/insiders` page | `adom-bridge-altium-manifest.json` on `adom/altium-bridge` |+| Who follows it | desktops whose login can read the insiders page (`insidersManifestUrl` in `src/bridge.json`) | everyone else |+| Moved by | `--publish` | `--promote` / `--rollback` only |++The release zip itself lives on the `adom/altium-bridge` releases for both tiers; the tiers differ+only in which manifest points at which version.++```bash+python3 scripts/release.py                      # lint + cargo test + build, zip into dist/. Publishes nothing.+python3 scripts/release.py --publish "<one sentence for the release log>"+python3 scripts/release.py --promote <ver>  --attest "<the human's exact words>" --by "<name>"+python3 scripts/release.py --rollback <ver> --attest "<the human's exact words>" --by "<name>"+```++`--publish` does, in order: the lints below, `cargo test`, the release build, the zip, the release+and its asset on `adom/altium-bridge`, the insiders manifest plus a release-log entry on+`adom/insiders` (a copy of the manifest is archived in `scripts/releases/<ver>.json`), the version+stamps to the page repo, the skills pkg (`adom-wiki pkg publish --org adom`), and a final check+that the insiders manifest is blocked for anonymous readers and serves the new version to a+signed-in one. It never touches the public manifest.++`--promote <ver>` needs the archived manifest for that version, re-downloads the zip and compares+its sha256 with the record, then writes the public manifest with `promotion_attestation`,+`promoted_by` and `promoted_at`, pushes it, and marks the release-log entry.++`--rollback <ver>` re-points the public manifest at an older archived build the same way, and+records `rollback_attestation`, `rolled_back_by`, `rolled_back_at`.++### The promotion rule++An AI never promotes on its own judgment. `--attest` carries the words the human actually said,+and `--by` names that human. The script refuses an attestation shorter than 8 characters or a+placeholder ("ok", "yes", "promote", "ship it", "go", "approved", "test"), and refuses a missing+`--by`. The words are stored in the public manifest, so do not paraphrase them.++## Versions++`src/bridge.json` `version` is the single source. These must carry the same number:++| File | Checked by `release.py` |+|---|---|+| `src/BRIDGE_VERSION` | yes |+| `bridge-rs/src/main.rs` (`BRIDGE_VERSION` const) | yes |+| `package.json` | yes |+| `bridge-rs/Cargo.toml` | no, bump by hand |+| `page.json` | no, bump by hand |++One plain semver per build, the same in both tiers. Add the `CHANGELOG.md` entry in the same change.++## What the release script refuses++Every mode runs these first, and any hit stops the build:++- **Version drift**: a stamp in the checked files above that differs from `src/bridge.json`, or an+  `insidersManifestUrl` in `src/bridge.json` that is not the insiders manifest URL.+- **Verbs declared vs dispatchable**: `verbs[]` in `src/bridge.json` must equal the `KNOWN` list in+  `bridge-rs/src/verbs.rs`. Both directions are printed: declared but not dispatchable, and+  dispatchable but not declared.+- **`ENGINE_HALTING` identifiers** in `src/agent/AdomAgent.pas.tmpl`: identifiers measured to halt+  Altium's DelphiScript engine (`.ImplementationCount`, `.Implementation[`, `BottomXSize`,+  `MidXSize`, `eProcessFreePrimitives`, `RunProcessWithParameters`, `.SuperClass :=`,+  `CreateOleObject`). Comments and string literals are ignored. When a new one is found, add it to+  the list in `release.py` and to `dev-skills/altium-bridge-dev`. One case the regex cannot see:+  `GroupIterator_Create` on a board halts but is correct on a component, so review those by hand.+- **Raw `StrToFloat(` / `StrToInt(`** anywhere in the agent template outside the `AdomFloat` /+  `AdomInt` helpers. A raw conversion raises on malformed input, and a raise is an Error box on+  the user's screen.++Then `cargo test` must pass before the release build, and every file in the zip must exist.++Not linted by the script: `verbs[]` entries must be plain strings, never objects (see section 0 of+the publish skill for the one-line check).++## Source changes need their own push++`--publish` pushes only `CHANGELOG.md`, `src/bridge.json`, `src/BRIDGE_VERSION` and `package.json`+to the page repo. Changed source, skills or docs do not travel with it. Push them separately:++```bash+adom-wiki repo push adom/altium-bridge --files <changed files> -m "v<ver>: <what changed>"+```++A docs-only change (README, images) needs no version bump, only this push.++## Before promoting to public++All of these, on the version being promoted:++1. The verb battery (`dev-skills/altium-bridge-test/run_verb_tests.py`) is green, meaning exit+   code 0 with no FAIL and no uncovered verb, on at least two Altium builds. Altium Designer 26.x+   and Altium Designer Develop behave differently on script errors.+2. It is green on a machine that is not the one the change was written on.+3. `altium_selftest_script_error` answers `netWorks: true` on each of those builds. `outcome` may+   be `halted_and_recovered` or `contained_by_agent`; both are passes.+4. Ideally one run on a from-scratch Windows install, since the battery assumes Altium is present.+5. A human has asked for the promotion, and their exact words are in hand.++Never run the battery on a machine somebody is using. It raises Altium and flashes an error box.+The runner refuses unless the target has had no keyboard or mouse input for 180 s (`--min-idle`);+pass `--user-is-away` only when the human has told you the machine is free. Do not run it on two+machines of the same Altium 365 workspace at once, and let it close Altium at the end so the+Author seat is released.++## Verify after a publish++- The script's last lines: `SHIPPED <ver> to INSIDERS; public tier still serves <old>`.+- `adom-wiki release list` shows the release with its zip attached.+- After a promote: `adom-wiki repo show adom/altium-bridge adom-bridge-altium-manifest.json`+  shows the promoted version and the sha256 of the archived manifest.

@@ -15,6 +15,7 @@ //! * The bootstrap activates Altium. Capture the user's foreground window first and hand it back. use crate::ab; use crate::agent;+use crate::instance; use serde_json::{json, Value}; use std::path::PathBuf; use std::time::{Duration, Instant};@@ -560,6 +561,16 @@ pub fn stop_all_live() -> Value { /// Un-halt the script engine: press OK on the script Error modal, stop the editor's script, /// clear stale files. Costs the user a modal, so only on a real halt. pub fn recover(reason: &str) -> Value {+    recover_impl(reason, true)+}++/// For altium_close: free the engine but do NOT start a new agent loop (a close must never go out+/// over a live loop, adom/altium-bridge#6).+pub fn recover_without_restart(reason: &str) -> Value {+    recover_impl(reason, false)+}++fn recover_impl(reason: &str, verify_by_restart: bool) -> Value {     let mut steps: Vec<Value> = vec![json!({"reason": reason})];     // 1. the script Error modal, if any     for d in crate::dialogs::scan() {@@ -569,7 +580,40 @@ pub fn recover(reason: &str) -> Value {             steps.push(json!({"dialog": title, "pressed": "OK"}));         }     }-    // 2. tell the editor to stop whatever unit it is holding (raises the busy notice → reap it)+    // 2. tell the editor to stop whatever unit it is holding (raises the busy notice → reap it).+    //    EditScript:Stop ONLY acts when a SCRIPT DOCUMENT is the active document. With a board or a+    //    library in front it is a silent no-op: recover answered success while the script stayed on+    //    its breakpoint, the self-test reported halted_and_recovered for an engine that was never+    //    freed, and Altium then refused to close (measured on AD 26.10.1, 2026-09-21; it had only+    //    ever worked because the script happened to be in front). So: bring every agent script this+    //    workspace holds to the front, one at a time, and stop it there.+    let scripts: Vec<std::path::PathBuf> = std::fs::read_dir(agent::workspace_dir()).map(|rd| rd.filter_map(|e| e.ok()).map(|e| e.path())+        .filter(|p| p.file_name().map(|n| { let n = n.to_string_lossy().to_string(); n.starts_with("AdomAgent_") && n.ends_with(".pas") }).unwrap_or(false))+        .collect()).unwrap_or_default();+    let instances_before = instance::instances().len();+    if let Some(exe) = x2_exe() {+        for sc in &scripts {+            let arg = format!("-RWorkspaceManager:OpenObject(ObjectKind=Document|FileName=\"{}\")", sc.to_string_lossy());+            if let Ok(mut child) = spawn_helper(&exe, &arg) {+                let _ = wait_helper(&mut child, Duration::from_secs(8));+                let _ = child.kill();+                let _ = child.wait();+            }+            std::thread::sleep(Duration::from_millis(600));+            if let Ok(mut child) = spawn_helper(&exe, "-REditScript:Stop") {+                let _ = wait_helper(&mut child, Duration::from_secs(8));+                let _ = child.kill();+                let _ = child.wait();+            }+            steps.push(json!({"scriptActivatedAndStopped": sc.file_name().map(|n| n.to_string_lossy().to_string())}));+        }+    }+    instance::invalidate_snapshot();+    let instances_after = instance::instances().len();+    if instances_after > instances_before {+        // A -R hand-off that does not reach the running instance makes X2 start a NEW Altium.+        steps.push(json!({"warning": "a helper started a second Altium instance instead of forwarding", "instancesBefore": instances_before, "instancesAfter": instances_after}));+    }     if let Some(exe) = x2_exe() {         match spawn_helper(&exe, "-REditScript:Stop") {             Ok(mut child) => {@@ -590,8 +634,20 @@ pub fn recover(reason: &str) -> Value {     for n in ["hb.txt", "stop", "request.txt", "request.payload", "request.txt.tmp"] {         let _ = std::fs::remove_file(ws.join(n));     }-    json!({"success": true, "steps": steps,-           "_hint": "the engine should be free now — agent_start. If a modal is still up, it is NOT ours: read it."})+    // VERIFY, never assume: the engine is free only if a fresh agent loop can actually start.+    instance::invalidate_snapshot();+    let mut verified = Value::Null;+    if verify_by_restart && crate::health::is_running() && instances_after <= 1 {+        let started = start(Duration::from_secs(40));+        let ok = started.get("success").and_then(|b| b.as_bool()) == Some(true) && agent::is_alive();+        verified = json!(ok);+        steps.push(json!({"verifiedByRestartingTheAgent": ok}));+    }+    let freed = verified.as_bool().unwrap_or(true);+    json!({"success": freed, "engineFree": verified, "steps": steps,+           "errorCode": if freed { Value::Null } else { json!("engine_still_parked") },+           "_hint": if freed { "The script engine is free and a fresh agent loop is running (verified by starting it)." }+                    else { "The engine is STILL parked: a new agent loop could not start. Look at the screen (desktop_screenshot_screen): a script document must be the active document for Altium to accept the stop. Click the agent script's tab in Altium, then altium_agent_recover again. Do not altium_close yet: Altium refuses to close over a parked script." }}) }  // ---- application lifecycle ---------------------------------------------------