Avoid launching a second shared Desktop client when attaching to an existing mphclient session

[jiweiqi]

Problem

The COMSOL skill/driver guidance currently makes visual_mode=shared-desktop sound like the default attach path for any live GUI collaboration. That is correct when the agent should create/manage the visible COMSOL Desktop client, but it is misleading when the user has already started comsolmphserver and opened the target .mph in an existing comsol.exe mphclient -host ... -port ... Desktop.

In that case, running:

sim connect --solver comsol --ui-mode gui `
  --driver-option attach_only=true `
  --driver-option port=2036 `
  --driver-option visual_mode=shared-desktop

can launch an additional COMSOL Desktop client, trigger a "server in use" / connection popup, or create extra sidecar model tags. The desired operation for inspection is only to attach the agent/API client to the already-running server and inspect the existing model tags.

Observed session

Workflow used:

1. User starts comsolmphserver on port 2036.
2. User opens comsol.exe mphclient -host localhost -port 2036.
3. User opens 双饼_屏蔽电流计算.mph in that GUI.
4. Agent tries to inspect tags with visual_mode=shared-desktop.

Observed effects:

• An extra ComsolUI process appeared.
• The GUI showed a server/client conflict popup.
• Earlier attempts created sidecar tags such as Model1/Model3.
• After cleanup, the correct state was obtained by using an existing session/no-new-GUI attach: one model tag (Model2) with label 双饼_屏蔽电流计算.mph, comp1, physics mfh/cc, and studies std1/std3.

Proposal

Documentation / skill routing

Clarify the routing rule:

• Use visual_mode=shared-desktop when the agent should launch/manage the visible COMSOL Desktop client.
• If the human already has a server-backed GUI open (comsol.exe mphclient -host ... -port ...) with the target model loaded, first attach without launching a new GUI:

sim connect --solver comsol --ui-mode no_gui `
  --driver-option attach_only=true `
  --driver-option port=2036

Then inspect:

sim inspect session.health
sim exec "_result = {'tags': [str(t) for t in list(ModelUtil.tags())], 'bound': str(model.tag()), 'label': str(model.label())}"

Driver/CLI behavior

Consider one of these improvements:

1. Add an explicit visual_mode=existing-desktop or desktop_attach=existing mode that attaches to the server/API without launching a new mphclient, but still reports observed COMSOL windows.
2. When attach_only=true and a matching COMSOL Desktop/mphclient window is already present for the target port, warn before launching a second Desktop client.
3. Split health semantics so model_builder_live=true does not imply the driver should always create a new visible client. It should distinguish:
   • desktop_client_owner=plugin
   • desktop_client_owner=user
   • desktop_observed=true/false
4. Add a tag-inspection command/path that is explicitly no-GUI and safe for existing human-owned GUI sessions.

Why this matters

This is a common collaborative workflow: the user wants to own the COMSOL GUI and open the model manually, while the agent only attaches to the same server for structured inspection/mutations. Launching an additional Desktop client is surprising and can disturb the GUI/session state.

[jiweiqi]

Additional proposal: remove or hard-deprecate the Java Shell / ordinary Desktop attach path.

The current Java Shell fallback depends on GUI automation/UIA against an already-open COMSOL Desktop. In practice this creates a second, fragile control plane separate from the structured comsolmphserver/JPype path:

• It depends on window focus, language/UI layout, dialogs, Java Shell visibility, and text submission behavior.
• It can confirm that code was submitted, but not provide the same structured execution/identity guarantees as session.health, ModelUtil.tags(), and live driver binding.
• It encourages agents to treat an ordinary standalone Desktop as automatable evidence, which conflicts with the safer server-client workflow.
• It blurs routing decisions: users and agents may try Java Shell attach for cases that should instead be either offline .mph inspection or no-GUI attach to an existing comsolmphserver.

Suggested direction:

1. Remove sim-comsol-attach / Java Shell from the main documented agent workflow.
2. If kept at all, move it to an explicitly unsupported/diagnostic-only namespace with strong warnings and no acceptance semantics.
3. Make the supported paths only:
   • offline .mph inspection for saved artifacts,
   • no-GUI attach_only=true for user-owned existing server sessions,
   • plugin-owned visual_mode=shared-desktop when the agent should launch/manage the visible Desktop client.

This would make the skill simpler and reduce the chance that GUI automation gets used for model-tree, geometry, physics, solve, or validation tasks.

[jiweiqi]

Addressed by merged PR #34 (c831509).

What changed:

• The COMSOL skill now explicitly says an already-open ordinary Desktop is not a reason to use Java Shell / GUI automation.
• For a user-owned comsolmphserver + mphclient session, the documented route is now no-GUI API attach:

uv run sim connect --solver comsol --ui-mode no_gui `
  --driver-option attach_only=true `
  --driver-option port=<port>

• visual_mode=shared-desktop is now scoped to plugin-owned/managed Desktop launch rather than user-owned existing Desktop sessions.
• The Java Shell / ordinary Desktop attach path is documented as deprecated and not acceptable as serious automation or validation evidence.
• The useful residual JPype notes were moved into server-backed Java API guidance rather than Java Shell guidance.

I’m closing this as addressed for the documented agent workflow. If we still want a driver-level guard later (for example warning when attach_only=true plus visual_mode=shared-desktop might launch a second Desktop), that should be tracked as a narrower implementation issue.