Multiprocessing child interception: run the host binary as a headless interpreter for spawn/forkserver/resource-tracker re-execs

[ndonkoHenri]

Part of flet-dev/flet#4283. Companion PRs: flet-dev/serious-python#228 (consumes these exports and bumps the pin) and flet-dev/flet#6662 (build-template runners that call them).

Problem

Python's multiprocessing (the spawn and forkserver start methods, plus the resource tracker) launches helper processes by re-executing sys.executable with a CPython command line. In apps embedding Python through this library, sys.executable resolves to the host app executable, so every helper re-launched the host GUI instead of running the multiprocessing protocol: one stray window per worker, tasks that never executed, hung joins, and resource_tracker: process died unexpectedly, relaunching loops. This has been broken since 2024 and is the core of flet-dev/flet#4283. Notably, Python 3.14 made forkserver the default start method on Linux, so packaged Linux apps now hit the broken re-exec path even for code that never selects a start method.

Solution

Two new stable-ABI exports in serious_python_run.c let the host binary double as a plain Python interpreter for exactly those helper invocations:

• serious_python_is_mp_invocation(argc, argv) matches --multiprocessing-fork anywhere in argv, or a -c payload starting with from multiprocessing. or import sys; from multiprocessing., covering spawn workers, the resource tracker, and the forkserver on CPython 3.12–3.14. The match is deliberately prefix-based because the exact helper command lines are CPython implementation details that shift across minor releases, while the helpers stay under multiprocessing.*.
• serious_python_main(argc, argv) runs a shared preflight (scrub inherited PYTHONINSPECT, which would otherwise hold a real interpreter child open in interactive mode after its -c command; verify PYTHONHOME/PYTHONPATH are present, which the parent's serious_python_run already setenv's process-wide so children inherit the embedded stdlib and site-packages; register the in-binary dart_bridge module on the inittab so inherited dart_bridge-aware imports fail soft), then delegates to Py_BytesMain for the full standard interpreter lifecycle.

Windows additionally gets wide-char variants serious_python_is_mp_invocation_w / serious_python_main_w (delegating to Py_Main), since wWinMain argv is wchar_t** and decoding through the ANSI code page in the narrow versions would be lossy.

Host contract (documented in the README): call the detector first thing in main / wWinMain / main.swift, before any UI or engine initialization, and exit with serious_python_main's return code on a match. The flet build template runners do exactly this, resolving the exports via dlsym/GetProcAddress with graceful fallthrough so hosts built against older dart_bridge keep launching unchanged.

The EXPORT macro on non-Windows now adds __attribute__((used)): on Mach-O the archive is statically linked into the host app and several exports are referenced only via dlsym/Dart FFI, and without the no-dead-strip marker the host link's -dead_strip discarded any export lacking a static call site.

CI fix: glibc floor of Linux artifacts

Artifacts are currently built directly on ubuntu-24.04 runners (glibc 2.39), so they bind modern symbol versions — e.g. strtoll → __isoc23_strtoll@GLIBC_2.38. Since the flet build template links libdart_bridge.so straight into the app executable, flet build linux fails its final link on anything older (reproduced on Ubuntu 22.04 LTS: clang: error: linker command failed). This affects the released 1.4.1 Linux artifacts today, independent of new features — worth re-spinning with the next tag.

Fix

Build inside a debian:10 job container on modern runners — the same pattern (and lowest tier) as flet's own build_linux matrix (manylinux_2_28). dart-bridge ships one .so per arch, so it must clear the lowest supported tier: a glibc 2.28 floor covers Debian 10/11/12, Ubuntu 20.04/22.04/24.04, and RHEL 8+ with a single artifact.

Details (each step is commented in the workflow):

• Debian 10 is EOL → apt pointed at archive.debian.org, Check-Valid-Until off; git/ca-certs installed before actions/checkout (the action runs inside the container).
• Debian 10 ships CMake 3.13 (< our 3.15 minimum) → current CMake from Kitware's official binaries, which run on old glibc.
• New assertion step: the job fails if the artifact references any glibc symbol newer than 2.28 — the floor is an enforced contract, so a future container/runner bump can't silently raise it.

Verification

Verified end-to-end inside flet build apps on macOS (arm64), Windows 11 (arm64 host, x64 app), and Ubuntu 22.04 (aarch64): a Process+Queue round-trip with a worker defined in the app's main.py, and a ProcessPoolExecutor benchmark with worker reuse, all completing with headless children, correct results, roughly cpu-count speedups, and clean exits, under both the spawn context and Linux's forkserver default. The interception was also smoke-tested directly by invoking the built app binaries with multiprocessing-shaped command lines.

Release notes

Merging this should be followed by tagging 1.5.0 (semver minor: new exports, no breaking changes), which republishes all platform artifacts including the glibc-2.35-floor Linux ones. flet-dev/python-build's manifest.json then bumps dart_bridge_version to 1.5.0, and flet-dev/serious-python#228 picks up the regenerated pin. Note that serious-python 4.3.0's darwin plugin hard-requires these exports at link time (dead-strip keep-alives), so the tag must exist before that releases.

[github-advanced-security]

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

[Copilot]

Pull request overview

This PR adds multiprocessing-child interception support so apps embedding Python via dart_bridge can detect when they’ve been re-exec’d by CPython’s multiprocessing helpers and run as a headless interpreter instead of re-launching the host GUI. It also tightens GitHub Actions security posture and adjusts Linux CI runner selection to keep a lower glibc baseline for published artifacts.

Changes:

• Add new exported entry points to detect multiprocessing helper invocations and delegate to Py_BytesMain/Py_Main after a small child-process preflight.
• Document the host-side integration contract and platform-specific notes in the README.
• Pin workflow actions to SHAs, add a zizmor workflow, and pin Linux builds to ubuntu-22.04 runners to preserve a glibc 2.35 floor.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
src/serious_python_run.c	Adds multiprocessing invocation detection, a child preflight, and interpreter-entry exports (including Windows wide-char variants).
README.md	Documents the new multiprocessing interception API and host integration requirements.
.github/workflows/zizmor.yml	Adds a zizmor Actions security analysis workflow with least-privilege permissions.
.github/workflows/ci.yml	Pins action versions to SHAs, restricts default permissions, and moves Linux builds to ubuntu-22.04 runners for glibc compatibility.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.