fix(desktop): make generated HTML previews truthful and directly openable #5213

Problem

A real H5 workflow exposed several misleading or unreliable assumptions in the local preview handoff:

• file:// navigation is rejected by the embedded Browser because it requires an HTTP origin. This is an intentional security boundary, not a readiness signal.
• An ad-hoc python3 -m http.server process was reported as running, while a subsequent request to 127.0.0.1 failed with connection refused.
• The shell process environment and the Desktop Browser do not necessarily share files, localhost networking, or process lifetime.
• The shell open command is not a reliable GUI handoff in a sandboxed runtime.
• The agent could therefore say “started”, “ready”, or “opened” before the user had a usable page.

The harness self-evaluation identified the underlying product gaps: incomplete capability discovery, untrusted background-task status, missing endpoint health evidence, weak process observability, and no reliable local artifact handoff.

Resolution

Maka Desktop must provide one supported, truthful handoff for generated HTML: the HTML Artifact path. The supported flow is:

Write HTML → register HTML Artifact → show it in Generated Files → Open → materialize through validated main-process IPC → launch with the operating system default application.

This flow must not require file:// navigation in the embedded Browser, an ad-hoc localhost server, or a shell open command. It also needs an actionable Finder fallback when an HTML preview cannot be read.

The generic shell/browser sandbox limitations remain intentional boundaries. The product must not claim that an arbitrary background process is a healthy preview endpoint merely because its process state is running; instead, it should use the Artifact handoff or report the unsupported capability clearly.

Scope

Maka Desktop Artifact UI, Artifact visibility policy, and the existing validated Artifact IPC path. This issue records the harness self-evaluation symptoms and their product-facing mitigation; it does not introduce a generic process supervisor, weaken the file:// security policy, or make Shell and Desktop Browser share a network sandbox.

Acceptance criteria

1. Directly generated HTML files are registered as HTML Artifacts and are visible in the Generated Files panel.
2. The HTML Artifact has an explicit Open action in that panel.
3. The action materializes the file through the existing path validation boundary and launches HTML with the operating system default application; it does not rely on localhost or embedded file:// navigation.
4. Unreadable HTML previews retain a clear Finder fallback through Artifact IPC.
5. User-visible copy does not call an unverified background process ready or an unconfirmed browser handoff opened; unsupported ad-hoc preview paths remain clearly reported as unsupported.
6. Focused regression tests cover Artifact visibility, HTML materialization/default-app launch, and the unreadable-preview fallback.

Remaining harness/platform gaps

The following findings from the harness self-evaluation are still open and are not implemented by PR #5216. They should be tracked as platform or harness follow-ups rather than treated as missing Desktop Artifact behavior:

• Browser admission does not support file://; it requires an HTTP origin.
• Shell and Desktop Browser may not share filesystem visibility, localhost networking, or process lifetime.
• A background task state of running does not prove that a server is listening or reachable; the harness needs explicit spawned, listening, healthy, unreachable, and exited states, plus startup/exit logs and health checks.
• The shell open command cannot be assumed to provide a working GUI/default-browser handoff from a sandbox.
• There is no dedicated desktop_open_file or browser_open_local_artifact capability, nor a platform-managed Artifact preview endpoint.
• Capability discovery does not clearly report URL-scheme, GUI, localhost, and sandbox constraints before an operation is attempted.
• Archived command output is not seamlessly paginated with enough live error/status context for reliable diagnosis.
• The harness lacks a single verified create preview → open → confirm loaded operation and a preflight check for GUI/browser/filesystem/network capabilities.

These gaps remain intentionally out of scope for the current Desktop PR. The supported product behavior is the Artifact handoff described above; unsupported ad-hoc localhost or shell-open paths must be reported as unsupported rather than described as ready or opened.

Related: #4267