feat(device): runner gains three siblings, --locked asserts, and mcpp sbom

Four axes a project is asked about before it is adopted, and none of them had
an answer: how the artefact reaches a device, whether the build is
reproducible, what went into it, and whether an emulator and real silicon are
one package or two.

## The device slots

`run`, `flash`, `monitor` and `debug` are one shape — an argv the BOARD knows
and a TOOL performs, addressed absolutely, with the artefact appended or
substituted for `{}`. `runner` has carried that shape since 2026.8.19; three
special-case commands would have carried it three more times. So the slot is
the parameter: one directive-table row each, one reader, one CLI shape.

⚠️ What no argv can express is which of them ENDS. `run` and `flash` finish and
hand back a verdict; `monitor` and `debug` have no natural end, so a live
process is success for them and a hang for the other two. `Semantics` answers
that from the slot, because `openocd -c "program … exit"` and `openocd -c
"init"` are spelled alike up to the argument the board chose.

`debug` starts a SERVER and stops there. The client is the user's debugger or
their IDE, which reaches mcpp through docs/11; driving it would put mcpp in the
middle of a session it has nothing to add to.

⚠️ `runner-exclusive` is the first thing a physical board needed that an
emulator never did. `mcpp test` runs binaries on a worker pool; one probe on
one device is a mutex, and two workers reaching for it do not fail — they
interleave, and the verdict is about neither test. The board knows this about
itself, so it says so once and no project remembers `-j1`.

## Emulator or hardware is a feature, not a fork

A board reached through QEMU and the same board reached through a probe differ
in the argv of their device slots and nothing else. Publishing two packages
would duplicate a linker script, startup code and a module surface to vary four
strings. `mcpp::has_feature()` already existed, so this needed no engine work
at all — it is what the layering was for. e2e 333 builds one board package and
drives it both ways.

## --locked

The lock has always been written after resolution and never read back; its own
header said so. This makes it an ASSERTION rather than a pin: the resolution
that happens must equal the one recorded, and a difference names the package
that moved and both versions. That is the half reproducibility needs first, and
it is what Cargo's flag of the same name means.

⚠️⚠️ And it must not meet the fast path. Measured before that guard existed: a
deliberately corrupted lock passed `mcpp build --locked` and printed "Finished"
— the flag accepted, the build correct, the assertion never run. A criterion
that is skipped is worse than one that is absent, because the green reads as a
verification.

## mcpp sbom

CycloneDX 1.5 over the recorded resolution. Everything a bill of materials
names is already in mcpp.lock, so this is an output format rather than a
mechanism: it resolves nothing and asks the network for nothing.

⚠️ It reads the lock rather than re-resolving, which is the one property such a
document must have — an SBOM describing a different graph from the one that was
built is worse than none. Asserted in e2e 333 by editing the lock and checking
the output follows it. An unknown licence is emitted as NOASSERTION rather than
omitted: an absent key reads as "not examined", and a reviewer cannot filter on
silence.

## Two propagation sites, and the one that was missed first

Dependency-supplied RunGlobal entries reach the root through a different path
from a package's own directives. Wiring only `apply()` left `mcpp flash`
reporting "no flash is configured" while `mcpp run` found the runner the same
build program emitted three lines away — measured. Both sites now iterate the
slot table instead of naming `runner`.

Protocol version 6. 97/97 unit tests; freestanding e2e 130-139 and 332 green.

Author: speak-agent

modules/buildmcpp/src/directives.cppm

@@ -76,6 +76,24 @@ enum class Slot : std::size_t {
     // is neither a compile input nor a link input, and putting it in LdFlags
     // would put an emulator's argv on the linker command line.
     Runner,
+    // ⭐⭐ THE THREE SIBLINGS OF `Runner`, AND THE COLUMN THAT SEPARATES THEM.
+    //
+    // Writing an artefact to a device, watching what it prints and attaching a
+    // debugger have `Runner`'s shape exactly: an argv the BOARD knows and a
+    // TOOL performs. They are slots for the same reason `Runner` is one — an
+    // emulator's argv is neither a compile input nor a link input.
+    //
+    // ⚠️ WHAT NO ARGV CAN SAY IS WHICH ONE ENDS. `Runner` and `Flash` finish
+    // and hand back an exit code; `Monitor` and `Debug` do not terminate on
+    // their own, so for them a live process IS the success condition and for
+    // the other two it is a hang. `semantics_of` below answers that from the
+    // SLOT, because the tokens cannot.
+    Flash,
+    Monitor,
+    Debug,
+    // Not an argv at all: a board stating that it is a mutex. See
+    // `BuildConfig::runnerExclusive`.
+    RunnerExclusive,
     CxxFlags,
     CFlags,
     LdFlags,
@@ -104,6 +122,51 @@ enum class Slot : std::size_t {
 };
 inline constexpr std::size_t kSlotCount = static_cast<std::size_t>(Slot::Count);
 
+// ⭐⭐ HOW A DEVICE ACTION'S PROCESS ENDS, WHICH IS A PROPERTY OF THE SLOT.
+//
+// The four device slots share an argv shape and differ in exactly one way that
+// the engine has to act on: whether the process is expected to terminate.
+//
+//   OneShot    `run`, `flash` — runs to completion; the exit code is the verdict
+//   LongLived  `monitor`, `debug` — has no natural end; the operator ends it,
+//              and a non-zero status after Ctrl-C is that, not a failure
+//
+// ⚠️ NO TOKEN IN THE TEMPLATE CARRIES THIS. `openocd -c "program {} verify
+// reset exit"` terminates and `openocd -c "init"` does not, and both are
+// spelled the same way up to the argument the board chose. So it is read from
+// the slot, and a board cannot get it wrong by writing its argv differently.
+//
+// ⚠️ AND `debug` IS `LongLived` RATHER THAN A THIRD VALUE. It starts a GDB
+// SERVER; the client that attaches to it is the user's debugger or their IDE,
+// which reaches mcpp through the machine-output protocol (docs/11) and not
+// through this table. Driving the client would put mcpp in the middle of a
+// session it has nothing to add to.
+enum class Semantics { OneShot, LongLived };
+
+inline constexpr Semantics semantics_of(Slot s) {
+    return (s == Slot::Monitor || s == Slot::Debug) ? Semantics::LongLived
+                                                    : Semantics::OneShot;
+}
+
+// The device slots, in the order a user meets them. Iterated rather than
+// hand-listed wherever all four must be handled, so a fifth cannot be added to
+// one site and missed at another.
+inline constexpr Slot kDeviceSlots[] = { Slot::Runner, Slot::Flash,
+                                         Slot::Monitor, Slot::Debug };
+
+// The user-facing name of a device slot: the `mcpp <name>` subcommand, the
+// `[target.<triple>].<name>` key and the `mcpp:<name>=` directive are all this
+// one string, which is why it has a single read point.
+inline constexpr std::string_view device_slot_name(Slot s) {
+    switch (s) {
+        case Slot::Runner:  return "runner";
+        case Slot::Flash:   return "flash";
+        case Slot::Monitor: return "monitor";
+        case Slot::Debug:   return "debug";
+        default:            return {};
+    }
+}
+
 // Who sees the value. The field that must be answered for every new directive.
 enum class Scope {
     PackagePrivate,  // only this package's own TUs — never propagated to consumers
@@ -166,7 +229,7 @@ struct Def {
     int              sinceProtocol;
 };
 
-inline constexpr std::array<Def, 16> kTable{{
+inline constexpr std::array<Def, 20> kTable{{
     //  wire                    tag                  slot                    scope                  transform                must   missingPrefix                 missingSuffix                                    since
     {"cxxflag",             "cxxflag",           Slot::CxxFlags,         Scope::PackagePrivate, Transform::Verbatim,      false, "",                           "",                                              1},
     {"cflag",               "cflag",             Slot::CFlags,           Scope::PackagePrivate, Transform::Verbatim,      false, "",                           "",                                              1},
@@ -212,6 +275,10 @@ inline constexpr std::array<Def, 16> kTable{{
     // OWNER home — measured in CI as `xlings: '…' is not installed` from a job
     // where the same name had answered `--version` two steps earlier.
     {"runner",              "runner",            Slot::Runner,           Scope::RunGlobal,      Transform::Verbatim,      false, "",                           "",                                              4},
+    {"flash",               "flash",             Slot::Flash,            Scope::RunGlobal,      Transform::Verbatim,      false, "",                           "",                                              6},
+    {"monitor",             "monitor",           Slot::Monitor,          Scope::RunGlobal,      Transform::Verbatim,      false, "",                           "",                                              6},
+    {"debug",               "debug",             Slot::Debug,            Scope::RunGlobal,      Transform::Verbatim,      false, "",                           "",                                              6},
+    {"runner-exclusive",    "runner-exclusive",  Slot::RunnerExclusive,  Scope::RunGlobal,      Transform::Verbatim,      false, "",                           "",                                              6},
     {"link-script",         "ldflag",            Slot::LdFlags,          Scope::LinkGlobal,     Transform::LinkerScript,  false, "",                           "",                                              3},
     {"include-dir",         "include-dir",       Slot::IncludeDirs,      Scope::PackagePrivate, Transform::AbsPath,       false, "",                           "",                                              1},
     {"include-dir-after",   "include-dir-after", Slot::IncludeDirsAfter, Scope::PackagePrivate, Transform::AbsPath,       false, "",                           "",                                              1},
@@ -668,13 +735,24 @@ void apply(mcpp::manifest::Manifest& m, const Directives& d) {
     auto const& c        = d.at(Slot::CFlags);
     auto const& ld       = d.at(Slot::LdFlags);
     auto const& runner   = d.at(Slot::Runner);
+    auto const& flash    = d.at(Slot::Flash);
+    auto const& monitor  = d.at(Slot::Monitor);
+    auto const& debugTpl = d.at(Slot::Debug);
     auto const& defines  = d.at(Slot::Defines);
 
     bc.cxxflags.insert(bc.cxxflags.end(), cxx.begin(), cxx.end());
     bc.cflags.insert(bc.cflags.end(), c.begin(), c.end());
     bc.ldflags.insert(bc.ldflags.end(), ld.begin(), ld.end());
     // Appended in emission order — the tokens ARE the argv.
     bc.runner.insert(bc.runner.end(), runner.begin(), runner.end());
+    bc.flash.insert(bc.flash.end(), flash.begin(), flash.end());
+    bc.monitor.insert(bc.monitor.end(), monitor.begin(), monitor.end());
+    bc.debugger.insert(bc.debugger.end(), debugTpl.begin(), debugTpl.end());
+    // ⚠️ ANY non-empty value sets it, and there is deliberately no way to unset
+    // it from a second package. Exclusivity is a claim about the DEVICE: if one
+    // package in the graph knows the target is a mutex, it is one, and a later
+    // package saying nothing must not relax that.
+    if (!d.at(Slot::RunnerExclusive).empty()) bc.runnerExclusive = true;
     // cfg defines colour BOTH language channels — the one slot that fans out.
     bc.cflags.insert(bc.cflags.end(), defines.begin(), defines.end());
     bc.cxxflags.insert(bc.cxxflags.end(), defines.begin(), defines.end());

modules/buildmcpp/src/program_protocol.cppm

@@ -51,7 +51,12 @@ export namespace mcpp::build::program_protocol {
 // COMPILE, because the bundled module that engine ships has no such function.
 // That is the same cost `link-script` carried into v3 and is stated here so
 // the next reader does not look for a protocol path that never runs.
-inline constexpr int kProtocolVersion = 5;
+// v6: adds `flash`, `monitor`, `debug` and `runner-exclusive` — `runner`'s
+// three siblings and the claim that a device admits one user at a time. Same
+// cost as v5's: a package calling `mcpp::flash()` fails on an older engine at
+// the build.mcpp COMPILE, because that engine's bundled module has no such
+// function, not through a protocol refusal.
+inline constexpr int kProtocolVersion = 6;
 
 // ── Cache-format epoch ─────────────────────────────────────────────────────
 //

modules/manifest/src/toml.cppm

@@ -2142,24 +2142,43 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
             // artifact cannot execute here. An ARRAY, so it is neither a
             // scalar (the unknown-key sweep below skips it by type) nor part
             // of the conditional sub-table channel.
-            if (auto it = body.find("runner"); it != body.end()) {
+            //
+            // ⭐ FOUR KEYS, ONE LOOP. `runner` was alone until `flash`,
+            // `monitor` and `debug` joined it, and they are the same key in
+            // every respect a parser can see: an array of strings, empty is an
+            // error, non-strings are an error. Writing the second one out by
+            // hand is how the third and fourth acquire slightly different
+            // diagnostics.
+            struct DeviceKey { std::string_view name; std::vector<std::string> TargetEntry::*into; };
+            static constexpr std::string_view kExample =
+                "[\"qemu-system-riscv64\", \"-kernel\"]";
+            const DeviceKey kDeviceKeys[] = {
+                { "runner",  &TargetEntry::runner  },
+                { "flash",   &TargetEntry::flash   },
+                { "monitor", &TargetEntry::monitor },
+                { "debug",   &TargetEntry::debugger },
+            };
+            for (auto const& dk : kDeviceKeys) {
+                auto it = body.find(std::string(dk.name));
+                if (it == body.end()) continue;
                 if (!it->second.is_array()) {
                     return std::unexpected(error(origin, std::format(
-                        "[target.{}].runner must be an array of strings, "
-                        "e.g. runner = [\"qemu-system-riscv64\", \"-kernel\"]",
-                        triple)));
+                        "[target.{}].{} must be an array of strings, e.g. {} = {}",
+                        triple, dk.name, dk.name, kExample)));
                 }
+                auto& dest = e.*(dk.into);
                 for (auto& el : it->second.as_array()) {
                     if (!el.is_string()) {
                         return std::unexpected(error(origin, std::format(
-                            "[target.{}].runner must contain only strings", triple)));
+                            "[target.{}].{} must contain only strings",
+                            triple, dk.name)));
                     }
-                    e.runner.push_back(el.as_string());
+                    dest.push_back(el.as_string());
                 }
-                if (e.runner.empty()) {
+                if (dest.empty()) {
                     return std::unexpected(error(origin, std::format(
-                        "[target.{}].runner is empty — an empty template would "
-                        "run nothing and report success", triple)));
+                        "[target.{}].{} is empty — an empty template would do "
+                        "nothing and report success", triple, dk.name)));
                 }
             }
 
@@ -2195,7 +2214,9 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
             static constexpr std::string_view kKnownTargetScalars[] = {
                 "cxx_runtime", "linkage", "sysroot", "toolchain",
             };
-            static constexpr std::string_view kKnownTargetArrays[] = { "runner" };
+            static constexpr std::string_view kKnownTargetArrays[] = {
+                "debug", "flash", "monitor", "runner",
+            };
             for (auto& [key, value] : body) {
                 if (value.is_table()) continue;   // the conditional channel
                 const std::span<const std::string_view> known = value.is_array()
@@ -2204,7 +2225,8 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
                 if (std::ranges::find(known, key) != known.end()) continue;
                 m.schemaWarnings.push_back(std::format(
                     "[target.{}] has unsupported key '{}' (ignored). Supported keys: "
-                    "cxx_runtime, linkage, runner, sysroot, toolchain. "
+                    "cxx_runtime, debug, flash, linkage, monitor, runner, sysroot, "
+                    "toolchain. "
                     "Per-role contracts go in [build].cxx_runtime's table form.",
                     triple, key));
             }

modules/manifest/src/types.cppm

@@ -456,6 +456,31 @@ struct BuildConfig : BuildInputs {
     // argv that is neither one's, and it would fail at exec time with no
     // indication of which package contributed which token.
     std::vector<std::string>            runner;
+    // ⭐⭐ THE THREE SIBLINGS OF `runner`, AND WHY THEY ARE SLOTS RATHER THAN
+    // COMMANDS.
+    //
+    // Executing an artifact, writing it to a device, watching what it prints
+    // and attaching a debugger are one shape: an argv that the BOARD knows and
+    // a TOOL performs, addressed by absolute path, with the artifact appended
+    // or substituted for `{}`. `runner` has carried that shape since 2026.8.19;
+    // three special-case commands would have carried it three more times.
+    //
+    // ⚠️ THEY ARE NOT INTERCHANGEABLE, AND THE DIFFERENCE IS THE PROCESS AND
+    // NOT THE ARGV. `run` and `flash` finish and report an exit code; `monitor`
+    // and `debug` do not end on their own, so "the process is still alive" is
+    // success for them and a hang for the other two. That is `Semantics`, which
+    // the engine reads from the slot rather than from the tokens — no argv can
+    // say which of the two it is.
+    std::vector<std::string>            flash;
+    std::vector<std::string>            monitor;
+    std::vector<std::string>            debugger;
+    // ⚠️ ONE BOARD IS A MUTEX, AND NOTHING ELSE IN THE BUILD IS.
+    //
+    // `mcpp test` runs test binaries on a pool of workers. An emulator takes
+    // N instances happily; a physical board takes one, and two probes reaching
+    // for the same device do not fail — they interleave. The board knows this
+    // about itself, so it says so, and a project never has to remember `-j1`.
+    bool                                runnerExclusive = false;
 
     // Was `sources` WRITTEN, as opposed to merely being empty?
     //
@@ -819,6 +844,13 @@ struct TargetEntry {
     // engine a different board has to fight. The artifact path is appended, or
     // substituted for `{}` when the template contains it.
     std::vector<std::string>            runner;
+    // The project's override for each of `runner`'s siblings, on the same axis
+    // and with the same precedence: what the author of THIS project wrote beats
+    // what a dependency supplied, and the override is reported rather than
+    // applied in silence.
+    std::vector<std::string>            flash;
+    std::vector<std::string>            monitor;
+    std::vector<std::string>            debugger;
     // #336 — per-target C++ runtime contract, same vocabulary as
     // [build].cxx_runtime and overriding it for this triple. It lives HERE,
     // beside `linkage`, rather than in the `cfg(...)` conditional channel: