[wangyinz]

Summary

• standardize DesktopLauncher on data/yaml/compose.yaml, canonical Linux/macOS/Windows browser argv, and argv-only subprocess execution
• start the complete Compose project rather than only mspass-frontend, and report ready only when every configured service is running
• wait for a real Jupyter HTTP(S) URL with configurable startup timing; never fabricate a tokenless fallback
• preserve caller-owned projects, make launch/shutdown idempotent, and deterministically terminate/wait (or kill) owned browser processes
• retain ordinary Python API boundaries: invalid arguments raise ValueError; Compose, readiness, and browser failures raise RuntimeError
• document topology, ownership, lifecycle, return values, and failure behavior in the public class and method docstrings

Root cause

The prototype queried logs before readiness, mixed Compose configuration and service names, built platform-specific browser shell strings, ignored command return codes, and did not track stack/browser ownership consistently.

The first version of this PR followed an issue-authored contract too literally: it targeted and checked only the frontend service, which can leave a scheduler with no worker, and changed ordinary launcher failures to MsPASSError(Invalid) without a compatibility basis. The scientific/API re-audit corrected both expansions.

Impact

Desktop launches now fail explicitly, require the database/scheduler/worker/frontend topology to be running, never fabricate a fallback URL, preserve caller-owned stacks, and clean up owned resources without replacing the original exception when cleanup itself also fails.

Validation

• focused launcher contract: 24 passed
• exact Compose/browser argv, delayed URL, full-service readiness, partial topology, every public failure path, ownership, idempotence, and browser poll cleanup covered
• Python byte compilation and git diff --check: passed
• test file formatted with Black; production changes are confined to DesktopLauncher in a legacy file whose unrelated HPC section is not Black-formatted

This PR remains draft pending the full renewed compatibility/scientific re-audit.

Fixes #808

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.35%. Comparing base (7d00c61) to head (053a12c).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #952   +/-   ##
=======================================
  Coverage   74.35%   74.35%           
=======================================
  Files         183      183           
  Lines       36516    36516           
  Branches     2540     2540           
=======================================
+ Hits        27150    27151    +1     
+ Misses       8456     8455    -1     
  Partials      910      910           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[wangyinz]

Renewed review found three blockers:

1. Prefer the loopback Jupyter URL. Real logs print the container hostname URL before 127.0.0.1; returning the first URL opens an address the desktop host cannot resolve.
2. Treat a nonzero compose up as potentially partial and attempt cleanup when this launcher began from an empty project.
3. Retain _owns_stack and the browser handle when cleanup fails so shutdown() can be retried.

Maintainer decision needed: if some configured Compose services are already running on entry, should launch() (a) fail without changing the caller-owned partial project (recommended), or (b) complete it with up -d but never run down?

[wangyinz]

Implemented the reviewed lifecycle policy and rebased onto #951/master.

• An empty Compose project is launcher-owned and is cleaned up on launch failure or shutdown.
• A partially running project is caller-owned: up -d fills missing services, but this launcher never runs down.
• Failed down and browser cleanup retain state/handles so cleanup can be retried.
• Jupyter log parsing prefers a loopback URL when container and host URLs are both present.
• HPC and desktop launcher contract suites pass together: 57 tests.

Keeping this PR draft until the refreshed CI is green.