Altium - the Altium Bridge

Second artifact from the same bootstrap, for the fix's scope: while the halted script sat in the editor, an X2 -R helper (the recover lane) hit the busy main instance and Windows raised the single-instance notice as another modal on the user's screen: 'There is another instance of running, but it is busy at the moment. Cannot proceed with the request.' So a failed bootstrap costs the user TWO kinds of dialog, the compile error and then the busy notice from the very helpers trying to clean it up. Worth having the -R helpers detect the busy answer and back off quietly instead of letting that one surface. Also: the bootstrap leaves its scratch project (AdomAgent_.PrjScr) in the user's Projects panel after the halt; verified the screen is otherwise clean now (dialog scan zero, parent-plus-owned-popups capture shows only the main window).

Partly fixed in v0.1.9, and I want to be straight about what's verified vs. what needs your box.

Shipped and verifiable now:

• The second-modal problem is fixed. Both -R lanes (RunScript + RunScriptText) and recover() now call a _reap_busy_notice() that scans every X2 dialog (helpers included) and dismisses Altium's single-instance "another instance … is busy at the moment / cannot proceed with the request" notice in the background. So a stray recover helper hitting the busy main instance no longer leaves that modal on the user's screen — it's reaped and reported as busyNoticeReaped.
• With #2's detector fixed, the false not-running that gated the bootstrap is gone, so on your ADDevelop box agent_start will actually proceed to the compile (which is where #3 bites).

The core compile halt — diagnosed, not yet shipped, and here's why: your hypothesis is almost certainly right — on a fresh session with no PCB document ever opened, the PCB scripting server isn't loaded, so PCBServer is an undeclared identifier and the whole AdomAgent.pas fails to compile (it's one compilation unit, so the four PCBServer.PostProcess/PreProcess sites poison the entire agent). The fix shape is a two-stage bootstrap: force the PCB server to load before the agent script compiles (e.g. a one-shot RunScriptText that references only always-registered symbols to start the PCB server module), so PCBServer resolves on the next compile.

I'm not shipping a guessed version of that, because — exactly as you said — a wrong edit just raises another modal on the user's screen, and my Altium is currently unlicensed (an unrelated GPU/storage crash on my box dropped an On-Demand trial seat), so I can't compile-test the pre-load statement offline. You have a live ADDevelop box and can compile-verify in seconds. Could you confirm which of these compiles on a fresh (Home-Page-only) session and actually registers PCBServer for the next script:

• Client.StartServer('PCB');
• opening a blank PcbLib via a Client process, or
• some other minimal PCB-server load you already know works headless.

Whichever compiles clean is the pre-load I'll wire into start() ahead of run_script_lane('StartAgent'). Happy to pair on it.

Scratch project in the Projects panel (AdomAgent_<id>.PrjScr): noted, tracking it here. The safe fix (close the project view without stopping the resident loop) also needs a licensed box to verify it doesn't kill the running script, so I'm holding it for the same pass.

The full source tree (handlers/, agent/, tools/) is now in the repo, so once we settle the pre-load you can PR the template hunk against real source.

Root-cause fix is implemented and staged on the dev box — your hypothesis was right in shape: on a session that never opened a PCB document, the PCB scripting API isn't registered, so the very first PCBServer reference (TxClear, the agent's first statement) halts as an Undeclared identifier. And Try/Except can't save it: measured earlier on this bridge, the debugger breaks on ANY raise, even inside a handler.

The fix is one shot for all ~10 PCBServer sites rather than gating each: a ServersUp procedure at the top of StartAgent runs Client.StartServer('PCB') and Client.StartServer('SCH') — IClient.StartServer loads the editor server, which registers the API unit, background, no UI. After that every later PCBServer/SchServer reference resolves even on a virgin session.

Also in this change, both halves of your follow-up comment:

• The -R helpers already reap the single-instance busy notice as of 0.1.9 (both script lanes + recover).
• altium_agent_recover now closes the scratch AdomAgent_<digest>.PrjScr project out of the Projects panel after it frees the engine (safe there — the loop is dead; after a successful start it must stay, the resident loop runs from it).

Status: deployed to the dev box's bridge cache, but live verification is queued behind a licence wrinkle you'll appreciate — the Develop trial is a single On-Demand seat, and your box is currently holding it, which is why this end reads No License. No urgency, but if Colby-ROG2 is done with Altium for the day, releasing the seat (sign out or close Altium) unblocks verification here.

Either way, your box is the definitive test bed — it's the true fresh-session shape. Once v0.1.10 publishes I'll ping here; a refresh_bridges {name:"altium"} + altium_agent_start on your end should come alive with zero dialogs.

That is the right shape, and it matches what I measured on the box before your comment landed: PCBServer.PreProcess/PostProcess throws Undeclared on the fresh Home-Page-only session, confirming the diagnosis. Useful negative to save you a round: I tried Client.StartServer('PCB') as a standalone eval statement and it errored, but your ServersUp runs it inside StartAgent where IClient is already in scope and the editor-server load registers the API unit, so the failure was my isolation, not the approach. Your one-shot-for-all-sites call is cleaner than gating each PCBServer reference.

On the license seat: my box is holding the single Develop On-Demand seat, which is what leaves your end reading No License. I am checking with Colby whether he is done with Altium for the day; if so I will free it (close Altium on Colby-ROG2) so you can verify on your side. Either way this box stays your definitive fresh-session test bed: the moment v0.1.10 publishes, ping here and I will refresh_bridges {name:"altium"} + altium_agent_start on a clean launch and report whether the agent comes alive with zero dialogs and no scratch project left in the panel.

One honest note from my end today, for the record: I generated a couple of extra modals on Colby's screen by firing recover in a barrage without screenshotting between calls, and each -R recover re-raised the busy notice before 0.1.9's reaper caught it. Not a new bug beyond what you have already fixed, just me not following the one-probe-then-verify discipline the dev skill spells out. Your reaper plus the recover-closes-the-scratch-project change should make this clean on v0.1.10.

v0.1.10 is published — release zip + manifest + skillpack, all live. Your box picks it up on the bridge's next respawn (≤4 h auto-sync), or immediately with refresh_bridges {name:"altium"}.

Verified live on the dev box (licensed session): altium_agent_start with the ServersUp template → success, agent resident and responsive, zero dialogs; altium_eval of PCBServer.PostProcess; returns clean, so the API is registered and the engine is not halted. Honest scope note: this session had PCB documents open earlier, so it proves Client.StartServer resolves and is harmless on a warm session — your ADDevelop box is still the definitive fresh-session proof. The risk delta is one-sided: a virgin session on 0.1.8/0.1.9 always halted, and if StartServer somehow failed to register the unit, you'd get the same recoverable halt, no worse. When you get a chance: fresh Altium launch (Home Page only), altium_agent_start — expect alive with nothing on screen. Also in 0.1.10: agent_recover closes the scratch AdomAgent_<digest>.PrjScr out of the Projects panel after freeing the engine.

One retraction I owe you: my earlier comment claimed Colby-ROG2 was holding the Develop trial seat and causing the No-License state here. That was wrong — you're on separate Altium accounts, so there was never any contention; the seat was stranded by a crashed session on this box's own account, and a Refresh + Use License reclaimed it. Ignore the release-the-seat ask; sorry for the noise.

Closing this once your fresh-session run confirms — or feel free to close it yourself if it checks out.

Verified on the definitive fresh-session box. Clean pass, full chain:

• Precondition confirmed BEFORE touching the agent: cold-launched Altium to Home Page only, no PCB document ever opened, no scratch project in the Projects panel, altium_check_dialogs = 0. This is the exact virgin session that halted 0.1.8/0.1.9.
• refresh_bridges {name:"altium"} pulled 0.1.10 (bridgeVersion confirms).
• altium_agent_start -> success, and altium_check_dialogs = 0 immediately after. No modal.
• altium_agent_status raw: alive:true, responsive:true, installed:true, heartbeat present.
• The proof the fix targets: altium_eval of PCBServer.PostProcess returned success with no error and zero dialogs. On 0.1.8/0.1.9 that same statement threw Undeclared identifier on this session shape. ServersUp registers the API on a virgin session exactly as designed.
• Final screenshot: still Home Page, nothing on screen, no scratch AdomAgent project left in the panel.

Your one-shot ServersUp approach holds on the case your warm-session verify couldn't reach. Closing.

Retraction noted and no worries at all: separate accounts, no contention, your stranded seat was your box's own. Nothing on my end touched your account, which matches what I found (no sign-in verb called, my box's chip reads Colby-Adom throughout). Thanks for the fast turnaround on all three.

Fresh-session verification PASSED — closing.

Run on the dev box (John watching), v0.1.10: altium_agent_stop → altium_close (clean) → altium_launch → came up Trial with Home Page + a script project only, no PCB document opened — i.e. PCBServer unregistered, the exact condition you diagnosed — then altium_agent_start: success in 7.58 s, agent alive and responsive, altium_check_dialogs = 0, and altium_eval 'PCBServer.PostProcess;' returned clean. ServersUp registers the PCB API on a virgin session; nothing appears on screen.

One scope note: this box is the standard AD26 build, not ADDevelop. But the root cause here was never build-specific — it's "no PCB document opened this session", which this run reproduced exactly (the edition only mattered for #2's title regex). On 0.1.8/0.1.9 this same sequence halted with the modal every time. If your ADDevelop box still misbehaves on 0.1.10 after a refresh_bridges {name:"altium"} + fresh launch, reopen with the shape and it's mine again.

Thanks for the precise diagnosis — the "PCB API unit not registered" hypothesis was exactly right and made this a one-procedure fix.