feat: describe selected launch configurations and named test runners

Author: Sunrisepeak

.agents/docs/2026-11-06-launch-configuration-and-named-test-runners.md

@@ -0,0 +1,39 @@
+# Launch configuration and named test runners
+
+Status, 2026-11-06: implemented for candidate 2026.11.6.1. Focused local
+controls pass; final public-dependency and cross-platform CI remain pending.
+
+A consumer choosing a debugger runner needs the configuration of the program
+selected to run. A separate `self env` query may describe a different profile
+or the first leg of a target set instead of its reachable launch leg. The
+launch producer already holds the selected build context and can describe it
+without another planning protocol.
+
+`mcpp.launch.data.configuration` therefore adds `triple`, `profile`,
+`platform` and `runners` to both program and test launch descriptions.
+The first three fields match the build result's configuration. `runners`
+lists nonempty effective named-runner declarations even when no platform is
+active. Older consumers can ignore the additive object; newer consumers test
+for its presence. No device or debugger name acquires core semantics.
+
+`mcpp test --runner <name>` uses the existing named-runner resolver. The same
+choice applies to ordinary test execution, launch description and execution
+of tests from an archive. A missing name is refused, rather than running the
+test directly. `--runner` and `--no-runner` are contradictory and refused.
+Timeouts, output capture, execution-host routing and test verdicts retain
+their existing behavior. The platform or project owns the runner's command.
+
+The IDE can use the additive configuration to choose a platform's `debuggee`
+runner while preserving the selected target and profile, and reject a
+different configuration in the second result. OpenKal platform 0.24 declares
+that runner using existing platform fields. The core contains no OpenKal
+debugger flag, loader path or JIT policy.
+
+The fresh local candidate passes E2E 01, 333, 993 and 936. E2E 993 exercises a
+real named runner, its returned command, ordinary and archived test execution,
+argument preservation and refusals. E2E 936 passes with the inherited
+`NO_COLOR=1` removed; its assertions remain unchanged. The build uses the OS
+0.3 candidate source and does not establish final public installation.
+An actual IDE-backend/core integration additionally passes eleven program
+and test launch checks without a mock. The modified target-set E2E 963 and
+the final packaged editor/runtime checks still require their full scopes.

CHANGELOG.md

@@ -4,10 +4,16 @@
 > Each `## [<version>]` section is that release's notes. Entries are written in English
 > from 2026.9.28.3 on; earlier entries remain as written.
 
-## [2026.11.5.2] - 2026-11-05
+## [2026.11.6.1] - 2026-11-06
 
 ### Fixed
 
+- Launch descriptions include the selected target, profile, resolved platform
+  and available named runners, including the reachable leg of a target set.
+  Editor debug launches can retain the configuration that actually built the program.
+- Tests accept `--runner <name>` with the same runner resolution as `run`,
+  including `--print-launch` and archive execution. Missing names and a
+  simultaneous `--no-runner` are refused.
 - Cached builds load action ownership when an action starts, so internal progress
   appears while Ninja is still buffering stdout. Idle builds retain lazy loading;
   command results and output checks remain authoritative.

docs/04-mcpp-toml.md

@@ -1049,7 +1049,7 @@ with two behaviours has to be.
 `bmi_schedule` decides when importers are unblocked.
 
 With GCC and `bmi_schedule = "on"`, ordinary compilation and detached code
-generation share the same total `jobs` limit (2026.11.5.2+). Additional
+generation share the same total `jobs` limit (2026.11.6.1+). Additional
 scheduling and join tasks do not increase the number of compiler processes.
 Cancelling the build ends its ordinary and detached compilers. An immediately
 following build waits for their cleanup before starting another compiler;

docs/08-testing.md

@@ -170,6 +170,18 @@ or a QEMU exit code is what a bare-metal runner is chosen to produce.
 `--no-runner` exists for a host that can execute the binaries natively and
 should not pay for an emulator.
 
+`--runner <name>` (2026.11.6.1+) selects a named runner instead of the default,
+using the same declarations and argument substitution as `mcpp run --runner`.
+It also applies to `--print-launch` and tests read from an archive. An absent
+runner name is refused; `--runner` and `--no-runner` cannot be combined.
+
+For a platform that declares `debuggee`, this builds one test and prints the
+command a debugger starts, without starting the test:
+
+```bash
+mcpp test unit/math --runner debuggee --print-launch
+```
+
 `--no-run` makes the narrower claim, and it has to be asked for. Without it, a
 target this host can neither execute nor reach through a runner leaves every
 test not run and the command exits 2: mcpp did not establish whether the tests

docs/24-openkal-cross.md

@@ -411,7 +411,7 @@ Nothing else is declared (2026.10.27.1+): the target table selects
 `openkal-platform` for both rows, and the platform states the toolchain, the
 layers, the tools, the conventions below and the runner ([35](35-platforms.md)).
 
-Both built-in openkal targets select platform 0.24.0 by default (2026.11.5.2+).
+Both built-in openkal targets select platform 0.24.0 by default (2026.11.6.1+).
 An explicit `platform` configuration overrides that selection. This platform
 preserves the emulated TLS convention through the final ThinLTO link.
 

docs/25-home-indices-and-store.md

@@ -90,7 +90,7 @@ configuration, so it remains usable while the network is broken.
 An install tracks byte progress and source changes separately for each active
 download. Time spent waiting for a download slot does not consume that budget.
 Progress on another file does not renew a stalled file's budget.
-From 2026.11.5.2, a stalled-download diagnostic names the file, elapsed interval
+From 2026.11.6.1, a stalled-download diagnostic names the file, elapsed interval
 and source attempt. Provider preparation and process timeouts are reported
 separately. Mirror selection
 uses `mcpp self config --mirror auto`, `CN` or `GLOBAL`.

docs/30-build-mcpp.md

@@ -1097,7 +1097,7 @@ none to rely on), and the only interpolations are a closed set:
 | `${mcpp.out_dir}` | the build output directory |
 | `${mcpp.bin_dir}` | where produced binaries land: `bin/`, or, for an action a workspace member's build program declares, that member's product directory (2026.9.29.4+) |
 | `${mcpp.compile_db}` | path to `compile_commands.json` (what clang-tidy's `-p` wants) |
-| `${mcpp.contract}` *(2026.10.30.1+)* | path to the configuration's contract, `mcpp-contract.json`, beside its compile database: the compiler of each language with the words every unit is compiled with (target, sysroot, target-side headers, platform and profile flags), and the link driver, its words and the archiver. A foreign build system reads it to compile for the target as the engine does; a package's own include directories are not in it, nor the engine's C++ dialect and module words (`-std=`, `-fmodules`), which are its choice for its own units. Since 2026.11.5.2, link arguments describe the target configuration; the consuming package's link flags and libraries are excluded, since they can name outputs the foreign build has yet to produce |
+| `${mcpp.contract}` *(2026.10.30.1+)* | path to the configuration's contract, `mcpp-contract.json`, beside its compile database: the compiler of each language with the words every unit is compiled with (target, sysroot, target-side headers, platform and profile flags), and the link driver, its words and the archiver. A foreign build system reads it to compile for the target as the engine does; a package's own include directories are not in it, nor the engine's C++ dialect and module words (`-std=`, `-fmodules`), which are its choice for its own units. Since 2026.11.6.1, link arguments describe the target configuration; the consuming package's link flags and libraries are excluded, since they can name outputs the foreign build has yet to produce |
 | `${mcpp.target_file:<name>}` | the built file of target `<name>` |
 | `${mcpp.stage_dir}` *(2026.9.11.1+)* | the tree `mcpp pack` staged, absolute. `artifact` role only, and only under `mcpp pack --pkg-format <name>` |
 | `${mcpp.self}` *(2026.9.13.1+)* | the engine's own executable, absolute. An action's command is an argv with no shell, so a build program has no portable way to copy a file; the engine is present wherever a build runs, and `${mcpp.self} stage --verify content --output <dst> <src>` copies one file, creates the destination's parent, and writes only when the bytes differ. That argument shape is a contract from 2026.9.13.1 on; a build program that names it declares that release as its floor |

docs/50-machine-output.md

@@ -1002,6 +1002,13 @@ starting it. `data` is `program`, `argv`, `cwd`, `env` and `via`, as
 `launch` above. `--print-launch` takes no `--format`: on `mcpp run`, `--pkg-format`
 names a distributable.
 
+`data.configuration` (2026.11.6.1+) contains the selected program's `triple`,
+`profile` and resolved `platform`, using the same fields as the build record's
+configuration. For a target set it describes the leg selected for this launch.
+`configuration.runners` lists the available named runners, including project
+declarations when `platform` is null. Older engines omit `configuration`;
+consumers check for its presence.
+
 ```
 mcpp test <name> --print-launch [-- <arguments>]
 ```

docs/specs/concurrency.md

@@ -7,7 +7,7 @@
 | 状态 | 评审中 v1.1 |
 | 版本 | 1.1 |
 | 最后修改 | 2026-11-06 |
-| 对应实现 | 基础保证: mcpp >= 2026.10.26.1; §5.1: mcpp >= 2026.11.5.2 |
+| 对应实现 | 基础保证: mcpp >= 2026.10.26.1; §5.1: mcpp >= 2026.11.6.1 |
 | 相关设计文档 | `.agents/docs/2026-10-26-control-contract-runtime-and-ide-ecosystem-design.md` §3、§4、§5.4 |
 | 相关 issue | #839 |
 | 使用文档 | [50 — 机器可读输出](../zh/50-machine-output.md) §9、§11 |
@@ -88,7 +88,7 @@ CI。在 2026.10.24.1 上,同一配置的两次冷构建相隔 0.1–0.5 s 启
 
 ### 5.1 分离编译的执行单元与恢复
 
-以下保证适用于 GCC 的 `bmi_schedule = "on"`（2026.11.5.2+）:
+以下保证适用于 GCC 的 `bmi_schedule = "on"`（2026.11.6.1+）:
 
 1. 普通编译与分离代码生成**必须**共用实际的 `jobs` 总上限。等待任务与调度任务
    **禁止**作为编译名额的替代。内核锁已释放而原编译单元仍被占用或状态未知时,

docs/zh/04-mcpp-toml.md

@@ -973,7 +973,7 @@ bmi_schedule = "off"     # auto (default, = off) | on | off
 `bmi_schedule` 决定 importer 何时被解除阻塞。
 
 使用 GCC 且 `bmi_schedule = "on"` 时，普通编译与分离的代码生成共用同一个 `jobs` 总上限
-（2026.11.5.2+）。额外的调度和等待任务不增加编译器进程数量。
+（2026.11.6.1+）。额外的调度和等待任务不增加编译器进程数量。
 取消构建会结束本轮普通编译器和分离的编译器。紧接着的构建等待它们完成清理后
 才启动新的编译器；未完成的输出会重新构建。已完成模块的 object 缺失时，
 该次构建会重新生成它。输入和输出均不变的构建仍不进行编译。