Harden build workflows and OBS selection

Add preflight, cancellation, confined status, and timeout handling for
local Sailfish and remote Android build jobs.

Vendor helper 2.0.0 with explicit backend/pull controls, build locking,
local RPM validation, metadata, and structured failure reporting.

Expose named internal, partner, and community OBS servers while retaining
raw osc API aliases.

1 files changed, 50 insertions, 19 deletions

diff --git a/README.md b/README.md
index a2e01f7..ce5d1a3 100644
--- a/README.md
+++ b/README.md
@@ -22,8 +22,8 @@ The server currently exposes tools for:
 - system and user service management
 - user-session command execution with the configured D-Bus environment
 - Sailfish Browser launch/debug helpers
-- Docker/mb2 RPM builds through the local `build-sailfishos` helper
-- remote Android/AppSupport builds on configured build hosts
+- preflighted Docker/mb2 RPM builds through the vendored `build-sailfishos` helper
+- cancellable local and remote Android/AppSupport build jobs
 - installed SDK repository metadata refresh
 - Jolla OBS result and build-log lookup through `osc`
 - repository status and search under the configured git root
@@ -36,11 +36,13 @@ placeholder SSH target `root@device`, the Sailfish user-session bus at
 `~/OBS` as the OBS checkout root, and the vendored build helper at
 `src/sailfish_devel_mcp/vendor/build_sailfishos.py`. Put a config file at
 `~/.config/sailfish-devel-mcp/config.json` or pass `--config` to provide your
-real device and OBS settings. Device entries can also carry the preferred
-user, architecture, and current release label. If an installed SDK is
-available, set `paths.local_sdk` to its `sdk-chroot` path; builds will use it
-when it has a target matching the requested release and architecture, otherwise
-they fall back to the coderus SDK image.
+real device and OBS settings. Device entries can also carry the preferred user,
+architecture, and configured release label. If an installed SDK is available,
+set `paths.local_sdk` to its `sdk-chroot` path; builds will use it when it has a
+target matching the requested release and architecture, otherwise they fall
+back to a matching tag in the third-party coderus Docker mirror. Neither a
+configured device label nor mirror tag availability independently establishes
+the current official SailfishOS release or SDK target.
 
 ## Running
 
@@ -127,7 +129,9 @@ Mutating tools are annotated as non-read-only:
 - `sailfish_device_restart_service`
 - `sailfish_device_browser_launch`
 - `sailfish_build_rpm`
+- `sailfish_build_cancel`
 - `sailfish_android_build`
+- `sailfish_android_build_cancel`
 - `sailfish_sdk_refresh_metadata`
 
 `sailfish_device_lipstick_screenshot` defaults to
@@ -169,34 +173,54 @@ for the topmost PID and checks whether that process has `libxul.so` mapped.
 as defaults when the call includes `device`. If `paths.local_sdk` is set, the
 build defaults to `live` and first checks the installed SDK targets. `live` uses
 the unversioned local target for the requested architecture, for example
-`aarch64`. A named production release such as `5.0.0` is used only when passed
-explicitly through the tool arguments, environment, or device config; it uses a
-matching versioned local target such as `aarch64-5.0.0` when available, and
-otherwise falls back to the release-specific coderus Docker SDK image. The
-wrapper image defaults to `sailfish-sdk-build-engine:$USER` and can be
-overridden with
+`aarch64`. A named production release is used only when passed explicitly
+through the tool arguments, environment, or device config; it uses a matching
+versioned local target when available, and otherwise falls back to a matching
+tag in the third-party `coderus/sailfishos-platform-sdk` Docker mirror. Tags in
+that mirror indicate image availability; they do not identify the current
+official SailfishOS release or SDK target. The wrapper image defaults to
+`sailfish-sdk-build-engine:$USER` and can be overridden with
 `SAILFISH_SDK_BUILD_ENGINE_IMAGE`.
 
+Use `sailfish_build_preflight` to validate backend, image/target selection,
+architectures, local RPM inputs, pull policy, VCS behavior, and artifact paths
+without pulling an image or changing the project. `sailfish_build_rpm` accepts
+the same `backend`, `local_sdk`, `target`, `pull_policy`, `no_vcs_apply`, and
+`allow_untrusted_rpms` controls. An explicitly selected `local` backend does
+not silently fall back to Docker. Asynchronous jobs use confined UUID job
+directories and expose helper metadata and RPM paths through
+`sailfish_build_status`; use `sailfish_build_cancel` to terminate the tracked
+process group.
+
 `sailfish_android_build` starts a remote Android/AppSupport build on the
 configured build host. Configure `android_build_hosts.<host>.project_dir` or
 pass `project_dir` to point at the remote Android tree, for example an
 `alien-aliendalvik-system` checkout. The tool writes job state under the remote
-`state_dir`, creates a per-job `run.sh`, and starts it with `nohup`, so the SSH
-session used to launch the job can disconnect without killing the build. Poll
-with `sailfish_android_build_status`; omit `job_id` to list recent jobs, or pass
-a job id to read state and tail `build.log`.
+`state_dir`, atomically creates a per-job directory, and starts its own process
+group with `nohup` and `setsid`, so the SSH session used to launch the job can
+disconnect without killing the build. Set `build_timeout` for a remote build
+lifetime limit. Poll with `sailfish_android_build_status`; omit `job_id` to list
+recent jobs, pass a job id to read state and tail `build.log`, or use
+`sailfish_android_build_cancel` to terminate the identity-checked process
+group.
 
 `sailfish_sdk_refresh_metadata` refreshes zypper metadata in the installed SDK
 main target, for example `aarch64.default`, using the same privileged Docker
 wrapper style as local SDK builds. Use it when local SDK builds fail because a
 package listed in repository metadata cannot be downloaded.
 
+`sailfish_obs_results` and `sailfish_obs_buildlog` accept `server` as
+`internal`, `partner`, or `community`. `internal` maps to the `.oscrc` alias
+`jolla`; the other names map to matching aliases. Omit `server` to use
+`paths.osc_api_alias`. The advanced `api_alias` argument accepts any raw
+`osc -A` alias or API URL and cannot be combined with `server`.
+
 `sailfish_obs_buildlog` defaults to `osc api` with `nostream=1` so a build log
 request does not become a long-running live stream. Set `nostream` to `false`
 to use `osc remotebuildlog`.
 
-Read-only tools include the journal, topmost PID, process maps, OBS lookup,
-repo search, spec summary, and QML checks.
+Read-only tools include build preflight/status, the journal, topmost PID,
+process maps, OBS lookup, repo search, spec summary, and QML checks.
 
 ## Smoke Test
 
@@ -214,3 +238,10 @@ Run tests without installing the package:
 ```sh
 PYTHONPATH=src python3 -m unittest discover -s tests
 ```
+
+The canonical helper lives in the `build-sailfishos` skill. Update the exact
+vendored copy with:
+
+```sh
+python3 scripts/update_build_helper.py /path/to/build-sailfishos/scripts/build_sailfishos.py
+```