tan-cli 0.7.0__py3-none-any.whl

tan/commands/build_cmd.py

@@ -0,0 +1,2236 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`tan build` -- the one command that turns a build plan into firmware.
+
+Composition, not logic: this module resolves the project, ACQUIRES a plan (from
+`--plan-from`, else by running the planner in-process -- there is no other way any
+more; see `_emit_plan`), then hands it in turn to the four sub-project-1
+libraries -- `parse_build_plan`, `apply_plan_token_substitution`,
+`materialise_plan`, `execute_slices` -- and
+folds the result into one envelope. Every decision those modules own stays
+theirs; what lives here is the ORDER they run in, the mapping from their
+`(code, message)` failures to an exit code, and the guarantee that not one of
+them can escape as a traceback.
+
+Three properties this file exists to hold:
+
+**Order is the contract (I-20).** `materialise_plan` writes every
+`sharedArtefacts` entry AND every slice's `configArtefacts` before
+`execute_slices` is called at all. The plan carries no `sequential` flag and
+no `inputHash`; the only thing making its slices independent is that all their
+inputs are on disk before the first one starts. `tests/commands/
+test_build_command.py` proves it by making the first slice's own command
+assert the OTHER slice's config artefact already exists.
+
+**Nothing but the envelope on stdout.** Slice output streams to stderr (see
+`_stream`), the text-mode recap goes to stderr, and the JSON envelope is the
+only thing ever written to stdout. The extension parses stdout whole; one
+stray byte and it renders nothing, with no error on either side.
+
+**`--plan-from` is a plan SOURCE, not a build trigger (v0.4.1 §gate).** The
+oracle's `--plan-from` help says "Implies `--plan`", and measured against the
+shipped `tan 0.4.1-dev` binary in fresh temp dirs, on
+`tests/parity/oracle/multicore_rpmsg-aen.build-plan.json`, it means it -- even
+against an EXPLICIT `--native`::
+
+    build --plan-from p.json                -> rc 0, 0 files, data = the plan
+    build --plan-from p.json --native       -> rc 0, 0 files, data = the plan
+    build --plan-from p.json --materialise  -> rc 0, 6 files,
+                                               data = {schemaVersion, baseDir, written}
+
+All three are reproduced here exactly (`_MODE_PLAN` / `_MODE_MATERIALISE`),
+`--native` included. Two earlier revisions of this file each redefined one of
+those argvs -- a bare `--plan-from` used to materialise AND dispatch, and then
+`--plan-from --native` did -- so a v0.4.1 script that only ever INSPECTED a
+plan silently began writing six files into its own tree. Changing what a
+v0.4.1 argv MEANS is the whole surprise this gate exists to remove.
+
+**`--execute` is a deliberate PORT ADDITION the oracle has no flag for.**
+Taking a pinned, reviewed plan file and running it reproducibly is a normal
+hermetic-CI request; v0.4.1's inability to do it is a LIMITATION of that CLI,
+not a contract worth preserving -- there `--plan-from`'s implied `--plan`
+outranks `--native`, so a file-supplied plan cannot be dispatched at all.
+`--execute` supplies exactly that capability without changing what any v0.4.1
+argv means. It is not a parity bug and not a test hook: a future reader who
+"fixes" it by deleting it removes a supported capability. Its `data` is the
+ORDINARY build shape -- `{schemaVersion, baseDir, slices[], warnings[]}` --
+because it IS a native build and only the plan's SOURCE differs; `written` is
+deliberately omitted, being byte-for-byte the pinned plan's own declared
+artefact paths, which the one caller who has that file already holds. A
+conflicting combination is refused with its own code, never resolved by silent
+precedence (`--execute --materialise` -> `build.conflicting-flags`, exit 2;
+`--pristine` with a mode that never dispatches (bare `--plan-from` or
+`--materialise`, neither paired with `--execute`) -> the same
+`build.conflicting-flags`, exit 2, because a wipe promised on the envelope
+cannot be silently skipped either; `--execute` with a RETIRED flag ->
+`build.flag-retired`, exit 2, because a flag this build refuses outright
+cannot be honoured either way).
+`--execute` is ADDED BY THIS PORT, not a v0.4.1 flag: there `--plan-from`
+implies `--plan` and outranks `--native`, so a file-supplied plan cannot be
+dispatched at all. Deliberate, not a parity gap. `--native` keeps v0.4.1's
+behaviour of NOT overriding the `--plan` that `--plan-from` implies, which
+`test_plan_from_shows_the_plan_and_writes_nothing_even_with_native` pins.
+
+**The OS is not an option (I-01/I-02).** There is deliberately no `--os` and
+no `--backend` flag. A core's runtime is derived from its Cortex class by the
+planner (`tan/planner/topology.py`), and `slices[].backend`
+arrives already resolved. Nor does this command filter the plan's slices: a
+one-core `board.yaml` legitimately plans three (I-04), and "helpfully"
+dropping the ones the customer did not name is how a Yocto slice silently
+stops being built.
+"""
+import json
+import os
+import sys
+import threading
+import time
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+import typer
+
+from tan.commands.build.execute import (
+    KNOWN_BACKENDS,
+    SliceOutcome,
+    execute_slices,
+    last_configure_cache_issues,
+    last_manifest_write_failure,
+    last_sdk_switch_issues,
+    reset_last_manifest_write,
+)
+from tan.commands.build.materialise import MaterialiseError, materialise_plan
+from tan.commands.build.token_substitution import (
+    TokenSubstitutionError,
+    apply_plan_token_substitution,
+    deferred_placeholder_issues,
+)
+from tan.commands.build.workspace_patches import workspace_patch_issues
+from tan.commands.build.toolchain import ToolchainResolution, resolve_toolchain_root
+from tan.core.user_defines import UserDefineError, apply_user_defines, define_pairs, user_defines_problem
+from tan.core.board_files import all_topology_boards, unmatched_board_file_messages
+from tan.core.plain_zephyr_plan import board_target_problem, normalise_defines, plain_zephyr_plan
+from tan.core.build_plan import BuildPlan, PlanParseError, parse_build_plan
+from tan.core.global_flags import accept_global_flags
+from tan.core.link_refusal import refusal_code
+from tan.core.plan_exec import (
+    CROSS_DRIVE_MSG,
+    MISSING_TOOL_RE,
+    PolicyAction,
+    normalize_path,
+    resolve_action,
+)
+from tan.core.west_workspace_refusal import WORKSPACE_UNRESOLVED_MSG
+from tan.commands.build.host_python import refusal_message, resolve_build_python
+from tan.core.plan_tokens import TOKEN_TOOLCHAIN_ROOT, DeferredPlaceholder
+from tan.core.sdk_discovery import (
+    _abs_posix,
+    global_default_foreign_project_issue,
+    project_pin_issue,
+    resolve_sdk_root_ladder,
+    sdk_ladder_divergence_issue,
+    with_sdk_search,
+)
+from tan.core.shapes import SDK_MARKER, is_sdk_root, rejected_sdk_root_message
+from tan.env import stderr_is_tty, terminal_width
+from tan.envelope import Envelope, Issue, Project, SdkInfo, emit
+from tan.exit_codes import ExitCode
+from tan.output_format import FORMAT_HELP, OutputFormat
+
+#: `scripts/alp_project.py` is THE marker for an alp-sdk checkout -- the same
+#: literal `tan_core::project` hardcodes (I-31). Renaming or relocating it
+#: breaks every `--sdk-root` resolution in the CLI, so it is spelled once --
+#: in `tan.core.shapes` since tan-cli#408. The import below re-exports it
+#: here because a dozen modules already reach it through this one.
+
+#: Envelope `data.slices[].status`, from `SliceOutcome.status`. The wire
+#: vocabulary is the Rust one (`ok` / `skipped` / `failed`), NOT the executor's
+#: internal spelling -- `succeeded` on the wire would break a consumer written
+#: against the shipped binary. `cancelled` is unreachable from this command
+#: (nothing here supplies a cancellation source) but maps to `failed` rather
+#: than falling through to a KeyError if one is ever wired up.
+_WIRE_STATUS = {"succeeded": "ok", "skipped": "skipped"}
+
+#: What this run does with the plan it acquires -- the oracle's own precedence,
+#: measured flag-combination by flag-combination against `target/debug/tan.exe`
+#: on the AEN fixture: `--materialise` outranks everything (`--plan-from
+#: --materialise --native` -> six files, `written` shape), the `--plan` implied
+#: by `--plan-from` outranks even an explicit `--native` (`--plan-from
+#: --native` -> the plan, zero files), and only a run naming NEITHER plan-mode
+#: flag builds. `_MODE_NATIVE` is therefore both the default and what the
+#: port-added `--execute` selects -- deliberately the SAME mode, so `--execute`
+#: reports the same `data` shape a plain `tan build` does rather than a fourth
+#: one no consumer is written for.
+_MODE_PLAN = "plan"
+_MODE_MATERIALISE = "materialise"
+_MODE_NATIVE = "native"
+
+#: The ONE top-level directory name a plan's `buildRoot` may name (tan-cli#566),
+#: `tan_core::build_plan::CONSUMER_BUILD_ROOT` in the oracle. Duplicated from
+#: `tan.commands.build.execute._CONSUMER_BUILD_ROOT` rather than imported, for
+#: the reason that module's own copy already records: it is the SDK build-plan
+#: schema's constant, not a value derived from anything in either module, and
+#: the two uses are unrelated (that one gates the sdk-switch-pristine wipe on a
+#: slice's plan-supplied `cwd`; this one refuses the whole plan). Importing a
+#: neighbour's underscore-private name to save four characters would couple
+#: this refusal to that guard's internals.
+CONSUMER_BUILD_ROOT = "build"
+
+#: tan-cli#427 resolved every flag `tan build` used to lump into one
+#: refuse-everything tuple, ONE of three ways:
+#:
+#: 1. **Implemented for real** -- `--pristine` (see
+#:    `_maybe_pristine_stale_sdk_build_dir`'s `force_pristine`) and the
+#:    `--target`/`--all`/`--verbose`/`--quiet`/`--no-color`/
+#:    `--non-interactive`/`--ci` septet, which the oracle's own `cli.rs`
+#:    declares ONLY on the shared `GlobalArgs` struct (`BuildArgs` itself has
+#:    no fields for any of the seven) -- `build`'s Rust handler never reads
+#:    them either, so accept-and-drop via `accept_global_flags` (see the
+#:    bottom of this module) is not a narrower stand-in, it is the SAME
+#:    oracle behaviour every other command already gets from that decorator.
+#:    This also settles the "does `--target`/`--all` on `build` mean
+#:    `generate`'s emit-backend selection" question the issue raised: it does
+#:    not mean anything on either binary -- `generate`'s own handler is the
+#:    only one that ever reads the global field, so build and generate
+#:    sharing the spelling was never a meaning collision to resolve.
+#: 2. **Retired as superseded** -- `--plan`, `--manifest`, `--manifest-from`:
+#:    see `_RETIRED_FLAGS` below. Still declared (never a Click parse error),
+#:    but refused with `build.flag-retired`, which names the replacement in
+#:    the message itself.
+#: 3. **Nothing is left deferred.** `--no-auto-bootstrap` was the last one,
+#:    and it is now retired (bucket 2) rather than implemented, on a
+#:    maintainer decision closing tan-cli#427: `tan build` does not run
+#:    `tan bootstrap` implicitly and is not going to. Measured before
+#:    deciding -- no call path from `build` or `run` reaches bootstrap;
+#:    an unbootstrapped workspace surfaces as `build.plan-unavailable`
+#:    (`_emit_plan`'s `SystemExit` catch), never an automatic invocation.
+#:    So there was never a trigger for the flag to disable, and building one
+#:    just to give the flag something to switch off would add a heavy
+#:    implicit side effect (a `west update` and a venv install) to a command
+#:    whose job is to build. A flag that disables a behaviour this CLI does
+#:    not have is not deferred work -- it is a flag with nothing to mean, so
+#:    it teaches the explicit command instead.
+
+#: The oracle spelling -> its replacement flag, for the three flags
+#: `_refuse_retired` reports (tan-cli#427): "Two overlapping plan surfaces is
+#: worse than one, so the oracle spellings go" (the issue's own maintainer
+#: decision), but a retired flag's error must TEACH the replacement, not just
+#: refuse -- a customer who typed `--plan` is told to type `--plan-from`, in
+#: the message itself, never pointed at a tracker to work it out.
+#:
+#: `--plan` (bare, live-fetched) has no direct one-flag substitute -- `
+#: --plan-from FILE` covers the file-sourced half of what it did, with
+#: `--materialise`/`--execute` covering the act-on-it half; there is no
+#: "preview the live plan and stop" mode left, which is the trade the
+#: decision accepts in exchange for one plan surface instead of two.
+#: `--manifest`/`--manifest-from` showed `build/system-manifest.yaml`
+#: (a DIFFERENT artefact from the build plan) before or without a real
+#: build; a native `tan build` already writes that exact file, and it is
+#: plain YAML a caller can read directly -- no second command needed.
+_RETIRED_FLAGS: dict[str, str] = {
+    "--plan": (
+        "`--plan` is retired: run `tan build --plan-from FILE` to inspect a build plan "
+        "instead (add `--materialise` or `--execute` to act on it)."
+    ),
+    "--manifest": (
+        "`--manifest` is retired: a native `tan build` already writes "
+        "`build/system-manifest.yaml` for you to read directly -- no separate flag needed."
+    ),
+    "--manifest-from": (
+        "`--manifest-from FILE` is retired: `system-manifest.yaml` is plain YAML -- open "
+        "FILE directly instead of routing it through `tan build`."
+    ),
+    # Retired rather than implemented (tan-cli#427): there is no implicit
+    # bootstrap for it to switch off, and there is not going to be one, so the
+    # message teaches the explicit command rather than describing a toggle.
+    "--no-auto-bootstrap": (
+        "`--no-auto-bootstrap` is retired: `tan build` never bootstraps implicitly, so "
+        "there is nothing for it to disable -- run `tan bootstrap` yourself when a "
+        "workspace needs preparing."
+    ),
+}
+
+
+class BuildError(Exception):
+    """A build failure with its issue code and exit code already decided --
+    the shape every step in `_build` reports through, so the caller never has
+    to guess a code from an exception type."""
+
+    def __init__(self, code: str, message: str, exit_code: ExitCode) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.exit_code = exit_code
+
+
+def _stream(line: str) -> None:
+    """Slice output goes to stderr -- ALWAYS, both formats. stdout is the
+    envelope channel and carries nothing else; stderr carries no contract at
+    all, so there is nothing to keep separate between the two modes."""
+    print(line, file=sys.stderr, flush=True)
+
+
+#: Idle time -- since the last line ANY slice printed, or since dispatch
+#: began if none has arrived yet -- before [`_Heartbeat`] starts announcing
+#: it is still alive. Measured against tan-cli#287: a first-build CMake
+#: configure sat fully silent for 234.2s; a warm-cache rebuild (21.1s) prints
+#: output throughout and never crosses this. Short enough to catch the
+#: former, long enough that ordinary tool-startup chatter never trips it.
+_HEARTBEAT_SILENCE_THRESHOLD_S = 5.0
+#: Refresh cadence once armed -- a live, in-place counter (`\r`, no
+#: trailing newline), not a growing log.
+_HEARTBEAT_TICK_S = 1.0
+#: `tan.env.terminal_width`'s fallback when stderr's column count can't be
+#: read at all. Should not be reachable -- `_Heartbeat` is only ever armed
+#: behind an `isatty()` gate -- but naming a value here is still cheaper
+#: than trusting that gate never has a gap.
+_HEARTBEAT_WIDTH_FALLBACK = 80
+
+
+def _heartbeat_line_width() -> int:
+    """Usable columns for one self-overwriting heartbeat line: the
+    terminal's own width, minus one.
+
+    tan-cli#287 blocker: the erase pad used to be a HARDCODED 88 columns
+    while the message it erased ran 114+ chars (more once elapsed hits
+    1000s). On a terminal narrower than 114 columns -- 80 is the common
+    case -- `\r` rewinds only the terminal's OWN last row, so a message
+    that wraps grows a fresh row every tick instead of overwriting one:
+    ~234 stacked "still building" rows over the measured 234.2s configure.
+    Sizing the message AND its erase pad off the actual terminal width,
+    every tick, removes the mismatch instead of guessing a bigger constant.
+    The `- 1` leaves the last column unwritten: filling a line to the exact
+    terminal width is what triggers autowrap on many terminals, which would
+    make the fix for the wrap defect one more way to trigger it.
+
+    tan-cli#564: measured through [`terminal_width`], which reads stderr's own
+    fd -- the handle the heartbeat is armed on and writes to. The previous
+    `shutil.get_terminal_size` call resolved `sys.__stdout__` instead, so
+    `tan build > log.txt` on that same 70-column terminal returned 79 rather
+    than 69 and `_tick`'s `message.ljust(width)` wrote a 79-char row onto a
+    70-column screen: it soft-wraps, `\r` rewinds only the last physical row,
+    and the "still building" line stacks a fresh row per tick -- exactly the
+    tan-cli#287 defect this width computation was added to remove.
+
+    # ponytail: re-reads the width every tick rather than caching it, so a
+    # terminal resized mid-build can leave a stale tick's tail past the
+    # newly narrower edge; not the reported defect (a STATIC undersized
+    # pad on an unchanged terminal) and not measured here -- revisit if a
+    # resize-mid-build report ever lands.
+    """
+    columns = terminal_width(_HEARTBEAT_WIDTH_FALLBACK)
+    return max(columns - 1, 1)
+
+
+class _Heartbeat:
+    """The `on_output` callback `_dispatch` constructs and hands
+    `execute_slices` directly: relays every line to [`_stream`] like
+    before, and -- TTY + text-mode only -- prints a single self-overwriting
+    "still building" line once the child has gone quiet for
+    `_HEARTBEAT_SILENCE_THRESHOLD_S` (tan-cli#287: a four-minute silent
+    CMake configure read as a hang with nothing to say otherwise). The
+    instant real output resumes, the line is blanked so it never mixes
+    with the stream it was standing in for.
+
+    Armed by [`_dispatch`] itself, not handed down by its caller: `_build`'s
+    two callers -- `build_cmd.build` and `run_cmd._run` -- both
+    bottleneck through `_dispatch` before any slice runs, so constructing
+    the heartbeat there covers `tan run`'s identical silent-CMake window
+    too, not just a direct `tan build` (tan-cli#287 follow-up).
+
+    `execute_slices` calls `on_output` once per line and has no hook for
+    "a slice started" or "configure ended, compile began" -- adding one
+    would mean editing `tan.commands.build.execute`, outside this file's
+    scope -- so this cannot name PHASES, only measure silence across the
+    whole dispatch and say tan is still alive.
+
+    # ponytail: one wall-clock timer for the whole dispatch, not a per-slice
+    # or per-phase one -- upgrade to a per-slice "building <core>" line if
+    # `execute_slices` ever grows a slice-start hook.
+
+    A disabled instance (`enabled=False` -- not a TTY, or `--format json`)
+    still relays every line via `__call__`, but never starts its thread and
+    so never prints anything of its own: behaviourally identical to passing
+    `_stream` straight through."""
+
+    def __init__(self, enabled: bool) -> None:
+        self._enabled = enabled
+        self._start = time.monotonic()
+        self._last_output = self._start
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._line_up = False
+
+    def __call__(self, line: str) -> None:
+        # Clear any live heartbeat line FIRST -- `_stream`'s `print` commits
+        # a trailing newline, so blanking AFTER it would scroll the
+        # heartbeat text away merged onto the same line as real output
+        # instead of erasing it.
+        self.note_output()
+        _stream(line)
+
+    def note_output(self) -> None:
+        with self._lock:
+            self._last_output = time.monotonic()
+            self._clear_locked()
+
+    def _clear_locked(self) -> None:
+        if self._line_up:
+            width = _heartbeat_line_width()
+            print("\r" + " " * width + "\r", end="", file=sys.stderr, flush=True)
+            self._line_up = False
+
+    def _tick(self) -> None:
+        while not self._stop.wait(_HEARTBEAT_TICK_S):
+            with self._lock:
+                idle = time.monotonic() - self._last_output
+                if idle < _HEARTBEAT_SILENCE_THRESHOLD_S:
+                    continue
+                elapsed = time.monotonic() - self._start
+                width = _heartbeat_line_width()
+                # Truncated AND right-padded to `width`, both to the SAME
+                # value: truncation keeps this tick's own text off the
+                # terminal's last column (see `_heartbeat_line_width`), and
+                # the pad overwrites a longer PRIOR tick's tail (elapsed/
+                # idle growing from single to double digits, say) -- both
+                # ticks compute the same width, so the pad always covers it
+                # on an unchanged terminal.
+                message = (
+                    f"... still building ({elapsed:.0f}s elapsed, no output for "
+                    f"{idle:.0f}s -- CMake configure can take several minutes on a "
+                    "first build)"
+                )[:width]
+                print("\r" + message.ljust(width), end="", file=sys.stderr, flush=True)
+                self._line_up = True
+
+    def __enter__(self) -> "_Heartbeat":
+        if self._enabled:
+            self._thread = threading.Thread(target=self._tick, daemon=True)
+            self._thread.start()
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=_HEARTBEAT_TICK_S * 2)
+        with self._lock:
+            self._clear_locked()
+
+
+def _emit_plan(sdk_root: str | None, board_yaml: str | None) -> str:
+    """Plan `board_yaml` against the SDK at `sdk_root`.
+
+    IN-PROCESS, always. `tan.planner_root.emit` binds the SDK root -- which is
+    where `metadata/**` and the fact-reader modules still live (ADR-0017) -- and
+    renders through the same `emit_artefact` dispatch `python -m tan.planner`
+    uses. No interpreter on PATH, no PYTHONPATH, and nothing under
+    `<sdk>/scripts` imported or spawned -- but NOT "no process" full stop:
+    `emit_build_plan` still spawns a short-lived `git rev-parse` (a stamped
+    `sdkCommit`, `buildplan.py:339-372`) whenever `git` resolves on PATH; with
+    none, it returns `None` first and the plan carries `sdkCommit: null`.
+
+    **The `<python> -m alp_orchestrate --emit build-plan` fallback was RETIRED
+    here, deliberately.** It fired when this build of `tan` could not import the
+    planner and quietly planned through the SDK's own copy instead -- and it
+    reported nothing at all when it did. Three reasons it had to go, any one
+    sufficient:
+
+    * It was SILENT. A run that fell back looked exactly like a run that did
+      not, which is the same defect class that let the planner relocation be
+      believed before it happened.
+    * It could only fire on a broken install. `jsonschema` and `PyYAML` are
+      declared `dependencies` in `pyproject.toml` and installed into the clean
+      venv `scripts/build_binary.sh` freezes, so the trigger is not a supported
+      layout -- and a missing dependency deserves `pip install jsonschema`, not
+      a different planner.
+    * It kept alp-sdk's `scripts/alp_orchestrate/` load-bearing forever. As long
+      as any tan path can reach it, it can never be deleted, and deleting it is
+      the point.
+
+    What replaces it is a coded refusal naming the missing dependency -- which is
+    strictly more actionable than a silent success against a second planner whose
+    version nothing checks.
+    """
+    if sdk_root is None:
+        raise BuildError(
+            "build.plan-unavailable",
+            "no alp-sdk checkout found -- pass `--sdk-root <PATH>` or run from a project "
+            "beside one. Planning reads the SDK's `metadata/**`. Run `tan doctor` to see "
+            "which checkout tan resolves, if any.",
+            ExitCode.RUNTIME_FAILURE,
+        )
+    if board_yaml is None:
+        raise BuildError(
+            "build.plan-unavailable",
+            "no board.yaml found -- pass `--board-yaml <PATH>` or run from a project; "
+            "for a plain Zephyr example without a board.yaml (alp-sdk's bench examples), "
+            "pass `--board <zephyr-board-target>` instead. "
+            "Run `tan init` to create a project, or `tan examples` to list ready-made ones.",
+            ExitCode.RUNTIME_FAILURE,
+        )
+    # `--sdk-root` is terminal and returned as-is even when wrong (I-31), so the
+    # first thing planning reads is checked here rather than surfacing as a
+    # loader stack trace. The board schema, not the planner: the planner is ours
+    # now, and requiring the SDK to still carry `alp_orchestrate` would refuse
+    # precisely the releases this relocation exists to enable.
+    if not (Path(sdk_root) / "metadata" / "schemas" / "board.schema.json").is_file():
+        raise BuildError(
+            "build.plan-unavailable",
+            f"the SDK at `{sdk_root}` has no `metadata/schemas/board.schema.json` -- "
+            f"that path is not an alp-sdk checkout, or the checkout is incomplete.",
+            ExitCode.RUNTIME_FAILURE,
+        )
+
+    try:
+        from tan.planner_root import emit as _plan_emit
+    except ImportError as err:  # pragma: no cover -- planner absent from this build
+        raise BuildError(
+            "build.plan-unavailable",
+            f"this build of `tan` cannot import its own planner ({err}). "
+            "Reinstall it, or install the planner's dependencies "
+            "(`pip install pyyaml jsonschema`).",
+            ExitCode.RUNTIME_FAILURE,
+        ) from err
+    try:
+        return _plan_emit("build-plan", root=sdk_root, board_yaml=Path(board_yaml))
+    except ImportError as err:
+        # A planner dependency (`jsonschema`, `PyYAML`) is missing from THIS
+        # build. Named, not worked around: see the docstring on why the
+        # spawn-the-SDK's-planner fallback was retired.
+        raise BuildError(
+            "build.plan-unavailable",
+            f"the planner could not be imported ({err}) -- install its "
+            "dependencies (`pip install pyyaml jsonschema`) or reinstall `tan`.",
+            ExitCode.RUNTIME_FAILURE,
+        ) from err
+    except SystemExit as err:
+        # `tan.planner.loader` / `kconfig_symbols` call `sys.exit()` on a missing
+        # dependency or an unbootstrapped Zephyr workspace. In a subprocess that
+        # was a non-zero rc; in-process it would tear down the whole CLI past
+        # every envelope guarantee.
+        raise BuildError(
+            "build.plan-unavailable",
+            f"the build-plan emit exited early (code {err.code}).",
+            ExitCode.RUNTIME_FAILURE,
+        ) from err
+    except Exception as err:
+        # `diagnostics.link: itcm` refused (tan-cli#1350): a board.yaml input
+        # error with its own code, not a planner fault. Recognised by its code
+        # (`refusal_code`), not its class: the planner needs a bound SDK root
+        # to import.
+        if refusal_code(err) is not None:
+            raise BuildError(err.code, str(err), ExitCode.VALIDATION_FAILURE) from err
+        # Every planner failure is an envelope, never a traceback -- the same
+        # thing the subprocess boundary used to buy for free. Includes the bare
+        # `ValueError`s the Ethos-U sizing path still raises (I-48).
+        raise BuildError(
+            "build.plan-unavailable",
+            f"the build-plan emit failed: {type(err).__name__}: {err}",
+            ExitCode.RUNTIME_FAILURE,
+        ) from err
+
+
+def _acquire_plan(
+    plan_from: str | None, sdk_root: str | None, board_yaml: str | None
+) -> tuple[str, BuildPlan]:
+    """`(source text, parsed plan)`. The TEXT comes back too because
+    `_MODE_PLAN` echoes it: the oracle's plan output is a raw passthrough, not
+    a round-trip through its own structs -- measured by adding an unknown
+    top-level key to the fixture, which survives verbatim into `data`. Echoing
+    a re-serialised `BuildPlan` would silently drop exactly the forward-compat
+    keys a newer SDK adds, which is the drift the version-skew guard exists to
+    make loud."""
+    if plan_from is not None:
+        try:
+            text = Path(plan_from).read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as err:
+            # UnicodeDecodeError is a ValueError, NOT an OSError, so `except
+            # OSError` alone let it fall through to the catch-all and report a
+            # bad INPUT as a tan bug (`build.internal-failure`, exit 5).
+            # Reachable on the exact flow `--plan-from` exists for: `tan build
+            # --plan --format json > plan.json` in Windows PowerShell 5.1
+            # writes UTF-16LE, and this is the replay half of that
+            # capture-then-replay loop.
+            raise BuildError(
+                "build.plan-unavailable",
+                f"failed to read plan file `{plan_from}`: {err}",
+                ExitCode.RUNTIME_FAILURE,
+            ) from err
+    else:
+        text = _emit_plan(sdk_root, board_yaml)
+
+    try:
+        return text, parse_build_plan(text)
+    except PlanParseError as err:
+        # Exit 1, NOT 2. A malformed plan reads like a validation failure and
+        # the semantic pull toward `ValidationFailure` is real -- but the
+        # shipped binary reports RuntimeFailure here
+        # (`crates/tan-cli/src/commands/build/plan_modes.rs:140-146` and
+        # `native.rs:110-116` both call `plan_error_run(..., "build.plan-
+        # invalid", ..., ExitCode::RuntimeFailure)`), and the exit ladder is a
+        # frozen contract. The consumer makes it worse than cosmetic:
+        # `alp-sdk-vscode/src/alpCli/service.ts:253-259` renders exit 2 as
+        # `severity: "warning"` and exit 1 as `"error"`, so "2" would downgrade
+        # a plan that will not parse -- a hard failure -- to a yellow banner.
+        # 2 stays for a genuine validation failure in Rust's own terms, e.g.
+        # `validate`'s schema violation, whose fixture pins exit 2.
+        raise BuildError(err.code, err.message, ExitCode.RUNTIME_FAILURE) from err
+
+
+def _slice_result(core_id: str, backend: str, outcome: SliceOutcome) -> dict:
+    """One `data.slices[]` entry. `rc`/`reason` are OMITTED when absent, not
+    null -- Rust's `skip_serializing_if = "Option::is_none"`.
+
+    `resolvedTool` is the ONE exception to that rule (tan-cli#510 review,
+    MAJOR 1): a NEW, additive field, ALWAYS present -- `null` rather than
+    omitted when [`SliceOutcome.resolved_tool`] is `None` -- because unlike
+    `rc`/`reason` it has no Rust oracle counterpart to mirror
+    `skip_serializing_if` against; a consumer that wants to know which
+    binary actually ran should not need to distinguish "the key is absent"
+    from "nothing to report" for a field this port alone defines. Never
+    folded into `reason`: that field is also the persisted
+    `system-manifest.yaml` `slices[].reason` (`_write_manifest_after_dispatch`
+    in `build/execute.py`), whose alp-sdk-owned schema defines it as "why a
+    slice was skipped/failed" -- a resolved path is neither."""
+    result = {
+        "coreId": core_id,
+        "backend": backend,
+        "status": _WIRE_STATUS.get(outcome.status, "failed"),
+        "resolvedTool": outcome.resolved_tool,
+    }
+    if outcome.exit_code is not None:
+        result["rc"] = outcome.exit_code
+    if outcome.message is not None:
+        result["reason"] = outcome.message
+    return result
+
+
+def _dispatch(
+    plan: BuildPlan,
+    demotions,
+    build_root: Path,
+    sdk_root: str | None,
+    sdk_root_for_stamp: str | None,
+    *,
+    json_mode: bool = False,
+    pristine: bool = False,
+    slice_refusals: dict[str, str] | None = None,
+    user_defines: dict[str, list[str]] | None = None,
+) -> tuple[list[SliceOutcome], list[Issue]]:
+    """Run the plan's slices, holding back the ones token substitution demoted
+    -- and, since tan-cli#483, the ones whose `cores.<id>.app` resolved to a
+    directory that does not exist ([`_missing_app_dirs`]) -- both HELD
+    per-slice, matching the same per-slice fail/skip shape
+    `execute_slices`'s own unknown-backend/missing-tool checks already use,
+    rather than refusing the whole plan over one bad core: a two-core project
+    with one good `app:` and one bad one still builds the good core.
+
+    Arms its own [`_Heartbeat`] around the dispatch (tan-cli#287), rather
+    than taking one from the caller: `execute_slices` (below) is a single,
+    EAGER call that can run for minutes -- the loop after it only walks
+    results `execute_slices` already computed -- and this function is the
+    one seam every route into the build engine shares. `_build`'s two
+    callers, `build_cmd.build` (`tan build`) and `run_cmd._run`
+    (`tan run`), both bottleneck through here before any slice runs, so
+    arming the heartbeat at THIS level, not one up, is what covers `tan
+    run`'s identical silent-CMake window too -- the gap the previous
+    revision (a `_Heartbeat` built in `build()` and threaded down as
+    `on_output`) left, since `run_cmd.py:267` calls `_build` with no
+    `on_output` of its own.
+
+    `json_mode` is the one thing this function cannot discover for itself
+    (`sys.stderr.isatty()` it checks directly, same as `build()` used to).
+    `build()` passes its real value straight through. `run_cmd._run` takes
+    its own `json_mode` parameter but does not yet thread it into this call
+    (out of this file's scope to add -- see `run_cmd.py:267`), so its call
+    keeps the default `False`.
+
+    tan-cli#488 round 5 class sweep: `sys.stderr` can be `None` -- a process
+    launched with its standard handles detached (a GUI launcher, a
+    `pythonw`-style spawn, or a shell that closed fd 2 before exec) -- the
+    same condition `tan.core.consent.can_prompt` guards against. A bare
+    `sys.stderr.isatty()` here raised the identical `AttributeError:
+    'NoneType' object has no attribute 'isatty'` for a detached-stdio
+    `tan build`/`tan run`, caught only by `build()`'s own outer `except
+    Exception` and reported as a fabricated `build.internal-failure` instead
+    of simply running with the heartbeat disabled.
+
+    tan-cli#488 round 6: the round-5 fix only added `sys.stderr is not
+    None` in front of the same bare `.isatty()` call -- which stops a
+    `None` stderr from crashing this line, but not a stderr that EXISTS and
+    simply has no `.isatty()` method at all. `tan.cli.main` installs exactly
+    that shape under `--format json`: `sys.stderr` becomes `_TeeStderr`
+    (`cli.py`'s tee, `write`/`flush`/`getvalue` only, no `isatty`), which is
+    not `None`, so round 5's guard let the call through and
+    `run_cmd._run` -> `_build` -> here crashed with `AttributeError:
+    '_TeeStderr' object has no attribute 'isatty'` on every `tan run
+    --format json` -- exit 5, `run.internal-failure`, before a single slice
+    ever dispatched (measured against the real binary). This is the exact
+    condition `tan.env.stderr_is_tty` already exists to guard (tan-cli#288)
+    and `use_color`/`wrap_width` already share -- a `None` check does not
+    cover a stream that exists but lacks the method, which is the whole
+    class this line, `tan.core.consent.can_prompt` and `doctor_cmd.
+    fix_suppressed_issue` all shared the same wrong shape for. Now routed
+    through the one shared probe instead of a fourth hand-rolled copy.
+    # ponytail: the one live gap this leaves -- `tan run --format json` with
+    # a REAL terminal still attached to stderr would arm the heartbeat where
+    # it should stay silent (`run_cmd._run` does not thread its own
+    # `json_mode` into `_build`, so `_dispatch` always sees the default
+    # `False` on that path -- see `run_cmd.py:267`). stdout (the envelope
+    # channel) is untouched either way, and the crash this round fixes is
+    # closed regardless of `json_mode`'s value, since `stderr_is_tty()` is
+    # false for a `_TeeStderr` on its own merits; threading `json_mode`
+    # through `run_cmd._run` is a separate, narrower polish left for its own
+    # change, out of this file's scope to add.
+
+    A demoted slice still names a literal `${TOOLCHAIN_ROOT}` in its own
+    fields because this host resolved no toolchain. `execute_slices` does not
+    know about demotions, so dispatching one would spawn a command with an
+    unsubstituted token in its argv -- a silent wrong-path build, the exact
+    failure I-29 says a naive substitution reintroduces. Instead the demotion
+    is routed to `executionPolicy.missingTool` (default skip) here, which is
+    the seam the Rust executor uses for it too: it is a host-provisioning
+    fact, not a plan bug.
+
+    Precedence is preserved: a demoted slice that ALSO names an unknown
+    backend or carries no command is left to `execute_slices`, because both of
+    those outrank a provisioning fact and are checked first there.
+
+    `pristine` (`tan build --pristine`, tan-cli#427) is threaded straight
+    through to `execute_slices`'s own `force_pristine` -- see that
+    function's docstring, and `_maybe_pristine_stale_sdk_build_dir`'s, for
+    the wipe/suppression decision it makes per slice.
+
+    `sdk_root` is threaded straight through to `execute_slices` -- it is
+    THIS run's already-resolved `--sdk-root`/discovered checkout (`_build`'s
+    own parameter), the identity `execute_slices`'s sdk-switch-pristine guard
+    (issue #52) keys its stamp comparison on. Without it every stamp
+    comparison degrades to "unresolved", which never wipes anything -- see
+    `tan.core.plan_exec.sdk_stamp_key`. `sdk_root_for_stamp` is the SAME
+    checkout, NORMALIZED and anchored on the workspace root (`build()`'s own
+    `tan.core.plan_exec.normalize_path(workspace_root / sdk_root)`) -- passed
+    separately so a relative `--sdk-root ../alp-sdk` keys the stamp
+    IDENTICALLY to the absolute form `tan sdk switch` would pin for the same
+    checkout (tan-cli#163), without changing what `sdk_root` itself
+    substitutes for `${SDK_ROOT}` or reports as `sdk.root`.
+
+    Held slices are also threaded into `execute_slices` as `held_outcomes`
+    (tan-cli #89 MINOR 4, oracle `execute/mod.rs:379-400`): `execute_slices`
+    only ever sees the RUNNABLE subset of the plan (`replace(plan,
+    slices=runnable)` below), so its own post-build manifest overlay would
+    otherwise never learn a demoted slice existed at all -- leaving that
+    core's `system-manifest.yaml` entry at its plan-time (or a previous
+    run's) `status`/`output_artefact` forever, which `tan size`/
+    `tan debug-config` read with no status check of their own. Each held
+    outcome's `output_artefact` is the explicit empty string, never `None`:
+    the overlay (`overlay_run_results_raw`) treats `None` as "preserve
+    whatever is already there", which is correct for a slice this run never
+    touched but wrong for one THIS run knows never dispatched.
+    """
+    held = {
+        d.slice_index: d
+        for d in demotions
+        if plan.slices[d.slice_index].backend in KNOWN_BACKENDS
+        and plan.slices[d.slice_index].command is not None
+    }
+    action = resolve_action(plan.execution_policy, "missing_tool", PolicyAction.SKIP)
+    failed = action is PolicyAction.FAIL
+
+    # tan-cli#483: a slice already held for `${TOOLCHAIN_ROOT}` keeps that
+    # verdict -- a bad `app:` is checked below only for the slices demotion
+    # left alone, so the two never disagree about the same index.
+    missing_app_dirs = {
+        i: msg for i, msg in _missing_app_dirs(plan, build_root).items() if i not in held
+    }
+    # tan-cli#517, filtered the same way and for the same reason: a slice
+    # that will not dispatch has no substitution to announce, and saying so
+    # anyway would bury the verdict that actually stopped it.
+    substituted_app_dirs = {
+        i: msg
+        for i, msg in _substituted_app_dirs(plan, build_root).items()
+        if i not in held and i not in missing_app_dirs
+    }
+
+    held_outcomes = {
+        i: SliceOutcome(
+            plan.slices[i].core_id,
+            "failed" if failed else "skipped",
+            None,
+            d.reason,
+            output_artefact="",
+        )
+        for i, d in held.items()
+    }
+    # A bad app dir is not a host-provisioning gap `executionPolicy` was ever
+    # meant to arbitrate (contrast the demotion above) -- it is the plan
+    # naming a path that does not exist, so it always FAILS the one slice
+    # rather than silently skipping it forward, matching the Expected
+    # section of tan-cli#483 ("not a warning that lets the build proceed").
+    held_outcomes.update(
+        {
+            i: SliceOutcome(plan.slices[i].core_id, "failed", None, msg, output_artefact="")
+            for i, msg in missing_app_dirs.items()
+        }
+    )
+
+    runnable = [
+        sl for i, sl in enumerate(plan.slices) if i not in held and i not in missing_app_dirs
+    ]
+    # tan-cli#287: TTY + text-mode only (never `--format json` -- stdout is
+    # untouched either way, this is belt-and-suspenders for a machine caller
+    # that also inherited the terminal's stderr). `__enter__`/`__exit__` run
+    # regardless of what happens inside, so a dispatch that raises still
+    # stops the thread and blanks any line it had printed.
+    with _Heartbeat(enabled=not json_mode and stderr_is_tty()) as heartbeat:
+        dispatched = iter(
+            execute_slices(
+                replace(plan, slices=runnable),
+                build_root=build_root,
+                env_lookup=os.environ.get,
+                # tan-cli#308: no build_cmd.py-level gap fillers of our own --
+                # `execute_slices` fills ZEPHYR_BASE/EXTRA_ZEPHYR_MODULES
+                # itself, PER SLICE, from the west workspace it resolves
+                # internally (`tan.core.zephyr_env.zephyr_env_overrides`),
+                # exactly where the Rust oracle's own `execute_slices`
+                # computes them (`execute/mod.rs`, inside its own per-slice
+                # loop) -- not from an outer caller. This parameter stays for
+                # a caller-supplied override this port has none of yet.
+                gap_fillers=(),
+                on_output=heartbeat,
+                sdk_root=sdk_root,
+                sdk_root_for_stamp=sdk_root_for_stamp,
+                held_outcomes=held_outcomes.values(),
+                force_pristine=pristine,
+                slice_refusals=slice_refusals,
+                user_defines=user_defines,
+            )
+        )
+
+        outcomes: list[SliceOutcome] = []
+        issues: list[Issue] = []
+        for i, sl in enumerate(plan.slices):
+            demotion = held.get(i)
+            if demotion is not None:
+                outcomes.append(held_outcomes[i])
+                issues.append(
+                    Issue(
+                        # Same code as the plan-fatal sibling on purpose: the
+                        # extension needs no new vocabulary, only a severity
+                        # that says whether this stopped the build.
+                        "build.toolchain-root-unresolved",
+                        "error" if failed else "warning",
+                        f"slice `{sl.core_id}` {'failed' if failed else 'skipped'}: "
+                        f"{demotion.reason}",
+                    )
+                )
+                continue
+            app_dir_message = missing_app_dirs.get(i)
+            if app_dir_message is not None:
+                outcomes.append(held_outcomes[i])
+                issues.append(Issue("build.app-dir-missing", "error", app_dir_message))
+                continue
+            substituted = substituted_app_dirs.get(i)
+            if substituted is not None:
+                issues.append(Issue("build.app-dir-substituted", "info", substituted))
+            outcome = next(dispatched)
+            outcomes.append(outcome)
+            if slice_refusals and outcome.message == slice_refusals.get(sl.core_id):
+                issues.append(Issue("build.host-python-unsuitable", "error", outcome.message))
+    # tan-cli#1351: per-board files naming a different board are silently
+    # ignored by Zephyr.
+    issues.extend(
+        Issue("build.board-file-unmatched", "warning", msg)
+        for msg in unmatched_board_file_messages(
+            [
+                (sl.backend, sl.command.args if sl.command else [], sl.app_dir)
+                for sl in plan.slices
+            ],
+            build_root,
+            _known_boards(sdk_root_for_stamp),
+        )
+    )
+    return outcomes, issues
+
+
+def _known_boards(sdk_root_for_stamp: str | None) -> list[str]:
+    """Every board target the SDK's SoM presets declare (tan-cli#1403).
+    Takes the workspace-anchored, normalized SDK root (a relative `--sdk-root`
+    is anchored on the workspace, not the build root)."""
+    if not sdk_root_for_stamp:
+        return []
+    return all_topology_boards(Path(sdk_root_for_stamp) / "metadata")
+
+
+#: `os` values the schema requires `cores.<id>.app` to resolve to a real
+#: directory for (`metadata/schemas/board.schema.json`
+#: `$defs/core_entry/properties/app`) -- `os: yocto` dispatches by
+#: `recipe:` (a bitbake recipe name), never by this directory
+#: (`tan/planner/orchestrator.py:338-353`), so checking it there would
+#: refuse a buildable yocto slice over a path the build never reads.
+_APP_DIR_REQUIRED_BACKENDS = frozenset({"zephyr", "baremetal"})
+
+
+def _missing_app_dirs(plan: BuildPlan, build_root: Path) -> dict[int, str]:
+    """Slice indices whose `cores.<id>.app` resolved to a path that is not a
+    real, existing directory (tan-cli#483), each mapped to the refusal
+    message.
+
+    Checked HERE, not inside `execute_slices`: by now `apply_plan_token_
+    substitution` has resolved `appDir` to a real path, or held the slice
+    back as a `${TOOLCHAIN_ROOT}` demotion -- `execute_slices`'s own tests
+    feed it synthetic plans with a placeholder `appDir` never meant to
+    exist. Neither `orchestrator.py`'s `_zephyr_app_dir` nor
+    `_resolve_app_path` checks existence (both FROZEN, `tan/planner/**`);
+    unfixed there, a nonexistent `app:` makes `_zephyr_app_dir`'s
+    CMakeLists.txt-fallback probe silently find the PROJECT ROOT's own
+    CMakeLists.txt instead.
+
+    Anchored on `build_root`, not the tan process's own CWD: `appDir` is a
+    plan path like `buildDir`/`command.cwd`, under the same anchoring
+    contract (`build-plan-v1.schema.json`, issue #596) `execute_slices`
+    already confines every slice's `cwd` to. The real CWD would refuse a
+    valid relative `appDir` from anywhere but the project (e.g.
+    `--build-root` from a parent dir), and misname it in the refusal.
+
+    A slice with no `command` (the planner already refused one --
+    `board-tree-missing`, `yocto-recipe-missing`, `no-command`, ...) is
+    skipped, mirroring the `${TOOLCHAIN_ROOT}` filter above: nothing was
+    going to dispatch for it, so reporting this instead would mask the
+    planner's own warning and flip an otherwise-`ok` exit code.
+
+    EXISTENCE only, not the schema's `prj.conf`/`CMakeLists.txt` contents
+    requirement: 96 of 105 enabled zephyr/baremetal examples on alp-sdk
+    `dev` are `app: ./src`, sources-only -- the shipped convention
+    `_zephyr_app_dir`'s own fallback serves, which a contents check would
+    refuse en masse."""
+    missing: dict[int, str] = {}
+    for i, sl in enumerate(plan.slices):
+        if (
+            sl.backend not in _APP_DIR_REQUIRED_BACKENDS
+            or sl.app_dir is None
+            or sl.command is None
+        ):
+            continue
+        app_dir_path = Path(sl.app_dir)
+        if not app_dir_path.is_absolute():
+            app_dir_path = build_root / app_dir_path
+        if not app_dir_path.exists():
+            missing[i] = f"core `{sl.core_id}`: app directory does not exist: {app_dir_path}"
+        elif not app_dir_path.is_dir():
+            missing[i] = f"core `{sl.core_id}`: app path is not a directory: {app_dir_path}"
+    return missing
+
+
+#: The one backend whose app dir the planner may SILENTLY substitute. Only
+#: `_zephyr_app_dir` carries the parent fallback (`tan/planner/
+#: orchestrator.py:397-401`); the `baremetal` arm beside it builds
+#: `cmake -S <_resolve_app_path(app)>` with no `CMakeLists.txt` probe at all,
+#: so nothing is ever substituted there and announcing one would be a lie.
+#: Narrower than `_APP_DIR_REQUIRED_BACKENDS` above for that reason, not by
+#: oversight.
+_APP_DIR_SUBSTITUTING_BACKENDS = frozenset({"zephyr"})
+
+
+def _substituted_app_dirs(plan: BuildPlan, build_root: Path) -> dict[int, str]:
+    """Slice indices whose `cores.<id>.app` resolved to a real directory that
+    carries no `CMakeLists.txt`, so `west build` will be pointed at its
+    PARENT instead (tan-cli#517), each mapped to the announcement.
+
+    ANNOUNCED, never refused. The fallback is the shipped convention, not a
+    defect: 96 of 105 enabled app-carrying zephyr/baremetal core entries
+    across alp-sdk `dev`'s own examples are `app: ./src`, sources-only, with
+    the one `CMakeLists.txt` at the example root doing
+    `target_sources(app PRIVATE src/main.c)`. Refusing would break 91% of the
+    SDK's own examples, which is why tan-cli#517 asks for visibility and
+    explicitly not for a refusal. What was wrong was only that it happened
+    SILENTLY: on a multi-core project the parent IS the project root, which
+    is very often the OTHER core's application, so a typo in one core's
+    `app:` that still names an existing directory builds the wrong source
+    tree and reports success.
+
+    `severity: "info"`, not `"warning"`. The measurement above is the
+    argument: the substitution fires on the overwhelming majority of real
+    builds, so `"warning"` would put a permanent yellow item on nearly every
+    successful build in a consumer that surfaces `issues[]` on the ok path
+    (alp-sdk-vscode does, since alp-sdk-vscode#485) -- and a warning that is
+    always there is one nobody reads on the day it matters. `"info"` is the
+    severity this registry already uses for exactly this shape: something
+    was substituted/migrated on your behalf and you should be able to see it
+    (`debug-config.legacy-entry-migrated`).
+
+    Named BOTH ways, as the issue asks: the configured path and the
+    substituted one. Naming only the substituted one would be indis-
+    tinguishable from a correctly-configured self-contained app dir.
+
+    The probe MIRRORS `_zephyr_app_dir`'s own two-line condition rather than
+    reading the substituted path back out of `command.args`. `tan/planner/**`
+    is a hash-audited relocation of alp-sdk's `scripts/alp_orchestrate/**`
+    (`tests/gates/test_planner_relocation_freshness.py`) and cannot be
+    changed here, so the condition is stable; reading `command.args` instead
+    would bind this to the ARGV POSITION of `west build`'s app argument,
+    which is not a contract anywhere. Note `appDir` is NOT the substituted
+    value: `buildplan.py` emits `_resolve_app_path(app)` there, the
+    configured path, and only the `west build` positional gets
+    `_zephyr_app_dir`'s result -- which is what makes both halves of the
+    message recoverable from the plan at all.
+
+    Guarded exactly like `_missing_app_dirs`: no `command` means nothing was
+    going to dispatch, and a nonexistent `app:` is that function's refusal,
+    reported there and not softened into an advisory here.
+    """
+    substituted: dict[int, str] = {}
+    for i, sl in enumerate(plan.slices):
+        if (
+            sl.backend not in _APP_DIR_SUBSTITUTING_BACKENDS
+            or sl.app_dir is None
+            or sl.command is None
+        ):
+            continue
+        app_dir_path = Path(sl.app_dir)
+        if not app_dir_path.is_absolute():
+            app_dir_path = build_root / app_dir_path
+        if not app_dir_path.is_dir() or (app_dir_path / "CMakeLists.txt").is_file():
+            continue
+        parent = app_dir_path.parent
+        if not (parent / "CMakeLists.txt").is_file():
+            # `_zephyr_app_dir`'s third arm: neither has one, so it returns
+            # the configured path unchanged. Nothing was substituted, so
+            # there is nothing to announce -- the build fails in west/CMake
+            # naming the path the project actually configured.
+            continue
+        substituted[i] = (
+            f"core `{sl.core_id}`: app directory has no CMakeLists.txt "
+            f"({app_dir_path}) -- building its parent instead ({parent}). This is the "
+            f"`app: ./src` sources-only convention when intended; if it was not, "
+            f"`cores.{sl.core_id}.app` names the wrong directory and this build is "
+            f"against the parent's sources."
+        )
+    return substituted
+
+
+def _backend_issues(plan: BuildPlan, outcomes: list[SliceOutcome]) -> list[Issue]:
+    """Name the backend string the plan sent that this CLI does not know.
+    Recomputed from the slice rather than sniffed out of the outcome message:
+    `executionPolicy.unknownBackend` already decided skip-vs-fail inside
+    `execute_slices`, and the outcome's status is the honest read of it."""
+    issues = []
+    for sl, outcome in zip(plan.slices, outcomes, strict=True):
+        if sl.backend in KNOWN_BACKENDS:
+            continue
+        failed = outcome.status == "failed"
+        issues.append(
+            Issue(
+                "build.unknown-backend",
+                "error" if failed else "warning",
+                f"slice `{sl.core_id}` names unrecognised backend `{sl.backend}`"
+                + ("" if failed else " -- skipped"),
+            )
+        )
+    return issues
+
+
+def _missing_tool_issues(plan: BuildPlan, outcomes: list[SliceOutcome]) -> list[Issue]:
+    """Name the tool a skipped (or, under `executionPolicy.missingTool: fail`,
+    failed) slice could not find on this host.
+
+    Matched on `outcome.message` rather than re-probing PATH a second time:
+    every missing-tool refusal `execute_slices` (`build/execute.py`) can
+    produce carries [`MISSING_TOOL_RE`]'s shape somewhere in the message --
+    a null-command skip reads `` has no command `` (and its reason already
+    lives in `plan.warnings`, I-11), and an unknown-backend one is caught
+    structurally by `_backend_issues` above -- so this recovers exactly the
+    missing-tool cases and nothing else.
+
+    tan-cli#801: this used to require the marker at the message's START
+    (`message.startswith("tool `")`), which matched only the slice's own
+    `command` precheck. The #550 post-build-step refusal
+    (`_missing_post_tool`) puts the SAME phrase after a `` slice `{core_id}`
+    post-build step N of M (`{label}`) cannot run: `` lead-in, so it never
+    started with the marker and this promoter silently dropped it -- the
+    exact silence tan-cli#283 was filed to close, just for a different
+    refusal site. `.search`, not `startswith`: the marker's position is not
+    part of the contract, only whether the message carries it at all.
+
+    tan-cli#283: without this, `tan build` on a host missing `west`/`bitbake`
+    reported each slice's specific reason only in `data.slices[].reason` --
+    never in `issues[]`, the field a JSON consumer (the VS Code extension,
+    CI) actually reads to decide whether anything needs flagging."""
+    issues = []
+    for sl, outcome in zip(plan.slices, outcomes, strict=True):
+        message = outcome.message
+        if message is None or not MISSING_TOOL_RE.search(message):
+            continue
+        failed = outcome.status == "failed"
+        issues.append(
+            Issue(
+                "build.missing-tool",
+                "error" if failed else "warning",
+                f"slice `{sl.core_id}` {'failed' if failed else 'skipped'}: {message}",
+            )
+        )
+    return issues
+
+
+def _host_python_issues(build_python, mode) -> list[Issue]:
+    """tan-cli#1317. Where CMake will NOT run (`--materialise`) the refusal is a
+    plain warning and the bare fallback stays. On the native dispatch it is a
+    PER-SLICE outcome instead (`_python_refusals` -> `execute_slices`), applied
+    after `executionPolicy`'s null-command / missing-tool skips."""
+    if build_python.refusal is None or mode == _MODE_NATIVE:
+        return []
+    return [Issue("build.host-python-unsuitable", "warning", build_python.refusal)]
+
+
+def _python_refusals(build_python, demotions, mode) -> dict[str, str]:
+    if build_python.refusal is None or mode != _MODE_NATIVE:
+        return {}
+    message = refusal_message(build_python.refusal)
+    return {
+        c: f"core `{c}`: {message}"
+        for c in build_python.users - {d.core_id for d in demotions}
+    }
+
+
+def _cross_drive_issues(outcomes: list[SliceOutcome]) -> list[Issue]:
+    """tan-cli#697: promote `tan.core.plan_exec.cross_drive_source_refusal`'s
+    refusal -- matched on its own `CROSS_DRIVE_MSG` marker, same idiom as
+    `_missing_tool_issues` above -- from a per-slice `reason` into a coded
+    top-level `issues[]` entry. Without this the envelope carried only the
+    generic `build.slice-failed` header (`_build`, below) for a cross-drive
+    project/workspace layout, indistinguishable from any other build
+    failure to a JSON consumer that reads `issues[]` and never `data.
+    slices[].reason`. Always `failed`, never `skipped`: this refusal is a
+    hardcoded plan/host-layout defect (mirroring the unsafe-cwd escape
+    above it in `execute.py`), not something `executionPolicy` governs."""
+    issues = []
+    for outcome in outcomes:
+        if outcome.message is None or CROSS_DRIVE_MSG not in outcome.message:
+            continue
+        issues.append(Issue("build.cross-drive-workspace", "error", outcome.message))
+    return issues
+
+
+def _workspace_unresolved_issues(outcomes: list[SliceOutcome]) -> list[Issue]:
+    """tan-cli#1429: `_cross_drive_issues`' promotion for the refusal in
+    `tan.core.west_workspace_refusal`, matched on its own marker."""
+    return [
+        Issue("build.workspace-unresolved", "error", o.message)
+        for o in outcomes
+        if o.message is not None and WORKSPACE_UNRESOLVED_MSG in o.message
+    ]
+
+
+def _plan_warning_issues(warnings: list[dict]) -> list[Issue]:
+    """tan-cli#1000: promote the PLAN's own warnings into `issues[]`.
+
+    Third sibling of `_missing_tool_issues` (tan-cli#283/#801) and
+    `_cross_drive_issues` (tan-cli#697), and filed because it was the door
+    those two left open. `plan.warnings` reached exactly one place -- the
+    envelope's `data.warnings` -- so the message that says WHY a build
+    produced nothing was invisible to text mode and to any consumer reading
+    `issues[]`, which is the field alp-sdk-vscode and CI actually branch on.
+
+    Measured on `E1M-AEN301`, a SKU `tan presets` lists: `tan init` rc=0,
+    `tan validate` rc=0 "clean", `tan build` rc=1 with a four-line text
+    output whose only cause-bearing words were ``slice `m55_hp` has no
+    command``, while `data.warnings` held "SoM 'E1M-AEN301' core 'm55_hp'
+    wants Zephyr board 'alp_e1m_aen301_m55_hp', which has no tree under
+    zephyr/boards/alp/ -- board bring-up for this target has not happened
+    yet."
+
+    ONE registered code for every warning, not `build.<the warning's own
+    code>`: `build_plan.py`'s `_warnings` documents the warning codes as an
+    OPEN set ("the forward compatibility is in the CODES being open"), so
+    minting an issue code per warning code would emit unregistered codes the
+    moment the planner adds one -- and `contract/issue-codes.json` is a
+    closed registry whose consumer matches with `===`. The warning's own code
+    travels inside the message instead, where an open set costs nothing.
+
+    Severity is always `warning`, never promoted to `error` on the count: a
+    build that fails BECAUSE of these already carries its own
+    `build.nothing-built`/`build.slice-failed` error beside them, and a
+    partial build where one core lacks a board tree is genuinely not an
+    error for the cores that did build.
+
+    Text mode needs no separate change -- `_print_text_issues` prints every
+    surviving issue as ``{severity}: {message}``, and `_text_issues`'
+    dedup (tan-cli#746) only drops a message that ENDS WITH a slice's own
+    `reason`, which a warning's text does not.
+    """
+    issues = []
+    for warning in warnings:
+        code = warning.get("code")
+        core_id = warning.get("coreId")
+        message = warning.get("message")
+        where = f" {core_id}:" if core_id else ""
+        issues.append(
+            Issue("build.plan-warning", "warning", f"[{code}]{where} {message}")
+        )
+    return issues
+
+
+def _toolchain_for_plan(plan_text: str) -> ToolchainResolution:
+    """This host's `${TOOLCHAIN_ROOT}` -- resolved ONLY when `plan_text`
+    actually names the token (tan-cli#547).
+
+    The laziness is the point, and it is a property of THIS call site rather
+    than of `resolve_toolchain_root` itself: no SDK plan names
+    `${TOOLCHAIN_ROOT}` today, and every one of those builds must keep
+    costing zero filesystem scans of `/opt` and `$HOME`. It also keeps the
+    resolver's own failure modes (an unreadable scan root, an ambiguous
+    host) entirely out of the way of a plan that would never have consumed
+    the value.
+
+    Asked of the plan's re-serialised JSON, not of `plan_text` directly: a
+    plan is free to spell the token's `$` as `\\u0024`, which a raw substring
+    search would miss while `substitute_plan_tokens` -- which sees the
+    DECODED string -- would not, leaving the slice demoted on a host that
+    has a toolchain. `plan_text` is already known to parse (`_acquire_plan`
+    returned a `BuildPlan` from it), so the round trip cannot fail here.
+
+    An untokened plan (`planPathMode` absent) never reaches substitution at
+    all, but is not special-cased: it also never contains the token, so the
+    same one check covers both.
+    """
+    if TOKEN_TOOLCHAIN_ROOT not in json.dumps(json.loads(plan_text)):
+        return ToolchainResolution(None)
+    return resolve_toolchain_root()
+
+
+def _build_root_is_consumer_default(build_root: str) -> bool:
+    """Whether a plan's `buildRoot` names the ONE tree this consumer reads
+    back (tan-cli#566) -- `BuildPlan::build_root_is_consumer_default` in the
+    oracle.
+
+    A PATH-COMPONENT comparison, not a string equality, and that distinction
+    is load-bearing in both directions. MEASURED against `target/debug/tan`
+    (`tan 0.4.1`), driving its live-emit native path through a stub planner
+    so an arbitrary `buildRoot` could be handed to it, ten spellings, only
+    that field varying:
+
+        build            rc 0    accepted
+        build/           rc 0    accepted   <- a naive `!= "build"` refuses this
+        ./build          rc 0    accepted   <- and this
+        out              rc 1    build.unsupported-build-root
+        build/sub        rc 1    build.unsupported-build-root
+        BUILD            rc 1    build.unsupported-build-root  (case SENSITIVE)
+        (empty)          rc 1    build.unsupported-build-root
+        ..               rc 1    build.unsupported-build-root
+        ../build         rc 1    build.unsupported-build-root
+        /tmp/abs/build   rc 1    build.unsupported-build-root
+
+    `Path.parts` reproduces all ten: it drops a trailing separator and a
+    leading `./` (so the two accepted aliases stay accepted), keeps `..` and
+    a leading root as components of their own, and is empty for `""`.
+    """
+    return Path(build_root).parts == (CONSUMER_BUILD_ROOT,)
+
+
+def _demoted_artefact_issues(plan: BuildPlan, demotions) -> list[Issue]:
+    """`executionPolicy.missingTool`, applied to a MATERIALISE run's token
+    demotions (tan-cli#565) -- RAISES on `fail`, returns one warning per
+    demoted slice on `skip`.
+
+    `substitute_plan_tokens` STRIPS a demoted slice's `configArtefacts`, so
+    without this the files that slice's core needs are simply absent from
+    both `written` and the disk, at exit 0 with `issues: []` -- a CI step
+    that materialises and then runs `west build` for that core gets DEFAULT
+    Kconfig instead of the project's, with no signal on either side. Routed
+    to `missingTool` because a demotion is a host-provisioning fact, the same
+    seam `_dispatch` routes it to for a run that goes on to dispatch.
+
+    NOT filtered the way `_dispatch`'s `held` is. There, a demoted slice
+    whose backend is unknown or whose `command` is null is left alone because
+    something else already outranks a provisioning fact AT DISPATCH. Nothing
+    is being dispatched here -- the question is only whether a file was
+    written -- so every demotion counts. MEASURED against the oracle with a
+    four-slice plan (demoted + `command: null`; demoted + unknown backend;
+    demoted + ordinary; undemoted): all three demoted slices were reported,
+    under both actions, and only the undemoted slice's artefact was written.
+
+    The two shapes are the oracle's own, verbatim:
+
+      * `skip` -> exit 0, one `warning` PER slice, "slice `x`:
+        configArtefacts not materialised — <reason>".
+      * `fail` -> exit 1, `data: null`, ONE `error` whose message is every
+        slice's "slice `x`: <reason>" sentence joined by newlines.
+
+    `reason` is threaded through verbatim from the demotion rather than
+    re-derived, exactly as `_dispatch` does -- it is the second half of one
+    toolchain resolution (`ToolchainResolution.advice`), and re-deriving it
+    here would let the sentence drift from the value it explains.
+    """
+    action = resolve_action(plan.execution_policy, "missing_tool", PolicyAction.SKIP)
+    if action is PolicyAction.FAIL:
+        raise BuildError(
+            "build.toolchain-root-unresolved",
+            "\n".join(f"slice `{d.core_id}`: {d.reason}" for d in demotions),
+            ExitCode.RUNTIME_FAILURE,
+        )
+    return [
+        Issue(
+            "build.toolchain-root-unresolved",
+            "warning",
+            f"slice `{d.core_id}`: configArtefacts not materialised — {d.reason}",
+        )
+        for d in demotions
+    ]
+
+
+def _build(
+    *,
+    # Defaulted so `mode` stays optional for the OTHER caller of this engine:
+    # `run_cmd._run` builds unconditionally (there is no `tan run
+    # --plan`/`--materialise`) and has no mode to pass.
+    mode: str = _MODE_NATIVE,
+    plan_from: str | None,
+    build_root: str,
+    sdk_root: str | None,
+    sdk_root_for_stamp: str | None,
+    board_yaml: str | None,
+    # Defaulted for the same reason as `mode`: `run_cmd._run`
+    # calls this with no format preference of its own today. Threaded
+    # straight through to `_dispatch`, which is where the heartbeat this
+    # gates is actually armed -- see that function's own docstring.
+    json_mode: bool = False,
+    # Defaulted for the same reason as `mode`/`json_mode`: `run_cmd._run` has
+    # no `tan build --pristine` equivalent of its own yet (`tan run` has no
+    # `--pristine` flag). Threaded straight through to `_dispatch`.
+    pristine: bool = False,
+    # tan-cli#1359: the synthesised single-Zephyr-slice plan text for a
+    # `board.yaml`-less example (`tan build --board`). Replaces the planner.
+    plain_plan_text: str | None = None,
+    # tan-cli#1382: normalised `-D` args (and optional `--core` scope) spliced
+    # into a PLANNED build's Zephyr slices. Unused on the plain route, which
+    # already carries its defines in `plain_plan_text`.
+    defines: list[str] | None = None,
+    define_cores: list[str] | None = None,
+) -> tuple[ExitCode, dict, list[Issue]]:
+    define_slices: list[str] = []
+    if plain_plan_text is not None:
+        text = plain_plan_text
+        try:
+            plan = parse_build_plan(text)
+        except PlanParseError as err:  # pragma: no cover -- tan's own plan
+            raise BuildError(err.code, err.message, ExitCode.RUNTIME_FAILURE) from err
+        if defines:
+            define_slices = [sl.core_id for sl in plan.slices]
+    else:
+        text, plan = _acquire_plan(plan_from, sdk_root, board_yaml)
+        if defines:
+            try:
+                text, define_slices = apply_user_defines(text, defines, define_cores)
+            except UserDefineError as err:
+                raise BuildError(err.code, err.message, ExitCode.VALIDATION_FAILURE) from err
+            plan = parse_build_plan(text)
+
+    if mode == _MODE_PLAN:
+        # Parsed (so a plan that will not load is still refused with its own
+        # code -- measured: the oracle rejects `schemaVersion: 2` and an
+        # unknown `executionPolicy` action in THIS mode too), then echoed
+        # verbatim. No token substitution: the oracle shows a `planPathMode:
+        # tokened` plan with no SDK resolvable at exit 0, unsubstituted, and
+        # only refuses it once `--materialise` asks for it on disk.
+        return ExitCode.SUCCESS, json.loads(text), []
+
+    # Substitution runs on the in-memory plan BEFORE materialise writes
+    # anything and before any command is assembled, so an unresolvable token
+    # can never reach disk or an argv. A no-op on an untokened plan -- e.g. an
+    # old `--plan-from` file (the planner itself now tags every plan tokened).
+    toolchain = _toolchain_for_plan(text)
+    deferred: list[DeferredPlaceholder] = []
+    build_python = resolve_build_python(plan, text, build_root, sdk_root)
+    try:
+        plan, demotions = apply_plan_token_substitution(
+            plan,
+            board_yaml_path=board_yaml,
+            exec_base=build_root,
+            sdk_root=sdk_root,
+            python=build_python.python,
+            toolchain_root=toolchain.root,
+            toolchain_advice=toolchain.advice,
+            deferred_out=deferred,
+            project_root=build_root if plain_plan_text is not None else None,
+        )
+    except TokenSubstitutionError as err:
+        # RuntimeFailure for every code this pass raises, `build.plan-invalid`
+        # (an unknown `planPathMode`) included -- same ladder position the Rust
+        # oracle gives them (`native.rs:132-142`), and the same code must not
+        # mean two different exits depending on which module raised it.
+        raise BuildError(err.code, err.message, ExitCode.RUNTIME_FAILURE) from err
+
+    python_issues = _host_python_issues(build_python, mode)
+
+    # tan-cli#566, and tan-cli#565's `fail` arm: BOTH sit here, between
+    # substitution and `materialise_plan` below, because both must leave a
+    # refused run with NOTHING on disk. `materialise_plan` runs unconditionally
+    # and above the mode check, so a guard placed inside the `_MODE_MATERIALISE`
+    # block below would refuse only AFTER the other slices' files had landed --
+    # measured, the oracle's own refusals leave the tree empty in both cases.
+    #
+    # After substitution, not before, also measured: a plan that is BOTH
+    # `planPathMode: legacy` and `buildRoot: out` is refused by the oracle with
+    # `build.plan-invalid`, not `build.unsupported-build-root`, so the
+    # substitution pass keeps its precedence.
+    #
+    # NATIVE only for the build root (tan-cli#566). The oracle accepts
+    # `buildRoot: out` under `--materialise` AND `--plan` and refuses it only on
+    # the path that goes on to DISPATCH -- measured, all three modes -- and that
+    # split is the right one rather than an inconsistency to iron out: the
+    # hazard is `system-manifest.yaml`, which only a dispatching run writes.
+    # `_MODE_NATIVE` is also what `--execute` and `run_cmd._run` select, so both
+    # of those are covered by the same one check. Nothing narrows to
+    # `--plan-from`: every live plan the in-process planner emits has
+    # `buildRoot: build` (`tan.planner.cli`/`planner_root.emit` default it to
+    # `Path("build")` and `_emit_plan` never overrides), so this can only ever
+    # fire on a plan file, which is exactly the shape the issue reports.
+    if mode == _MODE_NATIVE and not _build_root_is_consumer_default(plan.build_root):
+        raise BuildError(
+            "build.unsupported-build-root",
+            f"plan buildRoot `{plan.build_root}` is not `{CONSUMER_BUILD_ROOT}`; "
+            "tan's flash/size/image read "
+            "`<project>/build/system-manifest.yaml`, so building elsewhere "
+            "would leave them reading a stale or missing manifest",
+            ExitCode.RUNTIME_FAILURE,
+        )
+
+    # MATERIALISE only for the demotions (tan-cli#565): `_MODE_NATIVE` already
+    # routes them, per slice, through `_dispatch`'s own `missing_tool` seam, and
+    # `_MODE_PLAN` returned above without substituting at all. Raises on `fail`,
+    # so nothing below runs; returns the per-slice warnings on `skip`, carried
+    # to the return statement rather than emitted here.
+    demotion_issues = (
+        _demoted_artefact_issues(plan, demotions)
+        if mode == _MODE_MATERIALISE and demotions
+        else []
+    )
+    # tan-cli#1302: placeholders deliberately left in a config artefact, and a
+    # malformed `deferredPlaceholders`. Reported on EVERY path that
+    # materialises, so the native build says it too, not just `--materialise`.
+    deferred_issues = deferred_placeholder_issues(plan, deferred)
+
+    # I-20. ALL of them, then dispatch -- never interleaved.
+    try:
+        materialise_plan(plan, Path(build_root))
+    except MaterialiseError as err:
+        raise BuildError(
+            "build.materialise-failed", err.message, ExitCode.WRITE_FAILURE
+        ) from err
+
+    if mode == _MODE_MATERIALISE:
+        # Write and stop -- the oracle dispatches nothing here, and its `data`
+        # carries no `slices` at all. `written` is rebuilt from the plan's own
+        # (post-substitution) artefact paths in `materialise_plan`'s documented
+        # order, shared first then per slice, because those are the RELATIVE
+        # strings the oracle reports; `materialise_plan` itself hands back
+        # resolved absolute paths, and relativising those back re-introduces
+        # every symlink/case difference `_abs_posix` exists to avoid.
+        written = [a["path"] for a in plan.shared_artefacts]
+        for sl in plan.slices:
+            written.extend(a["path"] for a in sl.config_artefacts)
+        return (
+            ExitCode.SUCCESS,
+            {"schemaVersion": "1", "baseDir": build_root, "written": written},
+            demotion_issues + deferred_issues + python_issues,
+        )
+
+    # Cleared before dispatch, mirroring `run_cmd.py`'s own pattern, so a
+    # leftover signal from an earlier in-process `_build` (e.g. a test
+    # harness calling `build()` more than once) never gets misread as THIS
+    # run's own write outcome below.
+    reset_last_manifest_write()
+    # tan-cli#1376: advisory only -- never changes `ok`/the exit code.
+    patch_issues = workspace_patch_issues(
+        Path(build_root),
+        sdk_root,
+        has_zephyr_slice=any(sl.backend == "zephyr" for sl in plan.slices),
+    )
+    outcomes, issues = _dispatch(
+        plan,
+        demotions,
+        Path(build_root),
+        sdk_root,
+        sdk_root_for_stamp,
+        json_mode=json_mode,
+        pristine=pristine,
+        slice_refusals=_python_refusals(build_python, demotions, mode),
+        user_defines={c: define_pairs(defines) for c in define_slices} if defines else None,
+    )
+
+    any_failed = any(o.status not in ("succeeded", "skipped") for o in outcomes)
+    # tan-cli#283: a plan whose EVERY slice was skipped (e.g. `west`/
+    # `bitbake` absent from PATH) used to fall straight through this `if
+    # any_failed` gate -- `skipped` is deliberately not a failure status on
+    # its own line above -- and report `ok: true, exitCode: 0, issues: []`.
+    # A JSON consumer cannot tell that from a real build. A PARTIAL build
+    # (some slice built -- e.g. only the Zephyr cores, on a host with no
+    # Yocto toolchain) is a legitimate, deliberate outcome and must stay
+    # `ok: true`; refusing outright only when NOTHING built at all is the
+    # narrower fix, not "any skip is now a failure".
+    nothing_built = (
+        bool(outcomes)
+        and not any_failed
+        and not any(o.status == "succeeded" for o in outcomes)
+    )
+    exit_code = ExitCode.RUNTIME_FAILURE if (any_failed or nothing_built) else ExitCode.SUCCESS
+    if any_failed:
+        issues.insert(
+            0, Issue("build.slice-failed", "error", "one or more slices failed to build")
+        )
+    elif nothing_built:
+        issues.insert(
+            0,
+            Issue(
+                "build.nothing-built",
+                "error",
+                "no slice was built -- every slice was skipped",
+            ),
+        )
+    issues.extend(_backend_issues(plan, outcomes))
+    # tan-cli#283: named per skipped/failed slice, even in the PARTIAL case
+    # `nothing_built` does not cover -- a consumer reading only `issues[]`
+    # (not `data.slices[]`) must still be able to tell "2 of 3 slices built"
+    # from "3 of 3".
+    issues.extend(_missing_tool_issues(plan, outcomes))
+    # tan-cli#697: named per cross-drive-refused slice, same reasoning as
+    # `_missing_tool_issues` immediately above -- a JSON consumer reading
+    # only `issues[]` must see the specific cause, not just the generic
+    # `build.slice-failed` header this promotion sits alongside.
+    issues.extend(_cross_drive_issues(outcomes))
+    issues.extend(_workspace_unresolved_issues(outcomes))
+    # tan-cli#1000: the PLAN's own warnings, same reasoning again -- these
+    # are the only place the planner explains a `command: null` slice, and
+    # they reached `data.warnings` alone until now.
+    issues.extend(_plan_warning_issues(plan.warnings))
+    issues.extend(deferred_issues)
+    issues.extend(python_issues)
+    issues.extend(patch_issues)
+    # The sdk-switch-pristine wipe (issue #52) must not be stderr-only in
+    # JSON mode -- the VS Code extension only ever sees the envelope, not
+    # `_stream`'s output. Verbatim oracle codes/severity
+    # (`crates/tan-cli/src/commands/build/execute/mod.rs:591,617`):
+    # `build.sdk-switch-pristine` for the wipe itself, `-failed` when the
+    # wipe could not fully land.
+    issues.extend(last_sdk_switch_issues())
+    # tan-cli#655: the stale-configure-cache reset must not be stderr-only in
+    # JSON mode either -- same reasoning as the sdk-switch-pristine wipe
+    # immediately above.
+    issues.extend(last_configure_cache_issues())
+
+    manifest_reason = last_manifest_write_failure()
+    # The plain route (`--board`) has its own writer (tan-cli#1381), so a failed
+    # write there is as real as on the planned route (tan-cli#1517).
+    if manifest_reason is not None:
+        # A failed manifest write used to report only through `on_output`
+        # (stderr) -- so the envelope said `ok: true, issues: []` while
+        # `system-manifest.yaml` still named the PREVIOUS run's status and
+        # artefact, which `tan size` re-derives and `tan flash` would go on
+        # to program. Verbatim oracle code/message
+        # (`crates/tan-cli/src/commands/build/execute/mod.rs:809-814`):
+        # dropping this half is exactly how a stale manifest used to look
+        # identical to `ok: true`.
+        issues.append(
+            Issue(
+                "build.manifest-write-failed",
+                "warning",
+                f"system-manifest.yaml was not updated — {manifest_reason}",
+            )
+        )
+
+    data = {
+        "schemaVersion": "1",
+        "baseDir": build_root,
+        "slices": [
+            _slice_result(sl.core_id, sl.backend, outcome)
+            for sl, outcome in zip(plan.slices, outcomes, strict=True)
+        ],
+        # The plan's own warnings, verbatim. A `command: null` slice is a
+        # legitimate skip whose REASON lives only here (I-11) -- dropping the
+        # list leaves the user a slice that silently did not build. Passed
+        # through untyped on purpose: the schema says new warning codes may
+        # appear without a schemaVersion bump, so a consumer must not treat
+        # them as a closed set, and neither may this.
+        "warnings": plan.warnings,
+    }
+    if defines and define_slices:
+        data["defines"] = {"args": list(defines), "slices": define_slices}
+    return exit_code, data, issues
+
+
+def _plain_core_id(board: str, sdk_root: str | None) -> str | None:
+    """The planner core id (`m55_he`) the plain route's board target maps to,
+    from the bound SDK's SoM presets; `None` (the slice keeps the board
+    qualifier's name) when the SDK or the target is unknown (tan-cli#1370)."""
+    if sdk_root is None or not is_sdk_root(sdk_root):
+        return None
+    try:
+        from tan.planner_root import bind_sdk_root
+
+        bind_sdk_root(sdk_root)
+        from tan.planner.plain_slice import plain_core_id
+
+        return plain_core_id(board, Path(sdk_root) / "metadata")
+    except Exception:  # noqa: BLE001 -- best effort; the fallback name still builds
+        return None
+
+
+def _refuse_plain_route(
+    board: str | None,
+    define: list[str] | None,
+    board_yaml: str | None,
+    plan_from: str | None,
+    mode: str,
+    json_mode: bool,
+) -> None:
+    """Refuse a bad `--board` / `-D` combination up front (exit 2), else return."""
+    conflict = None
+    if board is not None and (board_yaml is not None or plan_from is not None):
+        flag = "--board-yaml" if board_yaml is not None else "--plan-from"
+        conflict = (
+            "`--board` (a plain Zephyr example, no board.yaml) cannot be combined with "
+            f"`{flag}` (a planned build). Pick one route."
+        )
+    elif board is not None and mode != _MODE_NATIVE:
+        conflict = "`--board` only builds; drop `--materialise`."
+    if conflict is not None:
+        _refuse("build.conflicting-flags", conflict, ExitCode.VALIDATION_FAILURE, json_mode)
+    problem = (board_target_problem(board) if board is not None else None) or normalise_defines(
+        define or []
+    )[1]
+    if problem is not None:
+        _refuse("build.invalid-argument", problem, ExitCode.VALIDATION_FAILURE, json_mode)
+    reserved = user_defines_problem(normalise_defines(define or [])[0])
+    if reserved is not None and reserved[0] == "build.define-reserved":
+        _refuse("build.define-reserved", reserved[1], ExitCode.VALIDATION_FAILURE, json_mode)
+    if reserved is not None:
+        _refuse("build.invalid-argument", reserved[1], ExitCode.VALIDATION_FAILURE, json_mode)
+
+
+def _refuse(code: str, message: str, exit_code: ExitCode, json_mode: bool) -> None:
+    """Report a refusal this command makes UP FRONT -- before any project is
+    resolved, any plan read, and any byte written -- and exit.
+
+    One helper for both of them (a retired flag, and a conflicting flag pair)
+    because they differ only in code, message and exit code. `project` is left
+    unresolved: nothing was read, so reporting a root would be reporting work
+    this run did not do."""
+    issue = Issue(code, "error", message)
+    if json_mode:
+        emit(
+            Envelope(
+                "build",
+                Project(root=None, board_yaml=None),
+                {"message": message},
+                [issue],
+                exit_code,
+            )
+        )
+    else:
+        print(f"error: {message}", file=sys.stderr)
+    raise typer.Exit(int(exit_code))
+
+
+def build(
+    plan_from: str = typer.Option(
+        None,
+        "--plan-from",
+        metavar="FILE",
+        help="Read the build plan from a JSON file instead of invoking the SDK planner. "
+        "Implies --plan: shows the plan and exits unless --materialise or --execute "
+        "is given.",
+    ),
+    materialise: bool = typer.Option(
+        False,
+        "--materialise",
+        help="Write the plan's generated files (shared artefacts + per-slice config) "
+        "under the build root and stop, instead of just showing the plan.",
+    ),
+    # Accepted and INERT, exactly as in the oracle ("This is the default; the
+    # flag is kept as an explicit opt-in" -- its own `--native` help). Never
+    # read below on purpose: a bare build is already native, and letting it
+    # override the `--plan` implied by `--plan-from` is the divergence
+    # `test_plan_from_shows_the_plan_and_writes_nothing_even_with_native`
+    # exists to keep out. `--execute` is the flag that dispatches a
+    # file-supplied plan.
+    native: bool = typer.Option(
+        False,
+        "--native",
+        help="Build natively: materialise the plan, then run each slice's command. "
+        "The default when no plan-mode flag is given. Does NOT override the --plan "
+        "implied by --plan-from -- use --execute for that.",
+    ),
+    execute: bool = typer.Option(
+        False,
+        "--execute",
+        help="Materialise the plan AND run each slice's command, even when the plan "
+        "came from --plan-from -- run a pinned, reviewed plan file reproducibly. "
+        "Implies --materialise (nothing can run that was never written); reports the "
+        "ordinary build result.",
+    ),
+    build_root: str = typer.Option(
+        None,
+        "--build-root",
+        metavar="DIR",
+        help="Project tree the slices run under and artefacts are written below "
+        "(default: the board.yaml's directory, else the current directory).",
+    ),
+    sdk_root: str = typer.Option(
+        None, "--sdk-root", metavar="PATH", help="alp-sdk checkout root."
+    ),
+    board_yaml: str = typer.Option(
+        None, "--board-yaml", metavar="PATH", help="Explicit board.yaml path."
+    ),
+    project: str = typer.Option(
+        None, "--project", metavar="PATH", help="Project root (defaults to '.')."
+    ),
+    board: str = typer.Option(
+        None,
+        "--board",
+        metavar="TARGET",
+        help="Build a plain Zephyr example that has no board.yaml (alp-sdk's bench "
+        "examples) as one Zephyr slice for this board target, e.g. "
+        "`alp_e1m_aen803_m55_he/ae822fa0e5597ls0/rtss_he`. The app is `--project` "
+        "(default '.'); west, toolchain, SDK and host-Python resolve as for a planned "
+        "build (tan-cli#1359).",
+    ),
+    define: list[str] = typer.Option(
+        None,
+        "-D",
+        "--define",
+        metavar="NAME=VALUE",
+        help="A CMake definition passed after `--` to west on every Zephyr slice "
+        "(or those named by --core), repeatable (`-D SHIELD=...`, `-D CONFIG_X=y`). "
+        "Applied AFTER the plan's own args so it overrides them, except "
+        "EXTRA_CONF_FILE / EXTRA_DTC_OVERLAY_FILE, which are appended `;`-joined to "
+        "tan's list; BOARD and Python3_EXECUTABLE are refused (tan-cli#1382).",
+    ),
+    core: list[str] = typer.Option(
+        None,
+        "--core",
+        metavar="ID",
+        help="Scope -D to the Zephyr slice(s) with this coreId, repeatable "
+        "(default: every Zephyr slice).",
+    ),
+    output_format: OutputFormat = typer.Option(OutputFormat.TEXT, "--format", help=FORMAT_HELP),
+    pristine: bool = typer.Option(
+        False,
+        "--pristine",
+        help="Force-wipe every slice's build dir before dispatch, regardless of the "
+        "recorded SDK-switch stamp (tan-cli#163) -- the manual counterpart to the "
+        "automatic sdk-switch-pristine wipe, for a stale build dir the stamp heuristic "
+        "doesn't (or can't yet) catch. Same wipe, same two safety guards (an explicit "
+        "`-d`/`--build-dir` in the slice's own command, or a plan cwd outside `build/`): "
+        "this never touches a dir tan can't vouch for. A slice the wipe declines -- for "
+        "either guard, or because the dir was never configured -- says so on the "
+        "envelope and in text (`build.pristine-skipped`), so \"pristine\" never "
+        "silently means \"incremental\".",
+    ),
+    # --- retired: parsed (never a Click typo error) but always refused, ------
+    # naming the replacement in the message itself (tan-cli#427). NOT
+    # `inert_help`-marked: unlike the accept-and-drop global flags, these are
+    # READ for real -- their value selects a specific refusal, not "accepted
+    # and does nothing" (see `_RETIRED_FLAGS`).
+    plan: bool = typer.Option(
+        False, "--plan", help="Retired -- superseded by `--plan-from` (tan-cli#427)."
+    ),
+    manifest: bool = typer.Option(
+        False,
+        "--manifest",
+        help="Retired -- a native `tan build` already writes `build/system-manifest.yaml` "
+        "(tan-cli#427).",
+    ),
+    manifest_from: str = typer.Option(
+        None,
+        "--manifest-from",
+        metavar="FILE",
+        help="Retired -- open FILE directly, it is plain YAML (tan-cli#427).",
+    ),
+    # A real, working flag of the v0.4.1 oracle, retired here rather than
+    # implemented (tan-cli#427) -- `tan build` has no implicit bootstrap for it
+    # to switch off. LISTED in `--help` rather than hidden, for the same reason
+    # the three above are: a reader comparing this surface to v0.4.1's needs to
+    # see that tan knows the flag and is refusing it, which absence cannot say.
+    no_auto_bootstrap: bool = typer.Option(
+        False,
+        "--no-auto-bootstrap",
+        help="Retired -- `tan build` never bootstraps implicitly (tan-cli#427).",
+    ),
+) -> None:
+    """Build every slice of the project's build plan."""
+    json_mode = output_format == "json"
+
+    # Before anything is resolved or read: a run naming a retired or deferred
+    # flag does no work at all, and says which flag and why. Retired flags
+    # first (`_RETIRED_FLAGS` already teaches the replacement in its own
+    # message), then the one still-deferred flag -- same precedence reasoning
+    # as before: a flag this build cannot honour in any combination gets the
+    # accurate answer ahead of the `--execute`/`--materialise` conflict check
+    # below, rather than a conflict message for a flag that would not have
+    # worked anyway.
+    retired_given = {
+        "--plan": plan,
+        "--manifest": manifest,
+        "--manifest-from": manifest_from is not None,
+        "--no-auto-bootstrap": no_auto_bootstrap,
+    }
+    for flag, was_given in retired_given.items():
+        if was_given:
+            _refuse(
+                "build.flag-retired",
+                _RETIRED_FLAGS[flag],
+                ExitCode.VALIDATION_FAILURE,
+                json_mode,
+            )
+
+    if execute and materialise:
+        # Two different answers to "what does this run leave behind" -- one
+        # stops after writing, one goes on to dispatch. Refused with its own
+        # code at exit 2 (this CLI's position for an invalid invocation, the
+        # same `--format bogus` takes) instead of letting either win quietly:
+        # a silent precedence win here is precisely what `--execute` exists to
+        # replace.
+        _refuse(
+            "build.conflicting-flags",
+            "`--execute` and `--materialise` cannot be combined: `--materialise` "
+            "writes the plan's files and stops, `--execute` writes them and then "
+            "runs each slice. Pick one (`--execute` already implies writing).",
+            ExitCode.VALIDATION_FAILURE,
+            json_mode,
+        )
+
+    # The oracle's own precedence, measured, reproduced exactly -- `--native`
+    # included: `--plan-from` implies `--plan`, and that implied `--plan` beats
+    # an explicit `--native`, so `--plan-from --native` shows the plan and
+    # writes nothing here too. `--execute` is the port's ADDED capability (see
+    # the module docstring) and the only thing that dispatches a file-supplied
+    # plan; it selects the same `_MODE_NATIVE` a plain `tan build` runs, so it
+    # reports the same `data` rather than a shape of its own. With no
+    # `--plan-from` it is a no-op -- that run already builds.
+    if execute:
+        mode = _MODE_NATIVE
+    elif materialise:
+        mode = _MODE_MATERIALISE
+    elif plan_from is not None:
+        mode = _MODE_PLAN
+    else:
+        mode = _MODE_NATIVE
+
+    # `--pristine`'s own help text promises "never silently means incremental"
+    # -- but `_build` only ever threads `pristine` into `_dispatch` (see its
+    # tail), and `_MODE_PLAN`/`_MODE_MATERIALISE` both return from `_build`
+    # BEFORE `_dispatch` is reached (the former shows the plan and stops, the
+    # latter writes config files and stops -- neither runs a slice, so neither
+    # has a build dir to wipe). Left unchecked, `--pristine --plan-from p.json`
+    # or `--pristine --materialise ...` used to exit 0 with `issues: []`,
+    # having silently done nothing with the flag -- precisely the "declared
+    # and does nothing" shape `--no-auto-bootstrap` above is refused for, and
+    # the closed-issue tan-cli#183 defect class re-entering through the mode
+    # flags instead of the flag that issue was about. Refused with the same
+    # code and exit position `--execute --materialise` already uses for an
+    # invalid combination, rather than added as a fourth mode-specific `data`
+    # shape: `--pristine` has no meaning without a dispatch to apply it to, so
+    # this is a conflicting-flags case, not a new envelope shape to design.
+    # `--execute` is exempt: it selects `_MODE_NATIVE` (line 1918 above) and
+    # dispatches for real, so `--pristine --plan-from p.json --execute` reaches
+    # `_dispatch` and wipes exactly as `--pristine` alone does.
+    if pristine and mode != _MODE_NATIVE:
+        stops_after = (
+            "writes the plan's files"
+            if mode == _MODE_MATERIALISE
+            else "shows the plan"
+        )
+        flag = "--materialise" if mode == _MODE_MATERIALISE else "--plan-from"
+        _refuse(
+            "build.conflicting-flags",
+            f"`--pristine` has nothing to wipe without a dispatch: `{flag}` alone "
+            f"only {stops_after} and stops before any slice runs. Add `--execute` "
+            "to dispatch it for real, or drop `--pristine`.",
+            ExitCode.VALIDATION_FAILURE,
+            json_mode,
+        )
+
+    if core and not define:
+        _refuse(
+            "build.invalid-argument",
+            "`--core` only scopes `-D`; pass `-D NAME=VALUE` with it.",
+            ExitCode.VALIDATION_FAILURE,
+            json_mode,
+        )
+    plain_plan_text: str | None = None
+    # The raw flag, kept before `sdk_root` is reassigned to the RESOLVED root (None
+    # for a rejected flag) so the refusal below can name what the caller typed.
+    sdk_root_flag = sdk_root
+    if board is not None or define:
+        _refuse_plain_route(board, define, board_yaml, plan_from, mode, json_mode)
+
+    # `util::cli_workspace_root`: `--project` joined to the (real) cwd, THEN
+    # everything below anchors on this instead of the bare cwd -- board.yaml
+    # discovery, the default build root, and SDK discovery. Was previously
+    # missing entirely (this command had no `--project` at all): the extension
+    # falls back to it when no project is active in the workspace
+    # (`alp-sdk-vscode/src/west.ts`'s `alpBuild`, `--project <example> build`).
+    # A Typer option Typer does not declare is a Click parse error (exit 2),
+    # so the missing flag REFUSED outright rather than building silently; the
+    # actual wrong-project risk is the relative `--board-yaml` anchor fixed
+    # below. `project is None` (the overwhelming common case, no flag given)
+    # makes `workspace_root == cwd`, byte-for-byte the prior behaviour -- this
+    # only changes anything when `--project` is actually given.
+    #
+    # tan-cli#488 defect 8: safe defaults for every name the exception handler
+    # below and the final `emit()` read, so a raise from ANYWHERE in this
+    # resolution prologue -- not only inside `_build` -- still produces the
+    # `build.internal-failure` envelope the guard below promises, instead of a
+    # raw traceback with empty stdout. `Path.cwd()` immediately below is the
+    # concrete case: a working directory deleted out from under the process
+    # throws `FileNotFoundError` -- previously from OUTSIDE the `try`/`except`,
+    # before `project`/`sdk`/`sdk_tier` had a real value, so it unwound through
+    # typer's own traceback renderer instead of this command's error contract.
+    # Mirrors `doctor_cmd.doctor`'s identical fix for the same defect class.
+    project_envelope = Project(root=None, board_yaml=None)
+    sdk: SdkInfo | None = None
+    sdk_tier = "none"
+    sdk_broken_pin: str | None = None
+    sdk_foreign_default: str | None = None
+    sdk_divergence: Issue | None = None
+    try:
+        cwd = Path.cwd()
+        workspace_root = cwd if project is None else Path(os.path.join(str(cwd), project))
+
+        # Anchor an EXPLICIT `--board-yaml` on `workspace_root`, not the real cwd,
+        # before anything derives from it (the default build root below included).
+        # `_abs_posix` is purely lexical (`os.path.abspath`, which anchors on
+        # `os.getcwd()`), so a relative `--board-yaml` left untouched re-anchors on
+        # the real cwd instead -- matching Rust's `resolve_board_yaml_path`
+        # (`crates/tan-core/src/project.rs:198-208`, which joins a relative
+        # configured path onto `workspace_root`). Verified against the oracle in a
+        # scratch tree (`tmp/app/board.yaml`, cwd=`tmp`): `tan --project app build
+        # --board-yaml board.yaml --format json` must report `project.root` /
+        # `project.boardYaml` under `tmp/app`, not `tmp` -- with a board.yaml also
+        # sitting in the real cwd, the pre-fix anchor planned and built the WRONG
+        # project without a word, exactly the failure class this port exists to
+        # remove.
+        if board_yaml is not None and not os.path.isabs(board_yaml):
+            board_yaml = os.path.join(str(workspace_root), board_yaml)
+
+        # Resolution, in one place, before anything can fail -- and to ABSOLUTE,
+        # BOTH sides, from the same anchor.
+        #
+        # The divergence guard in `apply_plan_token_substitution` compares these
+        # two lexically (as the Rust oracle does), so they must move together: this
+        # resolves both or neither, never one. But they must also both be absolute,
+        # because `${PROJECT_ROOT}` is substituted from `board_yaml` and then
+        # CONSUMED from a different directory -- each slice runs its command in its
+        # own `command.cwd` (`<root>/build/<slice>`), and Zephyr resolves
+        # `-DEXTRA_CONF_FILE` against the APPLICATION source dir, which for the
+        # stock-shim slice is inside the SDK checkout entirely. Left relative, the
+        # default `cd <project> && tan build` resolves `${PROJECT_ROOT}` to `"."`
+        # and every zephyr slice dies -- `<sdk>/firmware/alp-stock-shim/./build/
+        # <slice>/alp.conf: File not found`, and `ERROR: . doesn't contain a
+        # CMakeLists.txt` -- which is the whole documented happy path. Rust never
+        # hits this because it anchors first: `resolve_cli_project_context_inner`
+        # builds `workspace_root = normalize_path(cwd.join(--project))` and derives
+        # `board_yaml_path` by joining onto THAT, so both are absolute before the
+        # guard ever runs (`crates/tan-cli/src/util.rs`, `crates/tan-core/src/
+        # project.rs::resolve_board_yaml_path`).
+        if board_yaml is None and (workspace_root / "board.yaml").is_file():
+            # Already absolute (anchored on `workspace_root`, not a bare
+            # relative "board.yaml") so `_abs_posix` below is a no-op
+            # normalisation rather than a re-anchor onto the real cwd -- the
+            # divergence that would reappear the moment `--project` differs
+            # from cwd.
+            board_yaml = str(workspace_root / "board.yaml")
+            if board is not None:
+                raise BuildError(
+                    "build.conflicting-flags",
+                    f"`--board` builds a project WITHOUT a board.yaml, but `{board_yaml}` "
+                    "exists -- drop `--board` to build it as a planned project.",
+                    ExitCode.VALIDATION_FAILURE,
+                )
+        if build_root is None:
+            build_root = str(Path(board_yaml).parent) if board_yaml else str(workspace_root)
+        build_root = _abs_posix(build_root)
+        if board_yaml is not None:
+            board_yaml = _abs_posix(board_yaml)
+
+        # `--sdk-root` > the project's own `.alp/sdk-path` pin > the machine-global
+        # default > the positional walk (`resolve_sdk_root_ladder`, above) --
+        # previously this skipped straight from `--sdk-root` to the positional
+        # walk, so `tan init`'s own pointer went unread the moment `tan build` ran
+        # in the same directory.
+        sdk_resolution = resolve_sdk_root_ladder(sdk_root, workspace_root)
+        resolved_sdk_root = sdk_resolution.path
+        sdk_tier = sdk_resolution.tier
+        sdk_broken_pin = sdk_resolution.broken_project_pin
+        sdk_foreign_default = sdk_resolution.foreign_global_default_for
+        # tan-cli#407: computed HERE, while `sdk_root` still holds the raw
+        # `--sdk-root` flag -- it is reassigned to the RESOLVED root a few lines
+        # below, and a bogus flag is blanked to `None` in between, which would
+        # make this warn about a discovery collision the user never reached
+        # because they named a root explicitly.
+        sdk_divergence = sdk_ladder_divergence_issue(sdk_root, workspace_root, wide=False)
+        # tan-cli#257/#258: `resolve_sdk_root_ladder` returns an explicit
+        # `--sdk-root` UNVALIDATED (I-31 terminal-for-REPORTING, matching the
+        # oracle's `resolve_sdk_tiered`) -- fine for a caller that only reports
+        # the tier, but `build` also ACTS on `resolved_sdk_root`, so a bogus flag
+        # used to sail through as `sdk.sourceTier: "sdkRootFlag"`, reach
+        # `_emit_plan` as a non-None `sdk_root`, and get refused for the NEXT
+        # missing thing (`no board.yaml found`) instead -- telling the customer
+        # their project is broken when the `--sdk-root` they just typed is what's
+        # wrong, and reporting an `sdk` key the oracle never emits on this path.
+        # Validated here, at the flag's own entry point, rather than in the
+        # shared ladder (which every other caller also relies on staying
+        # unvalidated) -- same shape as `clean_cmd.sdk_root_resolves` and
+        # `flash_cmd._resolve_sdk`, the two callers that already guard their own
+        # explicit `--sdk-root`. An unresolvable explicit root is treated as no
+        # root at all: `_emit_plan` then gives its own "no alp-sdk checkout
+        # found" refusal, and no `sdk` key is reported, matching the oracle.
+        if sdk_tier == "sdkRootFlag" and not is_sdk_root(resolved_sdk_root):
+            resolved_sdk_root = None
+        sdk_root = str(resolved_sdk_root) if resolved_sdk_root is not None else None
+        sdk = SdkInfo(sdk_root, sdk_tier) if sdk_root is not None else None
+        if board is not None:
+            plain_plan_text = plain_zephyr_plan(
+                _abs_posix(str(workspace_root)),
+                board,
+                normalise_defines(define or [])[0],
+                core_id=_plain_core_id(board, sdk_root),
+            )
+        # Absolute, `.`/`..`-collapsed, anchored on `workspace_root` -- what the
+        # sdk-switch-pristine guard actually compares (tan-cli#163), kept
+        # SEPARATE from `sdk_root` itself: an explicit `--sdk-root` is a
+        # documented, supported relative form, and `sdk_root` unchanged still
+        # feeds `${SDK_ROOT}` token substitution and the `sdk.root` envelope
+        # field verbatim, matching the Rust oracle's own split between
+        # `normalized_sdk_root_str` (stamp-only) and the raw `resolve_sdk_root`
+        # result used everywhere else.
+        sdk_root_for_stamp = (
+            str(normalize_path(workspace_root / sdk_root)) if sdk_root is not None else None
+        )
+        # tan-cli#236: `boardYaml` reported only when the file really exists --
+        # `board_yaml` itself stays unfiltered for `_build` below, which needs the
+        # unconditional path.
+        project_envelope = Project.resolved(build_root, board_yaml)
+
+        # tan-cli#287: the heartbeat that covers a silent slice (a first-build
+        # CMake configure, measured at 234.2s with nothing printed) is armed
+        # inside `_dispatch`, not here -- `_build`'s OTHER caller,
+        # `run_cmd._run`, bottlenecks through the identical
+        # `_dispatch` call and needs the same cover for a silent `tan run`. See
+        # `_dispatch`'s own docstring for the TTY/`json_mode` gating (unchanged:
+        # still never armed for `--format json`, stdout is untouched either way)
+        # and for the mode-gating this also fixes for free -- `_MODE_PLAN`/
+        # `_MODE_MATERIALISE` return from `_build` before `_dispatch` is ever
+        # reached, so neither ticks a heartbeat for a slow in-process planner
+        # that never runs CMake at all.
+        exit_code, data, issues = _build(
+            mode=mode,
+            plan_from=plan_from,
+            build_root=build_root,
+            sdk_root=sdk_root,
+            sdk_root_for_stamp=sdk_root_for_stamp,
+            board_yaml=board_yaml,
+            json_mode=json_mode,
+            pristine=pristine,
+            plain_plan_text=plain_plan_text,
+            defines=normalise_defines(define or [])[0],
+            define_cores=list(core) if core else None,
+        )
+    except BuildError as err:
+        message = err.message
+        if err.code == "build.sdk-root-unresolved":
+            # tan-cli#1423: where the ladder looked, beside the message's own remedy.
+            if (sdk_root_flag or "").strip():
+                # `--sdk-root` is terminal (I-31): no other tier was tried, so
+                # name the rejected value instead of recommending the flag or
+                # claiming the ladder was searched (tan-cli#1521).
+                message = rejected_sdk_root_message(sdk_root_flag, "Nothing was built.")
+            else:
+                message = with_sdk_search(message, workspace_root)
+        exit_code, data, issues = err.exit_code, None, [Issue(err.code, "error", message)]
+    except Exception as err:  # noqa: BLE001 -- see below
+        # The port's most-repeated defect class: an uncaught exception
+        # escapes as a raw traceback, stdout stays empty, and the
+        # extension renders nothing at all with no error on either side.
+        # Anything that reaches here is a tan bug, so it is reported as
+        # one -- with an envelope.
+        exit_code = ExitCode.INTERNAL_FAILURE
+        data = None
+        issues = [Issue("build.internal-failure", "error", f"{type(err).__name__}: {err}")]
+
+    # These facts are all about how the SDK ROOT was RESOLVED, so all are
+    # prepended ahead of whatever the build itself reported, and all survive a
+    # run that never planned anything -- a refusal is exactly when knowing
+    # which checkout answered matters most.
+    #
+    # tan-cli#263 review: `tan build` is the command a silently-missed
+    # `.alp/sdk-path` pin hurts most -- it builds against whichever tier the
+    # ladder fell through to and says nothing, where `sdk current` alone only
+    # helps someone already suspicious enough to run it. tan-cli#407 is the
+    # same argument for the two-checkout collision one tier below it, and
+    # tan-cli#464 the same again for a `globalDefault` answer a DIFFERENT
+    # project's bootstrap relocation actually decided -- `sdk current` was the
+    # only place this warning reached before; `tan build` is the one that
+    # silently compiles against the wrong checkout because of it.
+    resolution_issues = [
+        issue
+        for issue in (
+            project_pin_issue(sdk_broken_pin, sdk_tier),
+            sdk_divergence,
+            global_default_foreign_project_issue(sdk_foreign_default),
+        )
+        if issue is not None
+    ]
+    if resolution_issues:
+        issues = [*resolution_issues, *issues]
+
+    if json_mode:
+        emit(Envelope("build", project_envelope, data, issues, exit_code, sdk=sdk))
+    else:
+        _print_text_issues(issues, data)
+        _text_recap(mode, data)
+    raise typer.Exit(int(exit_code))
+
+
+def _print_text_issues(issues: list[Issue], data: dict | None) -> None:
+    """Print the `issues[]` block of the text recap, minus any line the
+    per-slice recap below is about to repeat verbatim (tan-cli#746).
+
+    Dedup and printing live in ONE function on purpose: a `_text_issues`
+    that only FILTERED could be dropped from the call site and every test of
+    it would stay green -- measured, that is exactly what happened (6 of 6
+    passing with the call removed). Keeping the print here means a test that
+    captures this function's output covers both halves.
+    """
+    for issue in _text_issues(issues, data):
+        print(f"{issue.severity}: {issue.message}", file=sys.stderr)
+
+
+def _text_issues(issues: list[Issue], data: dict | None) -> list[Issue]:
+    """Drop an `issues[]` line whose text the per-slice recap is about to
+    print verbatim anyway (tan-cli#746).
+
+    TEXT MODE ONLY -- the JSON envelope keeps every issue untouched. Two
+    deliberate features collide here and neither is wrong on its own:
+    `_missing_tool_issues` promotes a skip's reason into `issues[]` so a
+    JSON consumer sees it (tan-cli#283), and that reason carries the literal
+    searched-PATH list so a customer can fix it themselves (tan-cli#510).
+    In `--format json` those are two different fields. In text they are two
+    adjacent lines carrying the same string.
+
+    Measured on a Windows host with no `bitbake`, where the AEN801 SoM's
+    `a32_cluster` yocto slice is an EXPECTED skip: 2807 + 2801 = 5608
+    characters, twice the same 57-entry PATH, pushing the two `ok:` lines
+    and the `2 of 3 slice(s) built` summary below it.
+
+    Matched on the reason text, not on the issue code: `_missing_tool_issues`
+    is not the only producer that may wrap a slice reason, and a code list
+    here would silently stop covering the next one. An issue whose message
+    is NOT already on a slice line is always kept -- this only removes a
+    second copy, never information.
+    """
+    if not data:
+        return issues
+    reasons = {
+        result["reason"]
+        for result in (data.get("slices") or [])
+        if isinstance(result, dict) and result.get("reason")
+    }
+    if not reasons:
+        return issues
+    return [
+        issue
+        for issue in issues
+        if not any(
+            reason in issue.message and issue.message.endswith(reason)
+            for reason in reasons
+        )
+    ]
+
+
+def _text_recap(mode: str, data: dict | None) -> None:
+    """The stderr recap for whichever mode ran. Three shapes because `data`
+    has three shapes -- a plan-mode `data.slices[]` entry is a PLAN slice with
+    no `status` at all, so the build recap below would `KeyError` on it."""
+    if data is None:
+        return
+    if mode == _MODE_MATERIALISE:
+        print(
+            f"materialised {len(data['written'])} file(s) under {data['baseDir']}:",
+            file=sys.stderr,
+        )
+        for rel in data["written"]:
+            print(f"  {rel}", file=sys.stderr)
+        return
+    if mode == _MODE_PLAN:
+        print(
+            f"build plan (schema v{data.get('schemaVersion')}) -- {data.get('sku')}",
+            file=sys.stderr,
+        )
+        print(f"  board.yaml: {data.get('boardYaml')}", file=sys.stderr)
+        print(f"  build root: {data.get('buildRoot')}", file=sys.stderr)
+        slices = data.get("slices") or []
+        print(f"  slices ({len(slices)}):", file=sys.stderr)
+        for sl in slices:
+            print(
+                f"    - {sl.get('coreId')} [{sl.get('backend')}] -> {sl.get('buildDir')}",
+                file=sys.stderr,
+            )
+        print(
+            f"  shared artefacts: {len(data.get('sharedArtefacts') or [])}",
+            file=sys.stderr,
+        )
+        # tan-cli#1000, oracle parity: the retired Rust `summarize_plan`
+        # (`crates/tan-core/src/build_plan.rs:358`, read at `2883cdf^`)
+        # printed `warnings: 0` when empty and otherwise expanded every
+        # entry as `  - [{code}] {coreId}: {message}`. The port counted them,
+        # so this surface lost the same cause the ordinary build path did.
+        plan_warnings = data.get("warnings") or []
+        if not plan_warnings:
+            print("  warnings: 0", file=sys.stderr)
+        else:
+            print(f"  warnings ({len(plan_warnings)}):", file=sys.stderr)
+            for warning in plan_warnings:
+                core_id = warning.get("coreId")
+                where = f" {core_id}:" if core_id else ""
+                print(
+                    f"    - [{warning.get('code')}]{where} {warning.get('message')}",
+                    file=sys.stderr,
+                )
+        return
+    slices = data.get("slices", [])
+    for result in slices:
+        reason = f" -- {result['reason']}" if "reason" in result else ""
+        # tan-cli#510 review, MAJOR 1: shown for a failed/cancelled slice
+        # only (`missingTool`'s own refusal already names what it searched
+        # in `reason` above, unaffected by this) -- a success needs nothing
+        # more explained, and `resolvedTool` is already `null` whenever it
+        # would just echo back the plan's own `tool` identity (see
+        # `SliceOutcome.resolved_tool`'s docstring). Deliberately NOT folded
+        # into `reason` itself -- see `_slice_result`'s own docstring for why.
+        resolved_tool = result.get("resolvedTool")
+        resolved_note = (
+            f" (resolved to `{resolved_tool}`)"
+            if result["status"] == "failed" and resolved_tool
+            else ""
+        )
+        print(
+            f"{result['status']}: {result['coreId']} [{result['backend']}]{reason}{resolved_note}",
+            file=sys.stderr,
+        )
+    # tan-cli#283: a one-line summary AFTER every per-slice line, so a
+    # partial or all-skipped build cannot be scrolled past -- the per-slice
+    # lines above already carry this same count, but only for a reader who
+    # counts them by hand.
+    if slices:
+        built = sum(1 for result in slices if result["status"] == "ok")
+        print(f"{built} of {len(slices)} slice(s) built", file=sys.stderr)
+
+
+# tan-cli#427: `--target`/`--all`/`--verbose`/`--quiet`/`--no-color`/
+# `--non-interactive`/`--ci` are accept-and-drop here, same as on every other
+# command `accept_global_flags` already covers -- the oracle's own `cli.rs`
+# declares all seven ONLY on the shared `GlobalArgs` struct (`BuildArgs` has
+# no fields for any of them), so `build`'s Rust handler never reads them
+# either. `--project`/`--board-yaml`/`--sdk-root` are already declared above
+# for real, so this adds nothing for those three (`_declared_flags` skips a
+# flag `build` already reads).
+build = accept_global_flags(build)