tan-cli 0.7.0__py3-none-any.whl

tan/commands/doctor_cmd.py

@@ -0,0 +1,4767 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`tan doctor` -- is this host actually able to build and flash?
+
+Every check here answers a question some customer already lost an afternoon to.
+Two of them exist because the answer used to be a confident, wrong "Pass".
+
+**The Python floor is not what the manifest says it is.**
+`metadata/bootstrap.json` declares `prerequisites.pythonMinVersion` (read live
+below, currently `"3.10"` on alp-sdk's `dev`), while separately
+Zephyr's `cmake/modules/python.cmake` sets `PYTHON_MINIMUM_REQUIRED 3.12`. And
+the Rust oracle's POSIX bootstrap branch was explicit that it "cannot fail on
+version" (`crates/tan-cli/src/commands/bootstrap/steps.rs:230-234`). Ubuntu 22.04
+ships `python3` = 3.10. Compose the three and a fresh customer got: `tan
+bootstrap` succeeds, `tan doctor` reports Pass, and the FIRST build dies inside
+Zephyr's CMake configure with an error naming Zephyr, not us. So the floor this
+command enforces is the EFFECTIVE one -- the higher of the manifest's and
+Zephyr's -- and where the two disagree that disagreement is itself reported
+(`pythonFloor`), naming which is which, so the fix lands in the manifest instead
+of in the customer.
+
+**"Zephyr's" used to mean whatever `$ZEPHYR_BASE` pointed at, not the
+workspace the report was actually about (tan-cli#301).** `zephyrWorkspace`
+(tan-cli#290) reads the RESOLVED west topdir (`west_workspace_dir`); until now
+`hostPython`/`pythonFloor` independently re-read `$ZEPHYR_BASE`, which is
+extremely commonly stale -- Zephyr's own docs, and this command's own
+`tan bootstrap` next-steps block, both tell a customer to export it. One
+report could then name two different Zephyrs: `zephyrWorkspace` passing
+against the real workspace while `hostPython`'s floor, and the interpreter it
+demanded, came from an unrelated tree the customer was not building against.
+`_collect` now feeds `zephyr_python_floor` the SAME resolved `workspace_path`
+`zephyrWorkspace` reports, falling back to a literal `$ZEPHYR_BASE` read only
+when no workspace resolves at all, and to `ZEPHYR_PYTHON_FLOOR` when neither
+does -- see `zephyr_python_floor`'s docstring for the three-way split.
+
+`tan bootstrap` now enforces the same effective floor on BOTH platforms, by
+calling `zephyr_python_floor` below rather than re-deriving it -- see
+`tan.commands.bootstrap_cmd.resolve_python_floor`. Keep that the ONE reader: a
+second floor rule is how the two commands come to disagree about the same host,
+which is worse than either verdict alone.
+
+**SETOOLS was never mentioned by any doctor.** Neither `alp doctor`
+(`scripts/alp_cli/doctor.py` -- it has `_check_python`, `_check_west`,
+`_check_jlink`, and nothing for this) nor the shipped `tan doctor` says a word
+about `SETOOLS_DIR` or `SE_UART`. A customer therefore gets a clean bill of
+health and then meets a bare `RuntimeError` out of
+`scripts/west_commands/runners/alif_flash.py` at the moment they try to flash an
+AEN part. The `setools` check names both, plus the Alif developer download
+(`app-release-exec-linux-SE_FW_x.y.z`) it cannot redistribute.
+
+**This check used to ALSO gate on `fdt` being importable under some Python
+interpreter, and that was a false negative even after tan-cli#488 defect 6
+picked the "right" interpreter to ask (tan-cli#641).** Measured on real AEN
+silicon, on a host where Flow D had just succeeded three times in the same
+session: `fdt` genuinely was not importable in the workspace venv, yet
+`app-gen-toc` ran fine, produced
+`app-package-map.txt`, and the MRAM write it fed survived a cold power cycle.
+Whatever `alif_flash.py`'s own `fdt` need is for the SE-UART `west flash`
+path, this check's own wording bundled it into one verdict alongside
+`app-gen-toc` -- which `tan.core.setools.sign_slot0` spawns as its own
+subprocess (`./app-gen-toc -f build/config/...`), never as a Python import
+under any interpreter this command could probe -- and SETOOLS ships whatever
+dependencies IT needs regardless. Dropped rather than reworded again: probing
+one interpreter's `sys.path` was never going to answer "will a flash that
+spawns a separate, license-gated binary succeed," and the false alarm this
+produced trains an operator to stop trusting doctor on the one question they
+ask it before a write.
+
+**Nothing that probes may throw.** Four Criticals in this port were uncaught
+exceptions escaping the error contract: a raw traceback instead of an envelope,
+so the VS Code extension renders nothing at all and neither side reports an
+error. `doctor` interrogates a hostile environment BY DEFINITION -- a missing
+binary, an unreadable directory, a tool that waits for a probe that is not
+plugged in, a subprocess that answers in bytes that are not UTF-8. Every one of
+those becomes a structured issue here; `probe()` is the single choke point and
+it has a timeout on every call.
+
+**Exit 4, never 0, when unhealthy.** A doctor that exits 0 on a broken
+environment is worse than no doctor: it converts a fixable setup problem into a
+mystery inside somebody else's build system.
+
+Deliberately NOT ported from `crates/tan-cli/src/commands/doctor.rs`: the debug
+half (`--target-kind`/`--server`, the cortex-debug/CodeLLDB extension set).
+That needs context this port has no command to produce yet, and half a debug
+verdict is worse than none. The envelope keys that survive --
+`data.summary.{pass,warn,fail}` and `data.checks[]` -- are the ones
+`alp-sdk-vscode` actually reads (`src/debug.ts`, `src/toolchain.ts`).
+
+**`--build` is accepted, real, and now (tan-cli#290) a no-op vs. plain `tan
+doctor` -- not the Rust oracle's second, disjoint check vocabulary.**
+Measured against a real `tan.exe`, plain `tan doctor` and `tan doctor
+--build` run two almost entirely different check lists (debug-readiness vs.
+zephyr/yocto/baremetal build-readiness -- compare `tan doctor`'s
+`workspaceRoot`/`codeLLDBExtension`/`lldb` against `tan doctor --build`'s
+`git`/`cmake`/`ninja`/`dtc`/`gperf`/`vendorToolchain`/...). Byte-parity with
+BOTH of those lists is a second command's worth of new checks, not a flag
+gap -- and this port's own check list -- `hostPython`/`hostPrerequisites`/
+`west`/`zephyrSdk`/`setools`/`jlink`, plus (tan-cli#294) `sdk`/`boardYaml`/
+`workspace`/`zephyrVersion`/`zephyrSdkAvailableForHost`/`longPaths`/
+`homePath`/`sdkProvenance`, plus (tan-cli#290) `westResolved`/
+`zephyrWorkspace` -- is ALREADY build/flash-oriented by design (see above),
+unlike the Rust oracle's PLAIN `doctor`. `zephyrWorkspace` -- whether the
+RESOLVED workspace's Zephyr matches alp-sdk's `west.yml` pin -- used to be
+the ONE check this flag gated; ADR 0021 Lane 1 P0a runs PLAIN `tan doctor`
+as the very first command a customer types, before `--build` is ever named,
+so gating it there left the exact alp-sdk#855 v4.4.0->v4.4.1 drift invisible
+on that first run. It is unconditional now, alongside every other
+tan-cli#294/#290 fact -- `--build` therefore changes nothing about this
+port's check-name set any more. The flag stays accepted rather than
+removed: both `alp-sdk-vscode` call sites (`["doctor", "--build"]`,
+`["doctor", "--build", "--fix"]`) still pass it, and a flag a caller already
+relies on does not need to keep doing something to still be worth accepting
+without error.
+
+**One name out of that unported `--build` vocabulary came BACK, deliberately
+and partially (tan-cli#1192): `dtc`, and only as `devicetreeLint`.** The
+sentence above still holds for `git`/`cmake`/`ninja`/`gperf`/`vendorToolchain`
+-- none of those is ported and none is planned -- but `dtc`'s premise changed
+underneath it. When this paragraph was written the Zephyr SDK put a `dtc` in
+CMake's reach on every install, so probing for one could only restate what
+`zephyrSdk` already said. Since tan-cli#1176/#1178 `tan bootstrap` acquires
+the SDK with `--no-hosttools`, the SDK ships no `dtc`, and Zephyr's
+devicetree LINT pass (`dts.cmake`'s `if(DTC)` block) silently stopped running
+with nothing on either side saying so. `devicetreeLint` is not the oracle's
+`dtc` check re-ported -- that one was a bare is-it-on-PATH presence probe,
+which after #1178 would warn on every correct install -- it is the narrower
+question that probe cannot answer; see `devicetree_lint_check` for the
+predicate and the severity argument.
+
+`--fix` is a separate, NOT-yet-ported flag gap (it is not part of this one):
+the oracle's `--build --fix` auto-repairs a missing Zephyr workspace by
+running `tan bootstrap`, and nothing here does that yet.
+"""
+import json
+import os
+import platform
+import re
+import shlex
+import subprocess
+import sys
+import tempfile
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import typer
+
+from tan.commands.build.toolchain import _is_toolchain_wreckage, _toolchain_store_scan_root
+from tan.commands.flash_cmd import _tool_available
+from tan.commands.sdk_cmd import (
+    NO_SDK_NEXT_STEPS,
+    global_default_pointer_fix_hint,
+    parse_sdk_version_yaml,
+)
+from tan.core import artifact_provenance
+from tan.core.artifact_provenance import ArtifactProvenance
+from tan.core.bootstrap import (
+    BOOTSTRAP_MANIFEST_SCHEMA_VERSION,
+    MissingPrerequisite,
+    PrereqFailure,
+    WorkspaceSdkRecord,
+    confirm_missing,
+    detect_linux_pm,
+    normalize_linux_install,
+    parse_west_zephyr_pin,
+    parse_workspace_sdk_record,
+    parse_zephyr_version_file,
+    posix_venv_unusable,
+    reported_missing,
+    select_linux_install,
+)
+from tan.core.consent import can_prompt
+from tan.core import devicetree_lint
+from tan.core.doctor_git import (
+    _git_behind_upstream,
+    _git_core_longpaths,
+    _git_short_commit,
+    _is_own_git_checkout,
+    _resolve_git_executable,
+    classify_git_core_longpaths,
+)
+from tan.core.doctor_stale import StaleVerdict, running_tan_verdict
+from tan.core.doctor_libraries import LibraryReport, inspect_selection
+from tan.core.doctor_render import render_check_lines, render_doctor_footer
+from tan.core.doctor_scope import CHECK_SCOPES
+from tan.core.doctor_setools import (
+    FLOW_A_METHOD,
+    FLOW_D_METHOD,
+    project_flash,
+)
+from tan.core.doctor_setools import verdict as setools_verdict
+from tan.core.global_flags import accept_global_flags
+from tan.core.inert import COMPATIBILITY, inert_help
+from tan.core.python_floor import (
+    FALLBACK_PYTHON_FLOOR,
+    ZEPHYR_PYTHON_FLOOR,
+    effective_python_floor,
+    zephyr_python_floor,
+)
+from tan.core.host_python import (
+    describe_unsuitable,
+    probe_all_host_pythons,
+    select_host_python,
+)
+from tan.core.probe import PROBE_TIMEOUT_S, probe, probe_status
+from tan.core.subprocess_env import spawn_env
+from tan.core.sdk_default_registry import registry_path
+from tan.core.sdk_discovery import (
+    SDK_DISCOVERY_DIVERGENT,
+    _abs_posix,
+    _has_loader_script,
+    _home_alp_dir,
+    _pointer_target,
+    discover_sdk_root,
+    global_default_foreign_project_issue,
+    project_pin_issue,
+    resolve_sdk_root_ladder,
+    resolve_sdk_root_wide,
+)
+from tan.core.shapes import is_sdk_root, rejected_sdk_root_message
+from tan.core.timestamp import generated_at_iso
+from tan.core import toolchain_provision
+from tan.core.tool_lookup import resolve_tool
+from tan.commands.workspace_patch_check import (
+    APPLIED as WORKSPACE_PATCHES_APPLIED,
+    MISSING as WORKSPACE_PATCHES_MISSING,
+    PatchCheck,
+    check_workspace_patches,
+)
+from tan.core.west_patches import describe_unapplied, patch_fix_text, zephyr_base_note
+from tan.core.venv import find_workspace_venv, venv_bin_dir, west_program, west_workspace_dir
+from tan.core.west_workspace_refusal import unresolved_workspace_verdict
+from tan.env import TEXT_WRAP_MIN_WIDTH, stderr_is_tty, stdin_is_tty, terminal_width, use_color
+from tan.envelope import Envelope, Issue, Project, SdkInfo, emit
+from tan.exit_codes import ExitCode
+from tan.output_format import FORMAT_HELP, OutputFormat
+
+#: The SETOOLS executables `alif_flash.py` looks for inside `$SETOOLS_DIR`
+#: (its `--app-gen-toc` / `--app-write-mram` defaults).
+SETOOLS_EXECUTABLES = ("app-gen-toc", "app-write-mram")
+
+#: The Alif developer-portal bundle `$SETOOLS_DIR` must point INTO. The `-linux`
+#: is not incidental: `alif_flash.py` hard-codes `app-release-exec-linux` in the
+#: refusal it raises, so this path is Linux-only in this tree.
+SETOOLS_BUNDLE = "app-release-exec-linux-SE_FW_x.y.z"
+
+#: The J-Link DLL that first shipped Alif's built-in MRAM flash loader. Below
+#: this, Flow D has nothing to program MRAM with.
+JLINK_MIN_DLL = (9, 46)
+
+#: The device profile that UNLOCKS that loader. The generic `Cortex-M55` profile
+#: connects fine for read/attach/RAM-run and has no MRAM loader at all, so a
+#: Flow D burn against it silently is not one.
+JLINK_AEN_DEVICE = "AE822FA0E5597LS0_M55_HE"
+
+#: The Zephyr SDK release `west sdk install --version` pins. Mirrors
+#: `tan_core::host_env::ZEPHYR_SDK_INSTALL_VERSION` byte-for-byte, so the
+#: `zephyrSdk` check's fix hint below and the Rust oracle's own can never name
+#: two different versions.
+#:
+#: A NEW consumer of the pin `contract/fixtures/toolchains/toolchains.json`
+#: owns -- that fixture's own `_comment` states the rule verbatim: "A NEW
+#: consumer of this pin needs its own parity assertion; widening this scan
+#: will not reach it." `test_zephyr_sdk_install_version_matches_the_real_
+#: toolchain_lock` (test_doctor_command.py) is that assertion, mirroring
+#: `crates/tan-core/src/host_env.rs`'s test of the same name (tan-cli#172) --
+#: without it, an alp-sdk version bump makes Rust fail loudly and this
+#: constant go silently stale.
+ZEPHYR_SDK_INSTALL_VERSION = "1.0.1"
+
+#: PATH names west's `.7z` toolchain extraction (via patoolib, which shells
+#: out to an external binary with no pure-Python fallback) will accept --
+#: mirrors `crate::build_readiness::SEVEN_ZIP_PROGRAMS` byte-for-byte. Any ONE
+#: is enough; probing only `7z` would false-negative a host that has `7zz` or
+#: `unar` instead.
+SEVEN_ZIP_PROGRAMS = ("7z", "7za", "7zr", "7zz", "7zzs", "unar")
+
+#: Verified resolvable (`winget show 7zip.7zip` -> `Found 7-Zip [7zip.7zip]`,
+#: publisher Igor Pavlov) -- mirrors `crate::build_readiness::
+#: SEVEN_ZIP_INSTALL_COMMAND` byte-for-byte.
+SEVEN_ZIP_INSTALL_COMMAND = "winget install -e --id 7zip.7zip"
+
+#: The host platforms the pinned Zephyr SDK (`ZEPHYR_SDK_INSTALL_VERSION`
+#: above) actually publishes a build for -- mirrors
+#: `tan_core::host_env::ZEPHYR_SDK_HOSTS` byte-for-byte (tan-cli#294 finding
+#: 1, reintroducing tan-cli#70). `windows-arm64` was never published at any
+#: release; `macos-x86_64` was dropped in the 1.0.0 line the pinned SDK is
+#: past. Spelled in the SDK's own release-asset tokens (`x86_64`, not `x64`).
+ZEPHYR_SDK_HOSTS = ("linux-aarch64", "linux-x86_64", "macos-aarch64", "windows-x86_64")
+
+
+@dataclass(frozen=True)
+class Check:
+    """One verdict. `status` is the Rust `DoctorStatus` vocabulary verbatim:
+    `pass` / `warn` / `fail` / `unknown`, where `unknown` means the question was
+    not askable on this host -- counted in NO summary bucket and raising no
+    issue, so an unverifiable assumption is never rendered as observed fact.
+
+    `code` overrides the default `doctor.<name>` issue code. It exists for the
+    three FROZEN `bootstrap.*` codes (`contract/issue-codes.json`), which
+    `alp-sdk-vscode`'s `PREREQ_CODES` matches with `Set.has()` -- an unrecognised
+    code there is indistinguishable from "no problem", so the spelling is load-
+    bearing and must not be re-derived from the check name.
+
+    `missing` carries the structured per-tool form of a `hostPrerequisites`
+    refusal (tan-cli#294 finding 4: `data.missingPrerequisites`) -- NOT
+    serialized by `as_dict()` below, unlike every other field: it does not
+    ride on the per-check JSON at all (mirroring Rust's `DoctorCheck`, which
+    has no such field either), only on the report-level
+    `data.missingPrerequisites` `doctor()` builds from it. Since tan-cli#760
+    it is the tan-cli#760-CONFIRMED half: a tool whose manifest command's own
+    leading binary (`sudo` included) does not resolve on this host's PATH
+    reports `command: null` here, never a string a human or `alp-sdk-
+    vscode`'s Fix button could run and fail on.
+
+    `fix_missing` is `missing`'s RAW twin, tan-cli#760 review MAJOR 1: it
+    carries the SAME `{tool, command}` pairs `missing` would carry with no
+    confirmation guard applied at all, and is what `doctor()`'s `--fix`
+    branch feeds `run_fix` -- never `missing` itself. `run_fix` has done its
+    OWN PATH resolution and reported `doctor.fix-installer-not-found` since
+    tan-cli#360; feeding it the CONFIRMED (already-nulled) dict instead would
+    turn that diagnosis into a silent no-op the moment the installer itself
+    is unconfirmed -- exactly the `--fix` silence #360 exists to prevent, on
+    the very host (a fresh Mac with no Homebrew, a Windows image with no
+    usable winget) #360 was written for. Also NOT serialized, for the same
+    reason `missing` is not: it exists purely for `--fix`'s in-process input,
+    never the wire.
+
+    A `hostPrerequisites` Check built with only `missing=` (omitting
+    `fix_missing=`) is not left silently `--fix`-disabled: `__post_init__`
+    falls back to `missing` itself when `fix_missing` is `None`, matching
+    `prerequisites_check`'s own `available=None` behaviour -- the two fields
+    equal, pre-#760's shape. A future 9th construction site that forgets the
+    pairing therefore fails SAFE (pre-#760 `--fix` behaviour) rather than
+    silently.
+
+    `scope` (tan-cli#549) is `host` or `project` -- see `tan.core.doctor_scope`
+    for the two definitions and the judgement calls. REQUIRED and KEYWORD-ONLY,
+    which is the enforcement mechanism itself: a check authored without one is
+    a `TypeError` at its own construction site, in every branch, on every
+    platform, including the ones no test host reaches (`longPaths`, `sevenZip`,
+    the six `fix:*` outcomes). A default -- any default -- would put the
+    consumer straight back on a hand-list for whatever the default silently
+    mislabelled, which is the failure this field exists to end. Keyword-only so
+    it can be required without renumbering the positional `fix` argument a
+    dozen call sites here already pass positionally.
+    """
+
+    name: str
+    status: str
+    detail: str
+    fix: str | None = None
+    code: str | None = None
+    #: `str | int | None` values since tan-cli#1066: an entry carries
+    #: `sizeBytes` (an int, or `null`) alongside its two string fields.
+    missing: list[dict[str, str | int | None]] | None = None
+    fix_missing: list[dict[str, str | int | None]] | None = None
+    scope: str = field(kw_only=True)
+
+    def __post_init__(self) -> None:
+        # A `str` annotation does not stop `scope=""` or a typo'd `"Host"`, and
+        # a consumer filtering on `scope` cannot tell an unrecognised value from
+        # a row it is meant to hide -- the same fail-open silence the
+        # name-matching seam had. Refuse at construction instead. Every value in
+        # this package is a literal that `test_doctor_check_scope.py` already
+        # checks statically, so this arm is unreachable from shipping code; it
+        # is here for a caller that computes one.
+        if self.scope not in CHECK_SCOPES:
+            raise ValueError(
+                f"doctor check {self.name!r} declares scope {self.scope!r}; "
+                f"the wire vocabulary is {CHECK_SCOPES}"
+            )
+        # tan-cli#760 review round 3, MINOR: a `hostPrerequisites` Check
+        # authored with only `missing=` (a 9th call site nobody remembered to
+        # pair with `fix_missing=`) must not silently disable `--fix` --
+        # `object.__setattr__` because `Check` is frozen, and this is the one
+        # place a divergent-by-omission construction can still be caught and
+        # repaired rather than reddening `run_fix` with a `None` input. Falls
+        # back to `missing` itself, matching `prerequisites_check`'s own
+        # `available=None` behaviour (pre-#760: the two fields identical) --
+        # fails SAFE at pre-#760 `--fix` behaviour, never silent. A no-op
+        # when `missing` is also `None` (every non-`hostPrerequisites` Check).
+        if self.fix_missing is None:
+            object.__setattr__(self, "fix_missing", self.missing)
+
+    def as_dict(self) -> dict:
+        # `scope` between `status` and `detail`: the three machine-read fields
+        # first, the prose last. Key ORDER is not a contract on this seam
+        # (`contract/README.md`, "What a golden does NOT cover: key ORDER") --
+        # both conformance harnesses compare parsed maps -- so this is
+        # readability, not compatibility.
+        out = {
+            "name": self.name,
+            "status": self.status,
+            "scope": self.scope,
+            "detail": self.detail,
+        }
+        # Omitted when absent, not null -- Rust's `skip_serializing_if`.
+        if self.fix is not None:
+            out["fix"] = self.fix
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Probing. `probe_status`/`probe` (tan.core.probe) are every subprocess this
+# module's checks read a tool's own answer through; `on_path` below is the
+# PATH-only presence walk. Every filesystem read goes through one of these
+# three, and none of them can raise. `probe_status`/`probe`/`PROBE_TIMEOUT_S`
+# moved to `tan.core.probe` (tan-cli#797 module-size budget) so
+# `tan.core.doctor_git` could depend on them without an import cycle back
+# into this file; re-imported here so every existing `probe(...)` call site
+# below, and every test referencing `doctor_cmd.probe`/`doctor_cmd.
+# PROBE_TIMEOUT_S`, keeps resolving unchanged.
+# ---------------------------------------------------------------------------
+
+
+def on_path(command: str) -> str | None:
+    """Resolve `command` against `$PATH`, returning its full path.
+
+    NOT `shutil.which`: on Windows that inserts `os.curdir` ahead of PATH
+    (documented Windows search order), so a project checked out with its own
+    `west.exe`/`openocd.exe` at its root would be reported as this host's
+    tooling -- and a later flow would spawn exactly that project-controlled
+    binary.
+
+    ONE LOOKUP, NOT A SIXTH COPY (tan-cli#532). This used to hand-roll the
+    walk; it now delegates to `tan.core.tool_lookup.resolve_tool`, which
+    `build/execute.py`, `flash_cmd.py` and `size_cmd.py` already call.
+    `faultdecode_cmd` reaches the lookup THROUGH here, so this retires the
+    last two of the five copies. Only the FINDING is shared -- the signature
+    stays `str | None` so each caller keeps its own policy about a miss; ask
+    `resolve_tool` directly for its `searched` record.
+
+    WINDOWS BEHAVIOUR CHANGED, deliberately: the old copy's `[""] + %PATHEXT%`
+    accepted a bare extension-less `%PATH%` file ahead of every suffixed
+    sibling, and `resolve_tool` never tries the bare name. Reasoning and the
+    oracle comparison are in `tool_lookup`'s docstring; pinned by
+    `test_bare_argv0_spawn.py::
+    test_the_windows_walk_never_considers_the_bare_extensionless_name`, and
+    the delegation itself by `test_doctor_on_path_consolidation.py`. POSIX is
+    unaffected.
+
+    `os.environ`, not a threaded env: this is the doctor's HOST probe. Paths
+    resolving against a constructed environment (a workspace venv prepended)
+    call `resolve_tool` with that env and never come through here.
+    """
+    return resolve_tool(command, os.environ).resolved
+
+
+def _read_text(path: Path) -> str | None:
+    try:
+        return path.read_text(encoding="utf-8", errors="replace")
+    except (OSError, ValueError):
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Version floors
+# ---------------------------------------------------------------------------
+
+
+def _parse_two(raw: str) -> tuple[int, int] | None:
+    """`"3.12"`, `"v1.2.0"`, `"West version: v1.2.0"` -> `(major, minor)`."""
+    match = re.search(r"(\d+)\.(\d+)", raw)
+    if match is None:
+        return None
+    return (int(match.group(1)), int(match.group(2)))
+
+
+def jlink_flash_device(sdk_root: str | None) -> tuple[str, str]:
+    """The Flow-D part-number J-Link device profile, and where it came from.
+
+    Read from `<sdk>/metadata/socs/alif/ensemble/e8.json`
+    `variants[].debug.jlink_flash_device` -- the ONE variant carrying that key
+    is the one with an MRAM loader profile at all; the other AE822 package
+    variant's `debug` has a `jlink_device` (attach) entry but no
+    `jlink_flash_device`, because it has no Flow D loader to unlock.
+
+    `JLINK_AEN_DEVICE` is the fallback for THREE distinct causes, and the
+    returned source string names WHICH one fired (tan-cli#310) -- they used
+    to collapse into one sentence that only ever matched the first, so a host
+    with a perfectly good SDK checkout got told "no alp-sdk checkout
+    resolved" in the same envelope that reported resolving one:
+
+    1. no `sdk_root` at all -- the honest "nothing to read from" case;
+    2. `sdk_root` resolved but `e8.json` is missing, unreadable, or does not
+       parse as a JSON object -- named with the exact path that was tried;
+    3. `sdk_root` resolved and `e8.json` parsed fine, but no variant carries
+       `debug.jlink_flash_device` -- the real state of a checkout predating
+       alp-sdk#1057, which publishes this fact into a per-board `flash_args`
+       value instead; doctor has no board selected to read one from, so the
+       built-in constant is the honest answer, not a resolution failure.
+
+    Every variant is checked, not just the first hit: if a future package
+    variant declares a DIFFERENT `jlink_flash_device`, picking whichever
+    serialises first would silently advise the wrong part with nothing to
+    catch it. More than one DISTINCT value is ambiguous, not resolved -- it
+    falls back to `JLINK_AEN_DEVICE` with a source that says so, rather than
+    guessing.
+
+    Never raises: a missing SDK, an unreadable or malformed `e8.json`, or no
+    variant carrying the key all fall back the same way -- doctor's whole job
+    is to run on a host where things are wrong.
+    """
+    if not sdk_root:
+        return JLINK_AEN_DEVICE, (
+            f"tan's built-in fallback {JLINK_AEN_DEVICE} -- no alp-sdk checkout "
+            "resolved to read metadata/socs/alif/ensemble/e8.json "
+            "variants[].debug.jlink_flash_device from"
+        )
+
+    path = Path(sdk_root) / "metadata" / "socs" / "alif" / "ensemble" / "e8.json"
+    text = _read_text(path)
+    doc = None
+    if text is not None:
+        try:
+            doc = json.loads(text)
+        except ValueError:
+            doc = None
+    if not isinstance(doc, dict):
+        return JLINK_AEN_DEVICE, (
+            f"tan's built-in fallback {JLINK_AEN_DEVICE} -- {path} is missing, "
+            "unreadable, or did not parse as a JSON object, so its "
+            "variants[].debug.jlink_flash_device could not be read"
+        )
+
+    found: set[str] = set()
+    for variant in doc.get("variants") or []:
+        if not isinstance(variant, dict):
+            continue
+        debug = variant.get("debug")
+        device = debug.get("jlink_flash_device") if isinstance(debug, dict) else None
+        if isinstance(device, str) and device:
+            found.add(device)
+    if len(found) == 1:
+        return next(iter(found)), str(path)
+    if len(found) > 1:
+        return JLINK_AEN_DEVICE, (
+            f"tan's built-in fallback {JLINK_AEN_DEVICE} -- {path} "
+            f"variants[].debug.jlink_flash_device carries {len(found)} "
+            "DIFFERENT values across variants (ambiguous), refusing to "
+            "pick one arbitrarily"
+        )
+    return JLINK_AEN_DEVICE, (
+        f"tan's built-in fallback {JLINK_AEN_DEVICE} -- {path} parsed but no "
+        "variant carries debug.jlink_flash_device; alp-sdk#1057 publishes this "
+        "profile into a per-board flash_args value instead, and doctor has no "
+        "board selected to read one from"
+    )
+
+
+def _fmt(version: tuple[int, int]) -> str:
+    return f"{version[0]}.{version[1]}"
+
+
+# ---------------------------------------------------------------------------
+# The checks. Pure: probed facts in, a verdict out.
+# ---------------------------------------------------------------------------
+
+
+def python_check(
+    found: tuple[str, tuple[int, int]] | None, floor: tuple[int, int], floor_source: str
+) -> Check:
+    """`hostPython` -- is there an interpreter, and does it clear the EFFECTIVE
+    floor?
+
+    `found` is `(how it is spelled, (major, minor))` for the best candidate that
+    actually RAN. `None` is not "too old", it is "nothing runs": the Microsoft
+    Store `python.exe` alias satisfies any presence check and prints nothing,
+    which is why the probe insists on parseable output rather than existence.
+    """
+    if found is None:
+        return Check(
+            "hostPython",
+            "fail",
+            "no runnable Python interpreter found -- none of `python3`/`python`"
+            + (" / `py -3`" if os.name == "nt" else "")
+            + " ran and reported a version.",
+            "Install Python "
+            + _fmt(floor)
+            + "+ and put it on PATH."
+            + (
+                " On Windows, a `python.exe` that opens the Microsoft Store is the"
+                " Store ALIAS, not an interpreter: disable it under Settings > Apps >"
+                " App execution aliases, or install from python.org."
+                if os.name == "nt"
+                else ""
+            ),
+            # FROZEN (contract/issue-codes.json). Spelled, never derived.
+            code="bootstrap.python-not-runnable",
+            scope="host",
+        )
+    binary, version = found
+    if version < floor:
+        return Check(
+            "hostPython",
+            "fail",
+            f"Python {_fmt(version)} (`{binary}`) is below the effective floor "
+            f"{_fmt(floor)}, which comes from {floor_source}. The build does not "
+            f"fail here -- it fails later, inside Zephyr's own CMake configure, "
+            f"with an error that names Zephyr rather than your Python.",
+            f"Install Python {_fmt(floor)}+ and put it ahead of {_fmt(version)} on PATH, "
+            f"then re-run `tan bootstrap` so the workspace venv is built with it."
+            + (
+                # Named because it is THE case: the distro `python3` on 22.04 is
+                # 3.10, which clears the manifest floor and dies at Zephyr's
+                # configure -- the exact host this check exists for.
+                f" Ubuntu 22.04's distro `python3` is 3.10, so this needs a newer one: "
+                f"`sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt-get install -y "
+                f"python{_fmt(floor)} python{_fmt(floor)}-venv`."
+                if sys.platform.startswith("linux")
+                else ""
+            ),
+            # FROZEN (contract/issue-codes.json).
+            code="bootstrap.python-too-old",
+            scope="host",
+        )
+    return Check(
+        "hostPython",
+        "pass",
+        f"Python {_fmt(version)} (`{binary}`) meets the effective floor "
+        f"{_fmt(floor)} ({floor_source}).",
+        scope="host",
+    )
+
+
+def host_python_check(
+    found: tuple[str, tuple[int, int]] | None,
+    floor: tuple[int, int],
+    floor_source: str,
+    has_workspace_venv: bool,
+    candidates: list | None = None,
+) -> Check:
+    """`hostPython` as `python_check` judges it, downgraded to `warn` (same id,
+    no code) when it would pass but `tan build` would have no usable
+    interpreter: no workspace venv, and no PATH Python that is >= `floor` AND
+    imports `west` (tan-cli#1317, same resolver as the build)."""
+    check = python_check(found, floor, floor_source)
+    if check.status != "pass" or has_workspace_venv:
+        return check
+    if candidates is None:
+        candidates = probe_all_host_pythons()
+    candidates = list(candidates)
+    best = select_host_python(candidates, floor, need_west=True)
+    if best is not None and best.version >= floor and best.has_west:
+        return check
+    return Check(
+        "hostPython",
+        "warn",
+        f"{check.detail} But {describe_unsuitable(candidates, floor)}",
+        "Run `tan bootstrap` (or activate the Zephyr workspace venv).",
+        scope="host",
+    )
+
+
+def python_floor_skew_check(
+    manifest_floor: tuple[int, int],
+    effective_floor: tuple[int, int],
+    effective_source: str,
+    manifest_is_real: bool = True,
+) -> Check | None:
+    """`pythonFloor` -- the two declared floors disagree.
+
+    Reported rather than silently reconciled. A host that satisfies the higher
+    floor is fine TODAY, but the manifest is the number a customer will read and
+    trust, so while the skew stands the two sources disagree about which hosts
+    are supported. Saying which number came from which file is the whole value.
+
+    **Not fixed by raising the manifest (tan-cli#300).** That was tried and
+    reverted -- alp-sdk#1078: `crates/tan-core/src/build_readiness.rs:401`
+    pushes the Python check BEFORE any `os_set` branch ("EVERY backend's
+    build-plan emission runs `alp_project.py` ... not just Zephyr's"), so
+    raising the shared `pythonMinVersion` key would refuse a Yocto-only or
+    metadata-only project, on a host that builds it fine today, over a floor
+    that project never needs -- and the raised floor is unreachable via the
+    manifest's own remedy (`sudo apt-get install -y python3`) on the Ubuntu
+    22.04 hosts the docs recommend. The skew is real and known, and scoped to
+    Zephyr; the fix for a Zephyr build on a below-floor host is a newer
+    interpreter on THAT host (see `hostPython` above), not a manifest edit.
+
+    `manifest_is_real` is `False` when `manifest_floor` never actually came from
+    a read `metadata/bootstrap.json` -- no SDK resolved, or this SDK predates
+    the manifest -- and is instead tan's own `FALLBACK_PYTHON_FLOOR` standing
+    in. Callers pass `_load_manifest`'s own `ManifestLoad.is_real` verdict
+    straight through -- never re-derived from `ManifestLoad.source`'s prose, so
+    a future rewording of that message cannot silently flip which branch below
+    fires. Misreporting that number as "alp-sdk's metadata/bootstrap.json
+    declares" sends the customer to edit a file that was never consulted, so
+    the wording and the fix both change for this case.
+
+    `tan bootstrap` enforces the SAME effective floor this reports -- it calls
+    `zephyr_python_floor` below with the same argument (see
+    `tan.commands.bootstrap_cmd.resolve_python_floor`) and raises
+    `bootstrap.python-floor-skew` with the same two numbers. Before that, the
+    Rust oracle's POSIX branch enforced only the manifest's, which is how a
+    3.10 host passed both commands and then died inside Zephyr's CMake
+    configure.
+    """
+    if manifest_floor >= effective_floor:
+        return None
+    if manifest_is_real:
+        claim = f"alp-sdk's metadata/bootstrap.json declares pythonMinVersion {_fmt(manifest_floor)}"
+        fix = (
+            f"Known, Zephyr-scoped skew (alp-sdk#1078) -- raising "
+            f"`prerequisites.pythonMinVersion` to {_fmt(effective_floor)} was tried "
+            f"and reverted, because that key also gates Yocto-only and "
+            f"metadata-only projects, which do not need it. Building for Zephyr on "
+            f"a host below {_fmt(effective_floor)} needs a newer interpreter -- see "
+            f"the `hostPython` check above."
+        )
+    else:
+        claim = (
+            f"no alp-sdk metadata/bootstrap.json was read (no SDK checkout resolved, "
+            f"or this SDK predates it), so tan's own built-in floor {_fmt(manifest_floor)} "
+            f"is standing in"
+        )
+        fix = (
+            # `tan sdk switch` refuses in this build (tan-cli#305) -- point at
+            # the mechanism that actually resolves one instead.
+            f"Resolve an alp-sdk checkout: {NO_SDK_NEXT_STEPS}. That checkout's "
+            "own metadata/bootstrap.json pythonMinVersion is then read instead "
+            "of tan's built-in floor."
+        )
+    return Check(
+        "pythonFloor",
+        "warn",
+        f"{claim}, but the build's effective floor is "
+        f"{_fmt(effective_floor)} (from {effective_source}). Both `tan doctor` and "
+        f"`tan bootstrap` enforce the higher, effective floor, so a host this "
+        f"manifest would have accepted is refused up front rather than failing "
+        f"later at Zephyr's CMake configure.",
+        fix,
+        scope="project",
+    )
+
+
+def prerequisites_check(
+    checked: list[str],
+    missing: list[str],
+    install: dict[str, str],
+    source: str,
+    venv_refusal: PrereqFailure | None = None,
+    *,
+    available: Callable[[str], bool] | None = None,
+    provenance: dict[str, ArtifactProvenance] | None = None,
+) -> Check:
+    """`hostPrerequisites` -- the manifest's own tool list, on PATH, PLUS
+    (Linux only) whether the interpreter's `venv` module can actually create
+    a usable environment (tan-cli#294 finding 3, reintroducing tan-cli#161).
+
+    Mirrors `tan_core::bootstrap::doctor_prerequisite_check`, including that
+    the per-tool install commands come from the manifest rather than being
+    spelled here: they are per-platform facts alp-sdk owns.
+
+    `venv_refusal` is `posix_venv_unusable()` when `python3` is on PATH and
+    ran, but its `venv` module cannot create a usable environment because
+    `ensurepip` is missing -- the Debian/Ubuntu `python3-venv` package split.
+    Before this, `tan doctor` probed bare PATH presence and never
+    `ensurepip`, so it passed on a host that then died at `tan bootstrap`
+    time. `venv_refusal.missing` (`{tool: "python3-venv", command: ...}`)
+    folds into this check's own `missing`/`fix_missing` fields alongside any
+    tool-presence entries, so one `data.missingPrerequisites` list
+    (finding 4) carries both failure shapes -- never two.
+
+    `available` (tan-cli#760 + review #765) is the PATH-confirmation guard --
+    `install` here is RAW, exactly as the manifest declares it, and `install`
+    itself is used UNGUARDED to build `fix_missing`, the field `--fix`
+    (`doctor_cmd.run_fix`) actually consumes. `missing` -- `data.
+    missingPrerequisites`, the customer-facing field -- is the CONFIRMED
+    projection of the same entries: `available(binary)` decides whether a
+    command's own leading binary (`sudo` included) resolves on this host
+    before it is ever handed out as `command`, never `None`. `available=None`
+    (every direct caller before tan-cli#760, and every existing unit test of
+    this function) means `missing` and `fix_missing` are identical -- no
+    guard at all, matching this function's pre-#760 behaviour exactly.
+
+    `provenance` (tan-cli#1066) is the manifest's own `artifactProvenance`
+    table, `tool -> {tier, licence, sourceUrl, sizeBytes}`, joined onto each
+    entry by `tool` -- the identity the entry already carries. It reaches BOTH
+    `missing` and `fix_missing`, unlike `available` above: the two differ over
+    what tan may promise to RUN, and a licence is not a promise. `None` (every
+    caller before #1066, and the fallback manifest, which publishes no
+    provenance at all) reports the same `null`s a tool with no entry does --
+    `west`, `zephyrSdk`, `setools`, `jlink` and `python3-venv` have none in
+    alp-sdk v0.16.0, and that gap is alp-sdk#1574's, not tan's to fill in.
+
+    This split exists because `run_fix` has done its OWN on_path resolution
+    and reported `doctor.fix-installer-not-found` since tan-cli#360: handing
+    it the CONFIRMED (already-nulled) dict instead of the raw one would make
+    every unconfirmed installer a silent `--fix` no-op -- trading away the
+    #360 diagnostic for the #760 fix, on the exact hosts (a fresh Mac with no
+    Homebrew, a Windows image with no usable winget) #360 exists for
+    (tan-cli#760 review, MAJOR 1).
+    """
+    raw_entries = tuple(
+        MissingPrerequisite(
+            tool, install.get(tool), artifact_provenance.for_tool(provenance, tool)
+        )
+        for tool in missing
+    )
+    if venv_refusal is not None:
+        # `posix_venv_unusable()`'s own entry keeps its `UNKNOWN` provenance:
+        # `python3-venv` is a Debian PACKAGE name, not one of alp-sdk's
+        # `artifactProvenance` keys, so there is nothing to join and a
+        # near-miss join (`python3`'s row) would attribute one artefact's
+        # licence to another (tan-cli#1066).
+        raw_entries = raw_entries + venv_refusal.missing
+    fix_missing = reported_missing(raw_entries)
+
+    entries = raw_entries if available is None else confirm_missing(raw_entries, available)
+    missing_data = reported_missing(entries)
+    confirmed_commands = [m.command for m in entries if m.tool in missing and m.command]
+
+    if missing:
+        # tan-cli#760 review MINOR 4: `tan bootstrap`'s sibling refusal
+        # (`bootstrap.posix_refusal`/`_doctor_fix_hint`) already stops
+        # promising a remedy it cannot perform when NO missing tool has a
+        # confirmed command; this Check's own `fix` prose gets the same
+        # treatment, naming the tools rather than falling silent.
+        if confirmed_commands:
+            fix_text = (
+                "Install the missing prerequisites, then run `tan bootstrap`."
+                f"  {'; '.join(confirmed_commands)}"
+            )
+        elif available is not None:
+            fix_text = (
+                f"tan has no confirmed install command for this host: "
+                f"{', '.join(missing)}. Install them with your OS's package "
+                f"manager and put them on PATH, then run `tan bootstrap`."
+            )
+        else:
+            fix_text = "Install the missing prerequisites, then run `tan bootstrap`."
+        return Check(
+            "hostPrerequisites",
+            "fail",
+            f"missing from PATH: {', '.join(missing)} ({source}).",
+            fix_text,
+            # FROZEN (contract/issue-codes.json).
+            code="bootstrap.prerequisites-missing",
+            missing=missing_data,
+            fix_missing=fix_missing,
+            scope="host",
+        )
+    if venv_refusal is not None:
+        return Check(
+            "hostPrerequisites",
+            "fail",
+            f"{' '.join(venv_refusal.lines)} ({source}).",
+            "Install the missing prerequisites, then run `tan bootstrap`.",
+            code=f"bootstrap.{venv_refusal.code}",
+            missing=missing_data,
+            fix_missing=fix_missing,
+            scope="host",
+        )
+    return Check(
+        "hostPrerequisites", "pass", f"{', '.join(checked)} present ({source}).",
+        scope="host",
+    )
+
+
+def _posix_venv_capable(argv: list[str], executable: str | None = None) -> bool:
+    """Whether `argv`'s Python can create a USABLE virtual environment
+    (tan-cli#161). `python -m venv --help` cannot tell -- argparse answers
+    before `ensurepip` is ever touched -- so this probes the real
+    dependency: `import ensurepip`, which fails fast on the Debian/Ubuntu
+    split where `python3-venv` is a separate, unmet package.
+
+    Fails OPEN, not closed (tan-cli#294 review): `True` both when the probe
+    ran and exited 0, AND when it could not be launched at all (bogus argv,
+    spawn failure, signal death) -- mirrors `crate::util::
+    python_venv_capable`'s `.output().map(|out| out.status.success())
+    .unwrap_or(true)` verdict, not only its probed command; the real `python
+    -m venv` a moment later surfaces its own error if something is genuinely
+    wrong. Only a probe that actually RAN and exited non-zero refuses the
+    host.
+
+    NOT built on this file's own `probe()`: `probe()` collapses "ran and
+    exited non-zero" and "could not run at all" to the same `None`, and
+    those two outcomes need OPPOSITE verdicts here.
+
+    `executable` -- the PATH-RESOLVED interpreter path (tan-cli#797), e.g.
+    `_probe_host_python`'s own third return element. `argv` stays the bare
+    display spelling for the child's own `argv[0]`; only the OS-level lookup
+    is pinned, the same split every other resolved spawn in this module uses.
+    `None` is accepted (rather than required) so a caller that has not
+    resolved the interpreter still gets the pre-existing bare-spawn behaviour
+    -- there is no bare-git-style "refuse outright" case here, since `argv`
+    always comes from a candidate `_probe_host_python` already ran once.
+    """
+    try:
+        # Empty cwd: `-c` puts the cwd on sys.path (module-hijack, tan-cli#1317).
+        with tempfile.TemporaryDirectory(prefix="tan-probe-") as empty:
+            result = subprocess.run(
+                [*argv, "-c", "import ensurepip"],
+                cwd=empty,
+                executable=executable,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                stdin=subprocess.DEVNULL,
+                timeout=PROBE_TIMEOUT_S,
+                env=spawn_env(),
+                check=False,
+            )
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return True
+    return result.returncode == 0
+
+
+def west_check(
+    found: str | None,
+    version: tuple[int, int] | None,
+    floor: tuple[int, int] | None,
+    resolved: str | None = None,
+    resolved_ran: bool = True,
+) -> Check:
+    """`west` -- present on BARE PATH, or resolvable through the SAME
+    resolver `westResolved` uses (`tan.core.venv.west_program`).
+
+    **Now consults the resolver (tan-cli#299 second half).** This docstring
+    used to argue the opposite:
+
+        Does NOT assert that the venv resolved one: this check cannot see
+        what `westResolved` found... Name the authority instead of
+        predicting its answer.
+
+    That was deliberate at the time: `found` (bare PATH) was this check's
+    ONLY signal, so a hard `fail` here on the default post-bootstrap state --
+    `tan bootstrap` deliberately does NOT put `west` on PATH; its own
+    next-steps text tells the user to activate the venv afterwards -- was a
+    false, exit-4 refusal of a host that provably builds. Measured on the
+    published v0.5.0-rc2 binary: `tan build` produced real ELFs through the
+    resolved venv `west` while this check alone reported the host broken.
+    Downgrading that `fail` to `warn` (this file's other, earlier change on
+    this branch) fixed the exit code, but the warning still fires on every
+    correctly-bootstrapped host's very first `tan doctor` -- and a warning
+    that fires on every correct install trains users to ignore warnings,
+    which is the same defect as the false `fail`, one severity down
+    (hkngln, tan-cli#299).
+
+    So this now takes `resolved`: the SAME absolute venv path `westResolved`
+    already computed via `tan.core.venv.west_program` -- never a second,
+    independent probe of its own (`tool_in_venv` already confirmed that file
+    exists before `westResolved` ever saw it) -- and reports `pass`, naming
+    it, when bare PATH lacks `west` but the resolver found one. A bare-PATH
+    probe that cannot see the venv was never a second opinion; it was a
+    worse one. It now defers to the real one instead of contradicting it.
+
+    **Still never the FAIL owner.** When `resolved` is ALSO `None` -- west
+    absent from PATH and unresolvable anywhere -- this stays `warn`, not
+    `fail`. That severity belongs to `westResolved` alone (below), by
+    tan-cli#123's one-version-per-check contract applied to severity: making
+    both checks fatal on the same absent-everywhere fact is the two-owners
+    bug tan-cli#123 closed, and reintroducing it is exactly what let west
+    absent everywhere exit 0 the one time this branch made BOTH checks
+    non-fatal at once, before `west_resolved_check` was raised back to
+    `fail`. Keeping `west` a `warn` even in that state is what lets
+    `westResolved` be the sole, unambiguous reason `tan doctor` exits 4 on a
+    genuinely unbuildable host.
+
+    Only WARN on an old or unreadable version too -- west is forward-
+    compatible in practice and refusing a host on a version string we could
+    not parse is a worse failure than letting the real invocation report its
+    own.
+
+    **`resolved_ran` -- a resolved-but-unspawnable west is not a `pass`
+    (tan-cli#488 defect 3).** `resolved` only proves `westResolved` found a
+    file at that path; it says nothing about whether that file can actually
+    run. Before this parameter existed, `found is None and resolved is not
+    None` returned `pass` unconditionally -- including for a `west` whose
+    launcher survives a relocated workspace but whose interpreter does not,
+    the exact host `westResolved` (tan-cli#488 defect 1) now reports `fail`
+    for. That paired one check correctly failing an unbuildable host with its
+    sibling still calling it a `pass`, the headline "pass on an unrunnable
+    west" symptom surviving in this one branch. Defaults to `True` so every
+    existing 4-argument call site (this file's own unit tests, modelling the
+    ordinary "ran fine" case) keeps its prior meaning unchanged.
+    """
+    if found is None:
+        if resolved is not None and resolved_ran:
+            return Check(
+                "west",
+                "pass",
+                f"`west` is not on bare PATH, but resolves through the workspace "
+                f"venv: {resolved} -- the same binary `westResolved` above "
+                f"reports, and the one a real build actually spawns. This is the "
+                f"default state right after `tan bootstrap`, which deliberately "
+                f"does not put `west` on PATH; activating the venv (its "
+                f"`bin`/`Scripts` directory holds the `west` launcher) would "
+                f"additionally put it on bare PATH, for tools that spawn it "
+                f"directly rather than through tan.",
+                scope="host",
+            )
+        if resolved is not None:
+            return Check(
+                "west",
+                "warn",
+                f"`west` is not on bare PATH. It resolves to {resolved} through the "
+                f"workspace venv, but `westResolved` above found that binary could "
+                f"not be executed there -- no build slice can run it. `westResolved` "
+                f"is the check that owns this failure; see it for the remedy.",
+                "Run `tan bootstrap` to recreate the workspace venv.",
+                scope="host",
+            )
+        return Check(
+            "west",
+            "warn",
+            # Does NOT assert that the venv resolved one: `resolved` above
+            # already covers that case with a `pass`, so reaching here means
+            # it is genuinely `None` too -- PATH absence on its own, with
+            # nothing for the resolver to find either. Name the authority
+            # instead of predicting its answer.
+            "`west` is not on bare PATH. `westResolved` above is the check that "
+            "answers whether a build slice can run -- it reports the binary one "
+            "would actually execute. PATH absence on its own is the normal state "
+            "before the workspace venv is activated in this shell.",
+            "If `westResolved` above also could not resolve one, run `tan "
+            "bootstrap`; otherwise activate the workspace venv (its `bin`/`Scripts` "
+            "directory holds the `west` launcher) so tools invoked directly find it "
+            "too.",
+            scope="host",
+        )
+    if version is None:
+        return Check(
+            "west",
+            "warn",
+            f"`west` found at {found} but `west --version` produced nothing this "
+            f"command could parse.",
+            "Run `west --version` by hand; a west that cannot report its version "
+            "usually cannot run either.",
+            scope="host",
+        )
+    if floor is not None and version < floor:
+        return Check(
+            "west",
+            "warn",
+            f"west {_fmt(version)} ({found}) is older than the {_fmt(floor)} floor "
+            f"alp-sdk's metadata/bootstrap.json pins.",
+            "Upgrade inside the workspace venv: `pip install --upgrade west`.",
+            scope="host",
+        )
+    return Check("west", "pass", f"west {_fmt(version)} ({found}).", scope="host")
+
+
+def west_resolved_check(
+    found: str | None, version: tuple[int, int] | None, ran: bool = True
+) -> Check:
+    """`westResolved` -- is `west` resolved through the WORKSPACE VENV
+    (`tan.core.venv.west_program`), not bare PATH (tan-cli#123/#290)?
+
+    Distinct from `west` above, which probes `on_path("west")` ONLY: on a
+    host where the workspace venv holds `west` but PATH does not -- the
+    normal GUI-launched-editor state, `tan.core.venv`'s own module
+    docstring -- `west` reports failing while a real build succeeds through
+    the venv binary. `westResolved` verifies the SAME binary a build would
+    actually run, and `version` (when probed) MUST come from that identical
+    resolution -- never a second, bare-PATH re-probe. Mirrors
+    `tan_core::preflight::build_preflight_checks`'s `westResolved`
+    (`west_available`) check, unconditional in BOTH doctor modes exactly like
+    `sdk`/`workspace` beside it (`crates/tan-cli/src/commands/doctor.rs:1828`
+    asserts all three together in the plain fold).
+
+    **FAIL when west resolves nowhere.** This used to be a Warn, justified by
+    "`west` above already fails outright on a totally-absent west, so this is
+    the narrower, additive fact". tan-cli#299 removed that Fail -- correctly,
+    because bare PATH is the wrong question -- and thereby falsified the
+    premise this severity rested on. Measured on a real host with `west.exe`
+    renamed out of the venv and absent from PATH:
+
+        westResolved  warn   west not resolved through the workspace venv or PATH
+        west          warn   ... every build slice actually resolves it through the venv
+        12 passed, 4 warning(s), 0 failed.        EXIT=0
+
+    Exit 0 on a host where nothing can execute a single slice, and `west`'s
+    text asserting the venv resolves it while THIS check says it does not. A
+    false refusal was traded for a false pass, which is the worse of the two.
+
+    So the pair now splits cleanly: `west` answers "is it on bare PATH" and is
+    never fatal (an unactivated venv is the normal post-bootstrap state);
+    `westResolved` answers "can a build slice run at all" and is fatal when the
+    answer is no. Exactly one of them owns the exit code, which is tan-cli#123's
+    one-version-per-check contract applied to severity.
+
+    **`ran` -- spawn failure is ALSO fatal, not a `pass` (tan-cli#488 defect
+    1).** `found` only proves `tool_in_venv`'s `is_file()` check passed; it
+    says nothing about whether the file can actually be EXECUTED. Before
+    `ran` existed, this function took `version` alone and treated
+    `version is None` as `pass` unconditionally -- but `probe()` collapses
+    THREE outcomes into that same `None`: could not be spawned at all
+    (`OSError` -- a `west` launcher whose shebang names a now-absent
+    interpreter, e.g. a relocated/renamed workspace, or a deleted
+    `.venv/bin/python`), spawned and exited non-zero, and spawned, exited
+    zero, and printed something this file's regex could not parse. `pass` is
+    only right for the third. `ran` (from `probe_status`, passed by
+    `_collect`) is `True` for exactly that third case and `False` for the
+    first two, so a resolved-but-unrunnable `west` now reports the SAME
+    `fail` as a `west` that resolved nowhere at all -- both mean "no build
+    slice can be executed" and both send the customer to the same remedy,
+    `tan bootstrap`. Defaults to `True` so every existing 2-argument call
+    site (this file's own unit tests, modelling the ordinary "ran fine"
+    cases) keeps its prior meaning unchanged.
+    """
+    if found is None:
+        return Check(
+            "westResolved",
+            "fail",
+            "west resolved neither through the workspace venv nor PATH -- no build "
+            "slice can be executed. Run `tan bootstrap` to create the workspace venv.",
+            "tan bootstrap",
+            scope="project",
+        )
+    if not ran:
+        return Check(
+            "westResolved",
+            "fail",
+            f"west resolved to {found}, but it could not be executed there ("
+            f"`{found} --version` did not run to a successful exit) -- no build "
+            f"slice can be executed. A relocated/renamed workspace, or a "
+            f"workspace venv whose own Python was removed, both leave the `west` "
+            f"launcher file in place while breaking it. Run `tan bootstrap` to "
+            f"recreate the workspace venv.",
+            "tan bootstrap",
+            scope="project",
+        )
+    if version is None:
+        return Check("westResolved", "pass", f"west resolved: {found}.", scope="project")
+    return Check("westResolved", "pass", f"west {_fmt(version)} resolved: {found}.", scope="project")
+
+
+#: tan-cli#1520: the verified remedy for a missing Zephyr SDK toolchain.
+ZEPHYR_SDK_BOOTSTRAP_FIX = "tan bootstrap"
+
+
+def zephyr_sdk_install_command() -> str:
+    """The exact `west sdk install` invocation the `zephyrSdk` check's `fix`
+    names -- the ONE place it is assembled, mirroring
+    `tan_core::zephyr_sdk_install_command` verbatim. `tan bootstrap`'s own
+    "Next steps" text (`tan.core.bootstrap`) already promises "the `tan
+    doctor` above reports it, and names the exact install command"; this is
+    what makes that promise true rather than a second, independently-worded
+    copy able to drift from it.
+
+    tan-cli#1520: this is now the README's MANUAL command only. The
+    `zephyrSdk` check and `tan build`'s missing-SDK message deliberately
+    diverge from the Rust oracle and point at `tan bootstrap` instead, because
+    this command's setup.sh fetches the toolchain archive with no integrity
+    check, skipping the alp-sdk sha256 pin (#1501).
+    """
+    return f"west sdk install --version {ZEPHYR_SDK_INSTALL_VERSION} -t arm-zephyr-eabi"
+
+
+def zephyr_sdk_check(detected: bool, env_dir: str | None = None) -> Check:
+    """`zephyrSdk` -- is the Zephyr SDK cross toolchain (`arm-zephyr-eabi`)
+    actually installed on this host? Ports `tan_core::zephyr_sdk_toolchain_check`
+    / `append_zephyr_sdk_toolchain` (tan-cli#160), closing tan-cli#286: this
+    port had NO such check at all, so on a host with no Zephyr SDK `tan
+    doctor` reported "3 passed, 2 warning(s), 0 failed" and never used the
+    word "toolchain" -- the exact alp-sdk#855 fresh-host gap #160 closed in
+    the Rust oracle, reintroduced here.
+
+    UNCONDITIONAL -- called from `_collect` regardless of `--build`, a
+    `board.yaml`, or an SDK checkout resolving. This is a HOST fact (an env
+    var / a scanned install dir), and ADR 0021 Lane 1 P0a runs `tan doctor`
+    as the very first command a customer runs, before anything project-shaped
+    exists. A Yocto-only project still gets a real `fail` here -- that host
+    genuinely has no Zephyr SDK -- not a skip for lacking a Zephyr core.
+
+    `env_dir` is the raw `ZEPHYR_SDK_INSTALL_DIR` value (or `None`), carried
+    only to word the Fail detail correctly: "ZEPHYR_SDK_INSTALL_DIR unset" is
+    true only when the variable really is unset. It used to be hardcoded even
+    when the variable WAS set and simply named a directory with no working
+    toolchain in it -- the exact stale-var case `_zephyr_sdk_detected` guards
+    against -- so a customer who greps their own environment and finds it set
+    disbelieved a diagnostic that was actually correct.
+
+    Paired with `seven_zip_check` on Windows (`_collect`, gated `os.name ==
+    "nt"` and nothing else -- tan-cli#736 dropped the `!probe.zephyr_sdk` term
+    the Rust sibling had, since the host WITH an SDK and no 7-Zip is precisely
+    what the pairing is for; tan-cli#204 covers that check's SEVERITY, not its
+    gate): the `west sdk install` this Fail's fix names cannot complete on
+    native Windows without 7-Zip on PATH (`manual_install_windows` prose).
+    """
+    if detected:
+        return Check("zephyrSdk", "pass", "Zephyr SDK toolchain detected.", scope="host")
+    where = (
+        f"ZEPHYR_SDK_INSTALL_DIR=`{env_dir}` does not contain a working toolchain"
+        if env_dir
+        else "ZEPHYR_SDK_INSTALL_DIR unset"
+    )
+    # tan-cli#1520: the remedy is `tan bootstrap`, NOT the oracle's
+    # `west sdk install ... -t arm-zephyr-eabi` (deliberate divergence): that
+    # command's setup.sh downloads the toolchain archive with no integrity
+    # check, bypassing the alp-sdk sha256 pin that #1501 made the boundary.
+    # `tan bootstrap` verifies the archive and passes `--no-hosttools`, so the
+    # tan-cli#424 `file(1)` prerequisite note no longer applies to this fix.
+    return Check(
+        "zephyrSdk",
+        "fail",
+        f"Zephyr SDK toolchain not detected ({where}) -- run `{ZEPHYR_SDK_BOOTSTRAP_FIX}`.",
+        f"Install the Zephyr SDK toolchain (arm-zephyr-eabi, version "
+        f"{ZEPHYR_SDK_INSTALL_VERSION}) with `{ZEPHYR_SDK_BOOTSTRAP_FIX}`, which "
+        "verifies the downloaded archive against the alp-sdk pin; a hand-run "
+        "`west sdk install` does not.",
+        scope="host",
+    )
+
+
+def _toolchain_store_dir(
+    manifest: toolchain_provision.ToolchainManifest,
+) -> Path:
+    root = toolchain_provision.resolve_toolchain_root(
+        os.environ.get("ALP_TOOLCHAIN_ROOT"), str(_home_alp_dir())
+    )
+    return Path(root.path_str) / toolchain_provision.store_dir_name(manifest.version)
+
+
+def _toolchain_root_adopted() -> bool:
+    """`$ALP_TOOLCHAIN_ROOT` is set: tan did not necessarily create that root
+    and `tan bootstrap` never deletes or repairs an unverified store
+    directory in it (tan-cli#1498)."""
+    return toolchain_provision.resolve_toolchain_root(
+        os.environ.get("ALP_TOOLCHAIN_ROOT"), str(_home_alp_dir())
+    ).adopted
+
+
+def _adopted_store_remedy(store_dir: Path) -> str:
+    return (
+        f"ALP_TOOLCHAIN_ROOT is an adopted root, so `tan bootstrap` will not repair "
+        f"it -- remove {store_dir} yourself (or unset ALP_TOOLCHAIN_ROOT), then run "
+        f"`tan bootstrap`."
+    )
+
+
+def _host_toolchain_matching_pin(
+    manifest: toolchain_provision.ToolchainManifest,
+) -> Path | None:
+    """The already-installed host toolchain root (`_zephyr_sdk_detected_root`
+    -- `ZEPHYR_SDK_INSTALL_DIR` or a scanned `zephyr-sdk*` directory, same
+    precedence `zephyrSdk` above trusts) IF its own `sdk_version` file names
+    the exact version `manifest` pins; else `None`.
+
+    `SDK_VERSION_FILE_RELPATH` is `west sdk install`'s own top-level marker
+    (`toolchain_provision`'s own docstring: measured against a real extracted
+    1.0.1 tree, exact byte content `"1.0.1\\n"`) -- read back and STRING-
+    compared, matching `toolchain_phase`'s own post-install verification, so
+    this reuses the identical trust boundary rather than a fresh directory-
+    name guess. A missing or unreadable `sdk_version` -- an unusual layout
+    `_zephyr_sdk_root_valid` still validated on compiler-binary presence
+    alone -- is honestly "does not match", not a guessed pass.
+
+    **Never returns an entry inside tan's OWN ADR 0021 store for THIS pin
+    (`_toolchain_store_dir(manifest)`) -- this adoption path is for a
+    toolchain tan did NOT install (tan-cli#990's `~/zephyr-sdk-1.0.1` case),
+    where a version-string match is the only signal available. Since
+    tan-cli#1186 widened `_zephyr_sdk_scan_roots` to also cover that store
+    (for `zephyrSdk`'s sake), `_zephyr_sdk_detected_root` can now return an
+    entry living INSIDE it too -- and that entry is already governed by the
+    stricter, digest-precise `stamp_matches_pin` check `toolchain_check` runs
+    first. A store directory can carry a real compiler and a `sdk_version`
+    matching the pin's nominal version while its stamp names a DIFFERENT
+    digest (the pin moved without the version string changing, ADR 0021's
+    own "stamped 1.0.1 against a moved pin" case) -- measured: without this
+    guard that combination made this function return the store entry as a
+    version-string match, turning the correct stamp-based `fail` a few lines
+    below in `toolchain_check` into a `pass` it never reaches. Trusting the
+    stamp alone for anything inside tan's own store, and never re-deriving a
+    looser verdict for it here, keeps the two checks from disagreeing on the
+    same directory.
+
+    Deliberately keyed on `_toolchain_store_dir(manifest)` -- the one
+    per-version LEAF tan's own installs use -- rather than the broader
+    `_toolchain_store_scan_root()` (the whole configured root, `~/.alp/
+    toolchains` or `$ALP_TOOLCHAIN_ROOT` verbatim). `resolve_toolchain_root`
+    takes an env override VERBATIM as the root, with no `/toolchains`
+    suffix (`toolchain_provision.resolve_toolchain_root`), so ADR 0021's own
+    documented bench/CI escape hatch -- `$ALP_TOOLCHAIN_ROOT` pointed at an
+    ancestor like `$HOME` or `/opt` -- makes the store root coincide with a
+    directory a hand-installed host toolchain also legitimately lives under.
+    Excluding the whole root there would misread that adopted toolchain as
+    "inside tan's own store" and refuse to adopt it, turning a
+    previously-passing configuration into a `toolchain` FAIL; excluding only
+    the specific `<root>/<store leaf for this manifest version>` directory
+    keeps the guard narrow enough to still hold under that escape hatch.
+    """
+    try:
+        store = _toolchain_store_dir(manifest).resolve()
+    except OSError:
+        store = None
+    for root in _zephyr_sdk_detected_roots():
+        try:
+            if store is not None and root.resolve().is_relative_to(store):
+                continue
+        except OSError:
+            pass
+        version_text = _read_text(root / toolchain_provision.SDK_VERSION_FILE_RELPATH)
+        if version_text is not None and version_text.strip() == manifest.version:
+            return root
+    return None
+
+
+def toolchain_check(sdk_root: str | None) -> Check:
+    """`toolchain` -- STAMP-vs-PIN, never directory-exists (issue #474, ADR
+    0021 Lane 1 P1's own words: "a stamped 1.0.1 store against a moved pin is
+    a Fail with a fix, not 'a toolchain exists'"). Calls
+    `toolchain_provision.stamp_matches_pin` -- the SAME function `tan
+    bootstrap`'s own skip-if-already-installed step calls -- so this check
+    and `bootstrap` cannot independently drift on what "still valid" means,
+    the same `zephyr_python_floor`-is-imported-not-re-derived pattern this
+    file already applies one layer up.
+
+    Distinct from `zephyrSdk` above, which answers "does ANY working
+    toolchain exist on this host" unconditionally, with no SDK checkout
+    needed (an env var or a scanned install dir). This one answers a
+    narrower, PIN-specific question -- "does THIS checkout's pinned
+    cross-toolchain version exist here, verified" -- so it needs `sdk_root`
+    and reports `unknown` without one: there is no pin to check against.
+
+    `scope="project"` on every arm (never `"host"`, unlike `zephyrSdk`): a
+    single check NAME may not carry two scopes (`tests/gates/
+    test_doctor_check_scope.py`), and this one is inherently
+    project-scoped -- it cannot answer at all without a resolved
+    `sdk_root` to read `metadata/toolchains.json`'s PIN from.
+
+    **Has an adoption path (tan-cli#990 review, the tan-cli#299
+    false-refusal class): an unstamped store is not the only way to satisfy
+    this check.** Before either `fail` branch, `_host_toolchain_matches_pin`
+    asks whether a toolchain THIS HOST ALREADY HAS -- found by the SAME
+    `ZEPHYR_SDK_INSTALL_DIR`/scan `zephyrSdk` above already trusts -- reports
+    the pinned version in ITS OWN `sdk_version` file. If so this is a `pass`,
+    never a `fail`: a stamp is tan's own bookkeeping for what IT installed,
+    not the only proof a working, correctly-versioned toolchain exists. Before
+    this, a host with a hand-installed or pre-existing SDK at the exact pinned
+    version -- `zephyrSdk` passing right above it -- got a `toolchain` FAIL
+    whose only prescribed fix, `tan bootstrap`, downloads a SECOND ~1.9 GiB
+    copy of a toolchain already on disk, and cannot even do that on an
+    offline host or the README's own hand-`west sdk install` path (this
+    check's one stamp-writing producer is `tan bootstrap` alone).
+    """
+    if sdk_root is None:
+        return Check(
+            "toolchain",
+            "unknown",
+            "no alp-sdk checkout resolved -- cannot read metadata/toolchains.json to "
+            "know which cross-toolchain version is pinned.",
+            scope="project",
+        )
+    manifest_path = Path(sdk_root) / "metadata" / "toolchains.json"
+    text = _read_text(manifest_path)
+    if text is None:
+        return Check(
+            "toolchain",
+            "unknown",
+            f"{manifest_path} is missing or unreadable -- cannot determine the "
+            f"pinned cross-toolchain version.",
+            scope="project",
+        )
+    try:
+        manifest = toolchain_provision.parse_toolchain_manifest(text)
+    except toolchain_provision.ToolchainManifestError as err:
+        return Check(
+            "toolchain", "unknown", f"{manifest_path} is malformed: {err}", scope="project",
+        )
+    store_dir = _toolchain_store_dir(manifest)
+    stamp_text = _read_text(store_dir / toolchain_provision.STAMP_FILENAME)
+    stamp = toolchain_provision.parse_stamp(stamp_text) if stamp_text is not None else None
+    adopted = _toolchain_root_adopted()
+    if toolchain_provision.stamp_matches_pin(stamp, manifest):
+        if not toolchain_provision.store_compiler_present(store_dir, is_windows=os.name == "nt"):
+            if adopted:
+                return Check(
+                    "toolchain",
+                    "fail",
+                    f"{store_dir} carries a verification stamp for {manifest.version} "
+                    f"but its arm-zephyr-eabi-gcc is gone -- "
+                    f"{_adopted_store_remedy(store_dir)}",
+                    scope="project",
+                )
+            return Check(
+                "toolchain",
+                "fail",
+                f"{store_dir} carries a verification stamp for {manifest.version} but "
+                f"its arm-zephyr-eabi-gcc is gone -- run `tan bootstrap` to repair it.",
+                "tan bootstrap",
+                scope="project",
+            )
+        return Check(
+            "toolchain", "pass",
+            f"arm-zephyr-eabi {manifest.version} installed at {store_dir}; version and "
+            f"compiler were checked at install, but "
+            f"{toolchain_provision.ARCHIVE_SHA256_NOTE}"
+            + ("." if stamp is not None and stamp.pin_checked else " (this install predates the check)."),
+            scope="project",
+        )
+    host_root = _host_toolchain_matching_pin(manifest)
+    if host_root is not None:
+        return Check(
+            "toolchain",
+            "pass",
+            f"arm-zephyr-eabi {manifest.version} detected at {host_root} -- not tan's "
+            f"own store, but its `sdk_version` matches this checkout's pin, so this "
+            f"host already has what `tan bootstrap` would otherwise download again. "
+            f"That match is the `sdk_version` text file only: this install was never "
+            f"compared with the pin (its archive may have been fetched unchecked); "
+            f"{toolchain_provision.ARCHIVE_SHA256_NOTE}.",
+            scope="project",
+        )
+    if stamp is not None:
+        if adopted:
+            return Check(
+                "toolchain",
+                "fail",
+                f"{store_dir} carries a verification stamp for a different pin (this "
+                f"checkout now pins {manifest.version}) -- "
+                f"{_adopted_store_remedy(store_dir)}",
+                scope="project",
+            )
+        return Check(
+            "toolchain",
+            "fail",
+            f"{store_dir} carries a verification stamp for a different pin (this "
+            f"checkout now pins {manifest.version}) -- run `tan bootstrap` to "
+            f"acquire the current pin.",
+            "tan bootstrap",
+            scope="project",
+        )
+    if adopted and store_dir.is_dir():
+        return Check(
+            "toolchain",
+            "fail",
+            f"no verified arm-zephyr-eabi {manifest.version} toolchain at {store_dir} "
+            f"-- {_adopted_store_remedy(store_dir)}",
+            scope="project",
+        )
+    return Check(
+        "toolchain",
+        "fail",
+        f"no verified arm-zephyr-eabi {manifest.version} toolchain at {store_dir} -- "
+        f"run `tan bootstrap` to acquire it (ADR 0021 Lane 1 P1).",
+        "tan bootstrap",
+        scope="project",
+    )
+
+
+def devicetree_lint_check(resolution: devicetree_lint.DtcResolution) -> Check:
+    """`devicetreeLint` -- will Zephyr's diagnostics-only `dtc` pass actually
+    run for a build on this host (tan-cli#1192)?
+
+    See `tan.core.devicetree_lint` for the two CMake mechanisms this mirrors
+    (`find_program(DTC dtc)` over the SDK's `hosttools` prefix then `PATH`,
+    then `find_package(Dtc 1.4.6)`'s silent `DTC-NOTFOUND` reset) and for the
+    tan-cli#1176/#1178 premise change that made the question worth asking.
+
+    **This partially reverses this module's own recorded decision that
+    `dtc`/`gperf` were deliberately NOT ported from the frozen Rust oracle's
+    `--build` vocabulary** (see the module docstring). That decision was right
+    when it was made and its premise is gone: `dtc` used to arrive with the
+    Zephyr SDK on every install, so a `dtc` probe could only restate what
+    `zephyrSdk` already reported. Since tan-cli#1178 `tan bootstrap` passes
+    `--no-hosttools`, the SDK ships no `dtc`, and the lint pass stopped
+    running with nothing anywhere saying so. `gperf` stays unported; only
+    `dtc` is reopened, and only as this question.
+
+    **The severity, which is the whole difficulty.** A naive "is `dtc` on
+    PATH" `warn` would fire on EVERY correctly-bootstrapped host, which is the
+    anti-pattern `west_check`'s own docstring records ("a warning that fires
+    on every correct install trains users to ignore warnings", tan-cli#299).
+    So the no-`dtc` arm is a `pass`: it is the ordinary, supported, documented
+    state, the build genuinely succeeds, and `tan bootstrap` is not a remedy
+    for it -- bootstrap is what caused it, on purpose. The row still SAYS the
+    lint is not running, which is the visibility tan-cli#1192 asks for, but it
+    raises no `issues[]` entry, contributes no `nextSteps` line, lands in
+    `summary.pass`, and cannot move the exit code.
+
+    The one `warn` arm is the host where somebody INSTALLED a `dtc` and does
+    not get the lint anyway, because `FindDtc.cmake` judged it unusable and
+    reset it to `DTC-NOTFOUND` without printing anything. That is a real,
+    actionable divergence between what an operator did and what they got, it
+    is unreachable on a host provisioned per this repo's own onramp, and its
+    fix is concrete. `warn`, never `fail`: `exit_code_for` reserves exit 4 for
+    a host that cannot build, and this one builds fine -- it just builds
+    without a class of diagnostics.
+
+    NOT harvested by `tan support-bundle`: that command reports only the five
+    HOST checks `support_bundle_cmd._HOST_CHECK_ORDER` names, built by
+    `host_environment_checks` (which this is deliberately not added to), so
+    this check reaches neither that command's report nor its verdict. That is
+    the right call for the same reason `_demote_long_paths_fail` exists --
+    support-bundle's acceptance bar is matching the frozen oracle's axes, and
+    the oracle has no devicetree-lint axis at all.
+
+    `scope="host"` on every arm: the subject is this machine's tooling (an SDK
+    install and `PATH`), identical for every project built on it, which is
+    `tan.core.doctor_scope`'s own test.
+    """
+    floor = devicetree_lint.format_version(devicetree_lint.DTC_MIN_VERSION)
+    lint_flags = "`-E unit_address_vs_reg` / `-Wunique_unit_address_if_enabled`"
+    if devicetree_lint.lint_will_run(resolution) and resolution.version is not None:
+        where = (
+            "the Zephyr SDK's own hosttools bundle, which `host-tools.cmake` puts on "
+            "`CMAKE_PREFIX_PATH`"
+            if resolution.origin == devicetree_lint.ORIGIN_HOSTTOOLS
+            else "this host's PATH"
+        )
+        return Check(
+            "devicetreeLint",
+            "pass",
+            f"dtc {devicetree_lint.format_version(resolution.version)} at "
+            f"{resolution.path} ({where}) -- Zephyr's devicetree lint pass "
+            f"({lint_flags}, `dts.cmake`'s `if(DTC)` block) runs for builds here.",
+            scope="host",
+        )
+    if resolution.path is not None:
+        answered = (
+            f"reports {devicetree_lint.format_version(resolution.version)}, below the "
+            f"{floor} floor"
+            if resolution.version is not None
+            else "did not answer `dtc --version` in a form `FindDtc.cmake` can parse"
+        )
+        return Check(
+            "devicetreeLint",
+            "warn",
+            f"`dtc` is installed at {resolution.path} but {answered}, so Zephyr's "
+            f"`find_package(Dtc {floor})` rejects it and `FindDtc.cmake` resets DTC to "
+            f"`DTC-NOTFOUND` -- silently. The devicetree lint pass ({lint_flags}) does "
+            f"not run, exactly as if no dtc were installed, and nothing in the build "
+            f"output says so.",
+            f"Install dtc {floor} or newer (Debian/Ubuntu `device-tree-compiler`, "
+            f"Homebrew `dtc`) ahead of {resolution.path} on PATH, or drop this one so "
+            f"the report stops claiming a lint that is not happening.",
+            scope="host",
+        )
+    return Check(
+        "devicetreeLint",
+        "pass",
+        f"no `dtc` in CMake's reach (neither a Zephyr SDK `hosttools/` copy nor one on "
+        f"PATH), so Zephyr's devicetree lint pass ({lint_flags}) is SKIPPED -- "
+        f"`dts.cmake` guards it with `if(DTC)` and treats dtc as optional. Builds "
+        f"succeed and produce a real `zephyr.elf`; only those diagnostics are absent. "
+        f"This is the expected state after `tan bootstrap`, which acquires the Zephyr "
+        f"SDK with `--no-hosttools` (tan-cli#1178) and so installs no dtc. Install a "
+        f"system dtc {floor} or newer if you want the lint back.",
+        scope="host",
+    )
+
+
+def seven_zip_check(found: bool) -> Check:
+    """`sevenZip` -- Windows-only, unconditionally (tan-cli#736 dropped the
+    `zephyrSdk`-is-failing half). Ports the Rust oracle's sibling (`crate::
+    build_readiness`, tan-cli#204): `west sdk install`, the remedy
+    `zephyr_sdk_check` names, extracts the `.7z` toolchain archive by
+    delegating to `patoolib`, which shells out to one of `SEVEN_ZIP_PROGRAMS`
+    and has no pure-Python fallback -- documented in this repo's own
+    `tan.core.bootstrap` (`manual_install_windows` prose) but, until this
+    check, reaching no JSON consumer, so `alp-sdk-vscode` had no way to
+    surface it and a customer who followed the `zephyrSdk` fix hint alone hit
+    a patoolib error naming no Alp surface and no mention of 7-Zip.
+
+    `Warn`, not `Fail`, mirroring the oracle: missing 7-Zip blocks the
+    REMEDY, not the build itself -- `zephyrSdk` is the `Fail` that stops
+    things. That reasoning is unchanged.
+
+    What DID change (tan-cli#736) is the gate this check used to ride: it
+    ran only alongside a FAILING `zephyrSdk`, on the premise that "a host
+    that already has the SDK never reaches this". That premise does not
+    hold -- "already has the SDK" is not "will never run `west sdk
+    install` again". Adding a second architecture's toolchain, or moving to
+    a newer SDK, is an ordinary operation; `zephyrSdk` passes throughout,
+    and the check never fired. Measured on Windows with `7z` stripped from
+    PATH and the SDK present: `overall ok: True`, and
+    `any check mentioning 7z: []` -- a green verdict on a host that cannot
+    complete `west sdk install`. It now runs unconditionally on Windows.
+    """
+    if found:
+        return Check(
+            "sevenZip",
+            "pass",
+            "7-Zip is available -- `west sdk install` can extract the toolchain.",
+            scope="host",
+        )
+    programs = ", ".join(SEVEN_ZIP_PROGRAMS)
+    return Check(
+        "sevenZip",
+        "warn",
+        f"No 7-Zip on PATH (looked for {programs}) -- `west sdk install` extracts "
+        "the toolchain with patoolib, which shells out to one of these and has no "
+        "pure-Python fallback, so it will fail on native Windows. Install it with "
+        f"`{SEVEN_ZIP_INSTALL_COMMAND}`.",
+        f"Install 7-Zip before running `west sdk install`: `{SEVEN_ZIP_INSTALL_COMMAND}`.",
+        scope="host",
+    )
+
+
+def zephyr_workspace_check(workspace_dir: str, version_text: str | None) -> Check:
+    """`zephyrWorkspace` -- unconditional now, not `--build`-only
+    (tan-cli#290): does the RESOLVED workspace's `zephyr/` subtree actually
+    look like a Zephyr checkout at all?
+
+    `workspace_dir`/`version_text` are the SAME
+    `tan.core.venv.west_workspace_dir`-resolved facts `workspace`/
+    `zephyrVersion` above already compute -- not a second, independent
+    `$ZEPHYR_BASE` env-var read, which was tan-cli#294's own complaint about
+    this check ("probes an env var, not the resolved topdir"). Callers only
+    reach this once a workspace has actually resolved: `workspace` above
+    already fails outright on a totally-absent one, and re-warning that same
+    absence here under a second name would be exactly the one-fact-twice
+    duplication this file's `boardYaml` handling (mirroring the Rust oracle)
+    already refuses to do -- so there is no "unresolved" branch here at all.
+
+    **No Fail branch (tan-cli#295 review, reversing tan-cli#290's own
+    addition of one).** A version-mismatch Fail was added to mirror Rust's
+    `crates/tan-core/src/preflight.rs:118-145` (tan-cli#98/#159, the
+    alp-sdk#855 v4.4.0->v4.4.1 incident, where a drifted checkout reported
+    `11 passed, 6 warnings, 0 failed` and the very next build broke) -- but
+    `zephyr_version_preflight_check` above already reports that identical
+    fact, from these identical two inputs (`workspace_version`/`sdk_pin`), at
+    Fail severity. This check's would-be Fail condition was a strict SUBSET
+    of that one, so it could never fire without `zephyrVersion` having
+    already reported it under a different code: measured on a drifted host,
+    `summary.fail` came out 5 instead of 4, both `doctor.zephyrVersion` and
+    `doctor.zephyrWorkspace` present, and two `nextSteps` strings for the one
+    `tan bootstrap` remedy. Removed rather than kept "in step" with it --
+    Rust's own `crates/tan-cli/src/commands/doctor.rs` drops its comparable
+    `boardYaml` duplicate for the identical reason ("emitting both would
+    report one fact twice"), and `grep -rn "zephyrWorkspace" crates/` is
+    empty: there is no Rust oracle row here for a version-mismatch Fail to
+    stay parallel with.
+
+    An unreadable `zephyr/VERSION` stays `Warn`: neither the Rust oracle nor
+    `zephyr_version_preflight_check` above (which silently SKIPS rather than
+    fails when the version is unknown -- "don't nag when this cannot
+    actually be verified") treats this as more than that, and a resolved
+    `.west` workspace mid-`west update` -- `zephyr/` not yet cloned -- is a
+    legitimate, working-in-progress host state, not a proven blocker. This is
+    the one fact `zephyrVersion` cannot see at all (it skips outright), so it
+    is this check's whole remaining reason to exist.
+    """
+    if version_text is None:
+        return Check(
+            "zephyrWorkspace",
+            "warn",
+            f"workspace at `{workspace_dir}` does not look like a Zephyr checkout "
+            f"(no readable zephyr/VERSION file).",
+            "Run `tan bootstrap`, or point the workspace at a real Zephyr checkout.",
+            scope="project",
+        )
+    return Check(
+        "zephyrWorkspace", "pass", f"Zephyr {version_text} at `{workspace_dir}`.",
+        scope="project",
+    )
+
+
+def jlink_available(app_dir: str, sdk_root: str | None) -> bool:
+    """Whether `tan flash` would find a J-Link tool: the SAME test it applies
+    (`flash_cmd._tool_available` -- PATH or the workspace venv)."""
+    try:
+        venv_bin = venv_bin_dir(app_dir, sdk_root)
+        return any(_tool_available(n, venv_bin) for n in ("JLinkExe", "JLink"))
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def setools_check(
+    setools_dir: str | None,
+    se_uart: str | None,
+    is_linux: bool,
+    flash_methods: frozenset[str] | None = None,
+    jlink_found: bool | None = None,
+    setools_source: str = "$SETOOLS_DIR",
+) -> Check:
+    """`setools` -- can this host flash an Alif AEN part's MRAM at all?
+
+    Nothing else in either doctor asks. `scripts/west_commands/runners/
+    alif_flash.py` raises a bare `RuntimeError` for each of these the moment a
+    customer runs `west flash`, so the first time they learn is at the bench.
+
+    WARN, not FAIL: this is one flow, on one SoM family. A customer building for
+    a V2N or native_sim never touches it, and a `fail` here would exit 4 on a
+    perfectly healthy host. `unknown` off Linux -- `alif_flash.py` hard-codes
+    `app-release-exec-linux`, so there is no verdict to give a native
+    Windows/macOS host, and `unknown` is counted in no summary bucket.
+
+    **No longer probes any interpreter for `fdt` (tan-cli#641).** It used to,
+    most recently against the workspace venv's own Python (tan-cli#488 defect
+    6). Measured on real AEN silicon: `fdt` was genuinely unimportable in the
+    workspace venv while `app-gen-toc` -- which `tan.core.setools.sign_slot0`
+    spawns as its own subprocess, never as a Python import under any
+    interpreter this command could probe, and which SETOOLS ships its own
+    dependencies for regardless -- signed successfully, and the resulting MRAM
+    write persisted a cold power cycle. Probing one interpreter's `sys.path`
+    was never going to answer whether a flash that spawns a separate,
+    license-gated binary will succeed, and the false alarm it produced here
+    trains an operator to stop trusting doctor on the one question they ask it
+    before a write.
+
+    **Method-aware (tan-cli#1323).** `$SE_UART` belongs to Flow A
+    (`zephyr_west_flash` -> the `alif_flash` runner) ONLY. A planner-emitted
+    AEN manifest dispatches Flow D (`alif_mram_jlink`): SETOOLS signs the ATOC
+    (`app-gen-toc`) and J-Link writes it over SWD, no SE-UART. `flash_methods`
+    is the set `tan flash` would dispatch for the project's built manifest
+    (`tan.core.doctor_setools.project_flash_methods`, which calls
+    `select_flash_method` itself); `None` means no project/manifest is in
+    scope, and the verdict is then phrased per method rather than asserting
+    one. `jlink_found` is whether a J-Link tool is on PATH (Flow D only).
+    """
+    flow_d = flash_methods is not None and FLOW_D_METHOD in flash_methods
+    flow_a = flash_methods is not None and FLOW_A_METHOD in flash_methods
+    if flash_methods is not None and not (flow_a or flow_d):
+        return Check(
+            "setools",
+            "unknown",
+            "this project's slices flash via "
+            f"{', '.join(f'`{m}`' for m in sorted(flash_methods)) or 'no method'}, "
+            "which does not use SETOOLS -- nothing to check here.",
+            scope="host",
+        )
+    if flow_a and not flow_d and not is_linux and not setools_dir and not se_uart:
+        return Check(
+            "setools",
+            "unknown",
+            "AEN MRAM flashing over the SE-UART is Linux-only in this tree: "
+            "scripts/west_commands/runners/alif_flash.py hard-codes "
+            f"`app-release-exec-linux`, so its bundle is `{SETOOLS_BUNDLE}`. "
+            "Nothing to check on this host for THAT path -- run it from "
+            "WSL2/Linux (Windows hosts pass the SE-UART through with usbipd). "
+            "Flow D below is a different matter: it signs on Windows with the "
+            "WINDOWS SETOOLS build, which is a different bundle from the "
+            "`-linux` one named above -- point `--setools-dir` at it (measured: "
+            "`app-gen-toc.exe` under a Windows `app-release-exec`, "
+            "SETOOLS_version_SE_FW_1.110.00_DEV, signed an ATOC the part "
+            "booted from).",
+            scope="host",
+        )
+
+    status, detail, fix = setools_verdict(
+        setools_dir,
+        setools_source,
+        se_uart,
+        flash_methods,
+        jlink_found,
+        SETOOLS_BUNDLE,
+        SETOOLS_EXECUTABLES,
+        is_linux,
+    )
+    return Check("setools", status, detail, fix, scope="host")
+
+
+def jlink_banner(jlink_exe: str, timeout: int = PROBE_TIMEOUT_S) -> str | None:
+    """The version banner JLinkExe prints, unprompted, at the top of EVERY
+    invocation -- `SEGGER J-Link Commander V9.50 (Compiled ...)` / `DLL
+    version V9.50` -- before it ever tries to reach a probe or a target.
+
+    **Not `[jlink_exe, "-?"]` (tan-cli#641).** JLinkExe has no such flag:
+    `JLinkExe -?` answers `Unknown command line option -?.` and exits
+    non-zero, so the old probe never once reached the banner it was trying to
+    read -- measured on real AEN silicon, this was the whole reason a J-Link
+    tool that answers `V9.50` unprompted on every run still reported "version
+    could not be read".
+
+    Feeds `exit\\n` on stdin so Commander quits at its own interactive prompt
+    rather than sitting there waiting for input or a probe that may not be
+    plugged in; `timeout` still bounds it regardless. Unlike `probe()`, this
+    reads stdout REGARDLESS of the exit code -- the banner is already printed
+    by the time Commander decides how it exits (e.g. because no emulator is
+    attached), and that text must not be discarded along with a non-zero
+    status that says nothing about whether the banner itself was readable.
+
+    Commander-only contract: this assumes `jlink_exe` is `JLinkExe`/`JLink`,
+    which quit on the `exit\\n` fed to them. `JLinkGDBServerCL` does not read
+    stdin at all -- it waits for a GDB connection and holds its port for the
+    full `timeout` regardless of what is piped in. The caller (`_collect`)
+    must not spawn this against that binary; see its comment there.
+
+    `-NoGui 1` matches every other J-Link spawn in this repo
+    (`flash_plan.py`, `flash_cmd.py`) -- without it a GUI-capable install can
+    raise a modal dialog (firmware-update / device-select) that `exit\\n` on
+    stdin does not dismiss, blocking for the full `timeout` regardless.
+    """
+    try:
+        completed = subprocess.run(
+            [jlink_exe, "-NoGui", "1"],
+            input="exit\n",
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+            env=spawn_env(),
+            check=False,
+        )
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return None
+    return completed.stdout or None
+
+
+def jlink_check(
+    found: str | None,
+    version: tuple[int, int] | None,
+    device: str = JLINK_AEN_DEVICE,
+    device_source: str | None = None,
+) -> Check:
+    """`jlink` -- Flow D, the day-to-day burn path (J-Link direct MRAM flash over
+    SWD, ~0.16 s, no SE-UART).
+
+    Three facts a presence check alone would hide, so all three travel in the
+    message even when the binary is there: the loader is built into the J-Link
+    DLL from V9.46 (nothing separate to install, and nothing at all below it),
+    it is unlocked ONLY by the part-number device profile -- the generic
+    `Cortex-M55` connects fine and has no MRAM loader, so a burn against it
+    silently is not one. Both are unprobeable from the host, which is exactly
+    why they must be said.
+
+    tan-cli#739: a third "fact" used to travel with them -- that the probe
+    needs matched J-Link V13 firmware or the part-number device will not
+    connect. Measured on the AEN EVK, that is false. A probe reporting
+    `Firmware: J-Link V11 compiled Apr  1 2025 10:02:30` / `Hardware version:
+    V11.00` connected WITH the part-number profile and programmed MRAM
+    repeatedly, including a 96 KiB loadbin + verifybin at 0x80560000 that
+    byte-verified (alp-sdk#1380 SS1). The claim sent customers with a working
+    probe to a firmware update they did not need, and read as "your setup is
+    unsupported" on a setup that demonstrably works.
+
+    It is NOT restated as "V11+". Where the real floor sits is unknown -- no
+    probe old enough to fail has been tested -- and swapping one unmeasured
+    minimum for another is the same defect wearing a different number. The
+    firmware clause is dropped entirely; the DLL floor and the device profile
+    are the two requirements that are actually established.
+
+    `device` defaults to `JLINK_AEN_DEVICE` so every existing call site keeps
+    working; `_collect` passes the metadata-resolved value from
+    `jlink_flash_device` instead, when an SDK checkout resolved one.
+
+    `device_source` (also from `jlink_flash_device`) is surfaced into the
+    detail text when given, so the same `device` string is not byte-identical
+    whether it came from a resolved SDK checkout or tan's built-in fallback --
+    otherwise a user on a host where the SDK did not resolve has no way to
+    tell which one they are looking at.
+    """
+    requirements = (
+        f"Flow D needs the `{device}` part-number device profile (NOT the "
+        f"generic `Cortex-M55`, which has no MRAM loader) and a J-Link DLL "
+        f"V{_fmt(JLINK_MIN_DLL)}+."
+    )
+    if device_source is not None:
+        requirements += f" Device profile resolved from: {device_source}."
+    if found is None:
+        return Check(
+            "jlink",
+            "warn",
+            "SEGGER J-Link tools are not on PATH (optional -- needed for Flow D "
+            "MRAM flash and SWD debug, not for native_sim or SE-UART flashing). "
+            + requirements,
+            "Install the SEGGER J-Link Software & Documentation Pack "
+            f"(V{_fmt(JLINK_MIN_DLL)} or newer).",
+            scope="host",
+        )
+    if version is None:
+        return Check(
+            "jlink",
+            "warn",
+            f"J-Link tools found at {found} but their version could not be read, so "
+            f"the Flow D MRAM loader could not be confirmed. " + requirements,
+            "Run `JLinkExe` by hand (it prints the banner unprompted, then type "
+            "`exit`) and confirm it reports "
+            f"V{_fmt(JLINK_MIN_DLL)} or newer.",
+            scope="host",
+        )
+    if version < JLINK_MIN_DLL:
+        return Check(
+            "jlink",
+            "warn",
+            f"J-Link V{_fmt(version)} ({found}) predates V{_fmt(JLINK_MIN_DLL)}, which "
+            f"is where Alif's MRAM flash loader became built in -- Flow D has nothing "
+            f"to program MRAM with on this DLL. " + requirements,
+            f"Upgrade the SEGGER J-Link pack to V{_fmt(JLINK_MIN_DLL)}+.",
+            scope="host",
+        )
+    return Check(
+        "jlink", "pass", f"J-Link V{_fmt(version)} ({found}). " + requirements,
+        scope="host",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Host-environment checks (tan-cli#294 finding 1, reintroducing tan-cli#70).
+#
+# `zephyr_sdk_check` above only answers "is a Zephyr SDK installed HERE" --
+# never "CAN one be installed on this machine at all". A Windows-on-ARM or
+# Intel-Mac host is served by neither a native Zephyr SDK build nor (on
+# macOS) a WSL2 fallback, and `zephyrSdkAvailableForHost` below is the ONLY
+# check that says so; `zephyrSdk`'s Fail just points at a `west sdk install`
+# that can never complete there. Unconditional, like `zephyr_sdk_check`: a
+# HOST fact needing no board.yaml/workspace/SDK, so it runs on plain
+# `tan doctor` (ADR 0021 Lane 1 P0a runs that BEFORE anything project-shaped
+# exists).
+# ---------------------------------------------------------------------------
+
+
+def zephyr_sdk_host_check(host_os: str, arch: str) -> Check:
+    """`zephyrSdkAvailableForHost` -- mirrors
+    `tan_core::host_env::zephyr_sdk_host_check` byte-for-byte, including the
+    two DIFFERENT remedies for the two unserved hosts: a Windows-on-ARM host
+    has a first-class route (WSL2, which reports as the served
+    `linux-aarch64`), a macOS host does not (Rosetta translates x86_64 FOR
+    Apple silicon, not the reverse, and there is no WSL2 equivalent) --
+    collapsing the two into one message would send an Intel Mac owner
+    chasing a `wsl --install` that does not exist on their OS.
+
+    `Fail`, not `Warn`: this is the one check in the trio that means "the
+    toolchain cannot run here at all", the same category as a missing
+    `ninja` (`hostPrerequisites`'s own `Fail`) -- there is no artifact for
+    `west sdk install` to fetch, and no amount of PATH or workspace fixing
+    changes that.
+    """
+    tag = f"{host_os}-{arch}"
+    if tag in ZEPHYR_SDK_HOSTS:
+        return Check(
+            "zephyrSdkAvailableForHost",
+            "pass",
+            f"The Zephyr SDK publishes a host build for {tag}.",
+            scope="host",
+        )
+    served = ", ".join(ZEPHYR_SDK_HOSTS)
+    if tag == "windows-aarch64":
+        detail = (
+            f"Windows on ARM ({tag}, `windows-arm64` in Zephyr's own naming): the Zephyr "
+            f"SDK has never published a host build for it. Served hosts are {served}. A "
+            "native Windows build cannot be provisioned on this machine."
+        )
+        fix = (
+            "Build inside WSL2 instead: install a WSL2 Linux distribution "
+            "(`wsl --install`), then run `tan bootstrap` and `tan build` from inside it -- "
+            "a WSL2 distro on this hardware is linux-aarch64, which the Zephyr SDK does "
+            "publish."
+        )
+    elif tag == "macos-x86_64":
+        detail = (
+            f"Intel Mac ({tag}): the Zephyr SDK published this host through 0.17.4 and "
+            f"dropped it in 1.0.0; the pinned SDK serves {served} only. macos-aarch64 is "
+            "not a substitute -- Rosetta translates x86_64 for Apple silicon, not the "
+            "reverse -- and macOS has no WSL2 equivalent to fall back to."
+        )
+        fix = (
+            "Build on a Linux host: a linux-x86_64 VM or container on this Mac, or a "
+            "remote Linux builder. Pinning an older Zephyr SDK is not an option -- the "
+            f"pinned Zephyr requires {ZEPHYR_SDK_INSTALL_VERSION}, which is past the "
+            "release that dropped macos-x86_64."
+        )
+    else:
+        detail = f"The Zephyr SDK publishes no host build for {tag}. Served hosts are {served}."
+        fix = f"Build on one of {served} -- natively, or in a VM/container on this machine."
+    return Check("zephyrSdkAvailableForHost", "fail", detail, fix, scope="host")
+
+
+def _enable_long_paths_fix(key: str) -> str:
+    """The elevated one-liner that sets `LongPathsEnabled` -- shared by every
+    `long_paths_check` arm that names it, so the command cannot drift between
+    them."""
+    return (
+        "Enable long paths in an ELEVATED PowerShell, then reopen your shell and VS "
+        f"Code so new processes pick it up: New-ItemProperty -Path '{key}' -Name "
+        "LongPathsEnabled -Value 1 -PropertyType DWORD -Force"
+    )
+
+
+#: Fix #3 in tan-cli#306: the remedy must name this EXACT command, verbatim
+#: and runnable, no elevation needed (unlike `_enable_long_paths_fix`, which
+#: touches `HKLM`) -- the cheaper fix, and the one that unblocks the actual
+#: reported failure (`west update`'s own `git` calls).
+_GIT_LONG_PATHS_FIX = "Enable it in git: git config --global core.longpaths true"
+
+
+def long_paths_check(registry_enabled: bool | None, git_core_longpaths: bool | None) -> Check:
+    """`longPaths` -- Windows only. Mirrors
+    `tan_core::host_env::long_paths_check`.
+
+    Two independent axes, and conflating them into one is exactly the defect
+    tan-cli#306 reports. `LongPathsEnabled` (the registry) governs manifested
+    Win32 API calls (CMake, Ninja, a plain file open); it does nothing for
+    git, which refuses any path past its own limit unless ITS OWN
+    `core.longpaths` is set, regardless of the registry. `west update`
+    clones/checks out every Zephyr module with `git`, so on a fresh `HOME`
+    (no global `.gitconfig` -- a first-run customer's exact state) the
+    registry read alone reported `pass` while `west update` died on
+    `hal_nxp`'s `tf-psa-crypto` vendor tree with "Filename too long".
+
+    **`Fail`, not `Warn`, exactly when the registry reads enabled and git's
+    does not.** That combination is not a probability the way a bare
+    disabled registry flag is: `west update` runs `git`, `git` is the first
+    thing in the whole toolchain to touch a long path, and its own setting
+    says no -- the break is certain. Anything softer here would repeat the
+    exact defect this check exists to fix.
+
+    **`Warn`, not `Fail` or `Pass`, when git is set but the registry is
+    not.** Git manages long paths on its own once `core.longpaths=true` (it
+    prefixes paths with `\\\\?\\` internally and never consults the
+    registry), so the specific failure this check exists to catch will not
+    reproduce -- but `LongPathsEnabled` still governs every OTHER manifested
+    tool in the chain, so real residual risk remains.
+
+    **`Warn` when neither is set** -- the original, pre-#306 severity for a
+    bare disabled registry flag: workspace-root-depth-dependent, not
+    certain.
+    """
+    key = r"HKLM\SYSTEM\CurrentControlSet\Control\FileSystem"
+    registry_on = registry_enabled is True
+    git_on = git_core_longpaths is True
+
+    if registry_enabled is True:
+        registry_detail = f"{key}\\LongPathsEnabled = 1"
+    elif registry_enabled is False:
+        registry_detail = f"{key}\\LongPathsEnabled is 0 or unset"
+    else:
+        registry_detail = f"{key}\\LongPathsEnabled could not be read"
+
+    if git_core_longpaths is True:
+        git_detail = "git core.longpaths is true"
+    elif git_core_longpaths is False:
+        git_detail = "git core.longpaths is unset or false"
+    else:
+        git_detail = "git core.longpaths could not be determined"
+
+    if registry_on and git_on:
+        status = "pass"
+        headline = "Windows long paths are enabled at both the OS level and in git."
+        fix = None
+    elif registry_on and not git_on:
+        status = "fail"
+        headline = (
+            "Windows reports long paths enabled, but git does not honour that flag: git "
+            "has its own core.longpaths and refuses paths past its limit without it, "
+            "regardless of the registry. west update runs git, so bootstrap WILL fail on "
+            "a long Zephyr module path (e.g. hal_nxp's tf-psa-crypto vendor tree) even "
+            "though this host looks fine."
+        )
+        fix = _GIT_LONG_PATHS_FIX
+    elif git_on:
+        status = "warn"
+        headline = (
+            "git's own core.longpaths is set, so west update's git operations are safe. "
+            "Windows' LongPathsEnabled is not, though, and every OTHER tool in the build "
+            "chain (CMake, Ninja, plain Win32 file APIs) relies on it -- a sufficiently "
+            "deep workspace can still cross MAX_PATH outside of git."
+        )
+        fix = _enable_long_paths_fix(key)
+    else:
+        status = "warn"
+        headline = (
+            "Neither Windows' LongPathsEnabled nor git's core.longpaths is set. A Zephyr "
+            "build/ tree nests deep enough to cross the 260-character MAX_PATH limit, and "
+            'it surfaces as a git "Filename too long" error during west update, or a '
+            "CMake/compiler error about a file that exists."
+        )
+        fix = f"{_GIT_LONG_PATHS_FIX}\n{_enable_long_paths_fix(key)}"
+
+    return Check("longPaths", status, f"{headline} ({registry_detail}; {git_detail}).", fix, scope="host")
+
+
+def tan_install_check(verdict: StaleVerdict | None, version: str) -> Check:
+    """`tanInstall` -- is the RUNNING `tan` behind the source it was installed
+    from? `warn` when so (never `fail`: a stale tan still works, and `exit_code_for`
+    reserves exit 4 for real breakage); `pass` when current OR when it cannot be
+    told (no provenance record, offline, no git) -- an unanswerable question is
+    not a problem. The verdict logic lives in `tan.core.doctor_stale`."""
+    return Check(
+        "tanInstall",
+        "pass" if verdict is None else "warn",
+        f"tan {version}" if verdict is None else verdict.detail,
+        None if verdict is None else verdict.fix,
+        scope="host",
+    )
+
+
+def _tan_install_check() -> Check:
+    """IO half of `tan_install_check`; `TAN_DOCTOR_OFFLINE=1` skips its one
+    short-timeout `git ls-remote`."""
+    from tan.version import TAN_VERSION
+
+    verdict = running_tan_verdict(
+        TAN_VERSION, _resolve_git_executable(), bool(os.environ.get("TAN_DOCTOR_OFFLINE"))
+    )
+    return tan_install_check(verdict, TAN_VERSION)
+
+
+def home_path_check(home: str | None) -> Check:
+    """`homePath` -- does the home directory contain a space? Mirrors
+    `tan_core::host_env::home_path_check`.
+
+    `Warn`, not `Fail`: a space in `C:\\Users\\Jane Doe` is a real historical
+    Zephyr breakage (unquoted paths through CMake/west/Kconfig), but most of
+    the chain quotes correctly now and plenty of hosts with a space build
+    fine -- degraded-but-usable, not a host the toolchain cannot run on at
+    all. `Fail` here would exit 4 for every user whose Windows account name
+    is two words.
+
+    All platforms, not Windows-only: a POSIX `/home/jane doe` breaks the same
+    way -- Windows is merely where `%USERPROFILE%` is derived from a display
+    name the user never chose.
+    """
+    if home is None:
+        return Check(
+            "homePath",
+            "warn",
+            "Could not resolve the home directory (neither USERPROFILE nor HOME is set).",
+            "Set HOME (or USERPROFILE on Windows) -- tan resolves ~/.alp for the SDK cache "
+            "and the global default-SDK pointer from it.",
+            scope="host",
+        )
+    if " " in home:
+        return Check(
+            "homePath",
+            "warn",
+            f"Home directory contains a space: {home}. Zephyr's CMake/west/Kconfig chain "
+            "has historically broken on unquoted paths, and a workspace created under it "
+            "inherits the space.",
+            "Create the workspace at a space-free path (e.g. C:\\alp or /opt/alp) and run "
+            "tan from there with --project, rather than under the home directory.",
+            scope="host",
+        )
+    return Check("homePath", "pass", f"Home directory has no spaces: {home}", scope="host")
+
+
+# ---------------------------------------------------------------------------
+# Build-environment preflight (tan-cli#294 finding 2, reintroducing
+# tan-cli#100, #98, #159): does a build even have a shot at starting?
+#
+# Folded into PLAIN `tan doctor`, mirroring
+# `tan_core::preflight::build_preflight_checks` -- #100's own words for the
+# gap this closes: "probed nothing about the build environment and printed
+# byte-identical output across four materially different host states."
+#
+# `westResolved` (the venv-resolved `west` binary's own presence, tan-cli#123
+# reintroduced) and `zephyrWorkspace`'s severity/gating are now IN scope here
+# too (tan-cli#290) -- see `west_resolved_check`/`zephyr_workspace_check`'s
+# own docstrings. `workspace`/`zephyrVersion`/`zephyrWorkspace` below are all
+# sourced from the SHARED `tan.core.venv.west_workspace_dir` (tan-cli#294
+# review) -- ALL THREE of its steps, including the `$ZEPHYR_BASE`-derived,
+# manifest-verified fallback. A fourth, partial copy of the same search
+# (this module's own retired `_resolve_west_workspace_dir`) previously
+# covered only the project-tree walk and the SDK-derived layout, so a host
+# relying SOLELY on a manually exported `$ZEPHYR_BASE` outside both a
+# project tree and `<sdk-parent>` reported a false `workspace` Fail -- "no
+# Zephyr workspace -- run `tan bootstrap`" -- that would have the customer
+# bootstrap a SECOND workspace. Importing the one shared resolver closed
+# that gap and retired the fourth copy one commit before this one; see
+# `tan.core.venv.west_workspace_dir`'s own docstring for why the search
+# lives there and not here.
+# ---------------------------------------------------------------------------
+
+
+def _broken_global_default() -> str | None:
+    """The raw `sdkPath` `~/.alp/sdk-default` names, ONLY when that pointer
+    file exists but its target is NOT a valid alp-sdk checkout (tan-cli#344).
+    `None` when the pointer is absent, unreadable/malformed, or DOES resolve
+    -- every one of those is indistinguishable from "nothing configured" and
+    stays that way; this exists to name the one case that is not.
+
+    Reads the exact file `sdk_cmd.resolve_sdk_tiered` already reads
+    (`_pointer_target(_home_alp_dir() / "sdk-default")` + `_has_loader_script`)
+    the SAME way, purely for this one extra fact -- it changes no resolution
+    outcome (`resolve_sdk_root_ladder`/`resolve_sdk_tiered` are untouched by
+    this function; it is called separately, only to feed `sdk_check`'s
+    report). `resolve_sdk_tiered` itself already tracks an analogous broken
+    POINTER for the project-pin tier (`ActiveSdk.broken_project_pin`) and
+    surfaces it via `project_pin_issue` regardless of which lower tier
+    answers -- this is the same idea one tier up, for the one tier that had
+    no such memory at all: a dangling global default fell through silently,
+    with nothing left to report it had ever existed.
+    """
+    target = _pointer_target(_home_alp_dir() / "sdk-default")
+    if target is None or _has_loader_script(Path(target)):
+        return None
+    return target
+
+
+def sdk_check(
+    sdk_root: str | None,
+    project_scope: str | None,
+    tier: str | None = None,
+    unselected_candidate: str | None = None,
+    broken_global_default: str | None = None,
+    divergent_candidate: str | None = None,
+    dangling_flag_root: str | None = None,
+) -> Check:
+    """`sdk` -- is an alp-sdk checkout resolved at all? Mirrors
+    `tan_core::preflight::build_preflight_checks`'s `sdk` check.
+
+    `project_scope` (the `--project` value, unjoined) used to name a SCOPED
+    `tan sdk switch <path>` fix (tan-cli#101: the `.alp/sdk-path` pointer
+    `sdk switch` writes is scoped to `--project`, so a bare `tan sdk switch
+    <path>` from a `tan --project <p> doctor` run would have reported success
+    while changing nothing about THIS invocation). That fix is moot now that
+    `sdk switch` refuses outright in every build of tan on this branch
+    (tan-cli#305, `sdk_cmd._run_not_ported`) -- recommending it, scoped or
+    not, was the actual dead end #305 reported, since the ONLY thing left
+    that resolves an SDK at all is `--sdk-root`, which needs no scoping. The
+    parameter stays (worded into the fail detail below) because `--project`
+    is still a fact worth naming, just no longer the reason for a different
+    remedy.
+
+    `tier`/`unselected_candidate` (tan-cli#301) -- a reported host named THREE
+    different roots in one report (a leftover `globalDefault`, a stale
+    `$ZEPHYR_BASE` workspace, and the checkout the user was actually standing
+    in, which appeared nowhere), and `tan doctor`/`tan bootstrap` disagreed
+    about which SDK a bare invocation meant. `GlobalDefault` outranking
+    `Discovery` is deliberate (tan-cli#263 made pins absolute on purpose) --
+    NO behaviour change here, only visibility: `tier` is the `SdkSourceTier`
+    wire spelling (`sdkRootFlag`/`projectPin`/`globalDefault`/`discovery`)
+    that answered, reported alongside the root the same way `tan sdk
+    current`'s envelope already pairs `sdkPath` with `sourceTier`.
+    `unselected_candidate` is a DIFFERENT checkout discoverable from cwd that
+    a higher tier outranked (`None` when the winning tier already IS
+    discovery, or nothing else resolves there) -- named explicitly, with how
+    to select it, so a plausible checkout sitting right there does not read
+    as unconsidered.
+
+    `broken_global_default` (tan-cli#344, `_broken_global_default` above) is
+    the raw `sdkPath` a machine-global `~/.alp/sdk-default` pointer held when
+    that file exists but its target is no longer a valid checkout -- only
+    meaningful in the `sdk_root is None` branch (a global default that DID
+    resolve never reaches this function with `sdk_root is None` at all).
+    Before this, "I have nothing configured" and "what I configured is
+    broken and tan silently fell through past it" printed the identical
+    sentence: `NO_SDK_NEXT_STEPS`, which tells the user to clone a checkout
+    and pass `--sdk-root`, with no hint the thing they already configured is
+    dangling. Falling through stays correct (unchanged here) and exit 4
+    stays correct (unchanged here) -- only which sentence explains it
+    changes. `bootstrap_cmd`'s own broken-pointer messages
+    (`global_default_pointer_fix_hint`) are the shape this matches: name the
+    pointer file directly, never `tan sdk switch`, which refuses outright in
+    this build (tan-cli#305) -- recommending it here would be the exact
+    dead end #305 already fixed for the project-pin case.
+
+    `dangling_flag_root` (tan-cli#727) is the raw `--sdk-root` text when that
+    flag named a path carrying no `scripts/alp_project.py`. `--sdk-root` is
+    the terminal tier, so `resolve_sdk_root_ladder` hands it back unvalidated
+    -- correct for a caller that only REPORTS the tier, and wrong for this
+    one, whose entire job is answering "is my setup right". `tan build` given
+    the same path refuses (`build_cmd`, `run_cmd`, `validate_cmd`,
+    `clean_cmd`, `flash_cmd` each guard at their own call site with
+    `is_sdk_root`); doctor did not, so the two commands disagreed about the
+    same flag and it was doctor saying yes. Reported as its own sentence
+    rather than by nulling the root into the `NO_SDK_NEXT_STEPS` branch,
+    which tells the user to clone a checkout and pass `--sdk-root` -- the
+    thing they just did.
+    """
+    if dangling_flag_root is not None:
+        return Check(
+            "sdk",
+            "fail",
+            rejected_sdk_root_message(
+                dangling_flag_root,
+                "`tan build` refuses this same path, so nothing this report "
+                "says about the SDK describes a checkout that is there.",
+            ),
+            "Point --sdk-root at a directory holding the marker above. "
+            "`tan bootstrap` MOVES the checkout into the workspace and "
+            "rewrites the default (tan-cli#185), so a --sdk-root copied from "
+            "before a bootstrap names the path it emptied.",
+            scope="project",
+        )
+    if sdk_root is not None:
+        detail = f"alp-sdk at {sdk_root}"
+        if tier is not None:
+            detail += f" ({tier}"
+            if unselected_candidate is not None:
+                detail += (
+                    f"; a checkout at {unselected_candidate} was not selected -- "
+                    f"pass --sdk-root {unselected_candidate} to use it"
+                )
+            detail += ")"
+        if divergent_candidate is not None:
+            # BOTH roots re-rendered POSIX here, unlike the `pass` branch's
+            # `alp-sdk at {sdk_root}` above, which keeps this host's native
+            # separators and is left byte-identical. The reason is the CODE:
+            # this branch's detail becomes an `issues[].message` under
+            # `sdk.discovery-divergent`, which four other commands also emit
+            # -- and all four build it from `_abs_posix`. A consumer
+            # correlating two envelopes would otherwise match a code across a
+            # message spelled `C:/...` on one side and `C:\...` on the other.
+            # The envelope is the contract; normalise the filesystem side to
+            # meet it, never the other way round (caught by
+            # windows-latest on tan-cli#428, green everywhere else).
+            posix_root = f"alp-sdk at {_abs_posix(sdk_root)}"
+            if tier is not None:
+                posix_root += f" ({tier})"
+            return Check(
+                "sdk",
+                "warn",
+                f"{posix_root}; `tan init`, `tan generate` and "
+                f"`tan examples` resolve a DIFFERENT checkout from this "
+                f"directory ({_abs_posix(divergent_candidate)}) and report "
+                f'the same sourceTier "discovery", so generated files and '
+                f"the build plan can come from different SDK versions.",
+                f"--sdk-root <path> to pin the one you mean for a single run, "
+                f"or `tan init --sdk-root <path>` to write it into "
+                f".alp/sdk-path, which outranks both discovery tiers.",
+                code=SDK_DISCOVERY_DIVERGENT,
+                scope="project",
+            )
+        return Check("sdk", "pass", detail, scope="project")
+    scope_note = f" for --project {project_scope}" if project_scope is not None else ""
+    if broken_global_default is not None:
+        home = _home_alp_dir()
+        pointer = str(home / "sdk-default")
+        return Check(
+            "sdk",
+            "fail",
+            f"no SDK selected{scope_note} -- the machine-global default "
+            f'({pointer}) names "{broken_global_default}", which is not a '
+            f"valid alp-sdk checkout, so tan fell through past it and found "
+            f"nothing else either.",
+            f"{global_default_pointer_fix_hint(pointer, str(registry_path(home)))}, or "
+            f"pass --sdk-root <path> directly.",
+            scope="project",
+        )
+    return Check(
+        "sdk",
+        "fail",
+        f"no SDK selected{scope_note} -- {NO_SDK_NEXT_STEPS}",
+        "--sdk-root <path>",
+        scope="project",
+    )
+
+
+def board_yaml_preflight_check(present: bool, project_selected: bool) -> Check:
+    """`boardYaml` -- mirrors `build_preflight_checks`'s check of the same
+    name, PLUS the project-selection awareness the Rust oracle's debug
+    report has and this port's copy used to lack (tan-cli#294 review,
+    reintroducing #100(b)): `tan bootstrap` prints `tan doctor` as the very
+    next command, run from the SDK checkout root it just set up -- which has
+    no `board.yaml` and needs none. Failing there made the first command a
+    new customer types report `1 failed` and exit 4 for a non-problem.
+
+    `project_selected` is True only when `--project` or `--board-yaml` was
+    actually given (mirrors `crates/tan-cli/src/commands/doctor.rs::
+    project_selected` -- with neither flag the resolved path is a guess at
+    the cwd, not a request) and is only read when `present` is False.
+
+    NOT a duplicate of a debug-report `boardYaml` check (this port has not
+    built the debug half -- see the module docstring), so this is the only
+    `boardYaml` check in this file and it is never dropped.
+    """
+    if present:
+        return Check("boardYaml", "pass", "board.yaml found", scope="project")
+    if project_selected:
+        return Check(
+            "boardYaml",
+            "fail",
+            "board.yaml not found -- run `tan init` or pass `--board-yaml <path>`",
+            "tan init",
+            scope="project",
+        )
+    return Check(
+        "boardYaml",
+        "warn",
+        "no project selected -- no board.yaml found",
+        "Select a project with `--project <dir>` (or `--board-yaml <path>`) to check one.",
+        scope="project",
+    )
+
+
+def libraries_check(report: LibraryReport | None) -> Check | None:
+    """`libraries` -- the ADR-0018 curated-library verdict for the selected
+    project: tier, licence, and whether each selection can actually be wired
+    on this target.
+
+    Ported from alp-sdk's `scripts/alp_cli/doctor.py::_check_libraries`
+    (ADR-0020 end-state B -- a user-facing check belongs on the user command
+    surface, which is `tan`; alp-sdk keeps the library LAYER, not a second CLI
+    reporting on it). `tan.core.doctor_libraries` owns the resolution, the
+    outcome vocabulary and the defect the port fixed; this is the mapping.
+
+    `None` -- no row at all -- for no project in scope and for one selecting
+    no libraries; a permanent "0 selected" line would sit in front of every
+    customer not using the feature, and `venv_provenance_check` is precedent
+    for declining to speak over speaking emptily.
+
+    Never `fail`: `tan build` refuses an unwireable selection outright, so the
+    hard gate exists already and is the emit, and a `fail` here would also
+    cost exit 4 -- making "you picked a library this board cannot run" read
+    identically to "you have no toolchain". alp-sdk's original call, kept.
+    `scope="project"` because the subject is that board.yaml against that
+    checkout, which answers identically on every host (`doctor_scope`)."""
+    if report is None:
+        return None
+    joined = ", ".join(report.labels)
+    count = len(report.names)
+    if report.outcome == "ok":
+        return Check(
+            "libraries", "pass", f"{count} selected, all compatible: {joined}", scope="project"
+        )
+    if report.outcome == "unreadable":
+        return Check("libraries", "warn", report.detail, scope="project")
+    if report.outcome == "unverifiable":
+        return Check(
+            "libraries",
+            "warn",
+            f"{count} selected, none verified ({joined}) -- {report.detail}",
+            # `NO_SDK_NEXT_STEPS`, never a hand-written `tan sdk switch` --
+            # that verb is refused (test_sdk_onboarding_dead_end.py).
+            f"{NO_SDK_NEXT_STEPS}, then re-run `tan doctor`.",
+            scope="project",
+        )
+    return Check(
+        "libraries",
+        "warn",
+        f"{count} selected: {joined} -- INCOMPATIBLE: {report.detail}",
+        "Fix or remove the offending `libraries:` entry in board.yaml; `tan build` "
+        "rejects it as a hard error.",
+        scope="project",
+    )
+
+
+def workspace_patches_check(result: PatchCheck, workspace_dir: str) -> Check:
+    """`workspacePatches` (tan-cli#1376) -- is alp-sdk's `zephyr/patches.yml`
+    applied in the resolved workspace? A tree without them still BUILDS; the
+    gap shows up on the device (`alp_camera_open` -> `ALP_ERR_NOSUPPORT` for a
+    missing Alif clock `set_rate`). `unknown` (never a failure) when the SDK has
+    no verifier or the check could not run, so an offline doctor stays green."""
+    if result.state == WORKSPACE_PATCHES_APPLIED:
+        return Check(
+            "workspacePatches", "pass",
+            f"zephyr/patches.yml {result.note} in {workspace_dir}", scope="project",
+        )
+    if result.state == WORKSPACE_PATCHES_MISSING:
+        return Check(
+            "workspacePatches",
+            "warn",
+            f"alp-sdk's zephyr/patches.yml is not applied in {workspace_dir}: "
+            f"{describe_unapplied(result.patches, result.modules)}. The build still succeeds, "
+            "but features that need them fail at runtime (for example `alp_camera_open` "
+            f"returns ALP_ERR_NOSUPPORT). Fix: {patch_fix_text(result.modules, workspace_dir)}.",
+            "tan bootstrap",
+            scope="project",
+        )
+    return Check(
+        "workspacePatches", "unknown", f"patches not checked: {result.note}.", scope="project"
+    )
+
+
+def zephyr_base_check(env_value: str | None, workspace_dir: str) -> Check | None:
+    """`zephyrBase` (tan-cli#1376) -- only when `$ZEPHYR_BASE` names a tree other
+    than the resolved workspace's zephyr, which tan ignores. A `pass` carrying
+    the explanation: it is information, not a problem with the host."""
+    note = zephyr_base_note(env_value, str(Path(workspace_dir) / "zephyr"))
+    if note is None:
+        return None
+    return Check("zephyrBase", "pass", note, scope="project")
+
+
+def workspace_preflight_check(
+    workspace_dir: str | None,
+    *,
+    start: str | None = None,
+    sdk_root: str | None = None,
+    zephyr_base: str | None = None,
+) -> Check:
+    """`workspace` -- is a Zephyr WORKSPACE (a directory holding `.west/`)
+    resolved at all? Mirrors `build_preflight_checks`'s check of the same
+    name. Distinct from `hostPrerequisites`/`west` above, which only confirm
+    the TOOLS needed to build are on PATH -- neither confirms a Zephyr tree
+    exists to build against.
+
+    tan-cli#1432: with `start` and `sdk_root` known, an unresolved workspace
+    is judged by what `tan build` will then do (see `tan.core.
+    west_workspace_refusal.unresolved_workspace_verdict`), not reported as a
+    bare "no Zephyr workspace" when west's own walk still finds one.
+    """
+    if workspace_dir is not None:
+        return Check("workspace", "pass", f"Zephyr workspace at {workspace_dir}", scope="project")
+    status, detail = "fail", (
+        "no Zephyr workspace -- run `tan bootstrap` (reuses a compatible Zephyr, else "
+        "bootstraps one)"
+    )
+    if start is not None and sdk_root is not None:
+        status, detail = unresolved_workspace_verdict(Path(start), zephyr_base, Path(sdk_root))
+    return Check("workspace", status, detail, "tan bootstrap", scope="project")
+
+
+def zephyr_version_preflight_check(
+    workspace_version: str | None, sdk_pin: str | None
+) -> Check | None:
+    """`zephyrVersion` -- does a REUSED workspace's Zephyr match the active
+    SDK's `west.yml` pin? Mirrors `build_preflight_checks`'s check
+    (tan-cli#98/#159): compared at full `MAJOR.MINOR.PATCH`, because a
+    truncated `MAJOR.MINOR` comparison let a patch-level pin bump
+    (`v4.4.0` -> `v4.4.1`) read as a match -- the drifted-checkout shape of
+    the alp-sdk#855 incident.
+
+    `None` (no check emitted) when either side is unknown, matching Rust's
+    own skip: don't nag when this cannot actually be verified.
+
+    **`Fail`, not `Warn`** (#159): a reused workspace on the wrong Zephyr
+    does not "maybe" break the build -- it compiles against a different
+    Zephyr than the plan was emitted for, and a Warn here is indistinguishable
+    from a check that can never fail.
+    """
+    if workspace_version is None or sdk_pin is None:
+        return None
+    if workspace_version == sdk_pin:
+        return Check(
+            "zephyrVersion", "pass", f"Zephyr v{workspace_version} matches the SDK pin",
+            scope="project",
+        )
+    return Check(
+        "zephyrVersion",
+        "fail",
+        f"reused Zephyr v{workspace_version} != SDK pin v{sdk_pin} -- run `tan bootstrap` "
+        "to refresh the workspace",
+        "tan bootstrap",
+        scope="project",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Venv provenance (tan-cli#292 consequences 1 and 3).
+# ---------------------------------------------------------------------------
+
+
+def venv_provenance_check(record: WorkspaceSdkRecord | None, sdk_root: str | None) -> Check | None:
+    """`venvProvenance` -- does the RESOLVED workspace venv's tan-written
+    record (`<topdir>/.west/tan-workspace-sdk`, tan-cli#292) name the SAME SDK
+    this report resolved against? Catches two of #292's three consequences:
+    `tan sdk switch` leaving the venv behind (consequence 3 -- the record
+    still names the SDK that last populated it), and a neighbouring project's
+    venv winning `find_workspace_venv`'s upward walk when that venv is ITSELF
+    tan-bootstrapped, just for a different SDK (consequence 1 -- its own
+    record then names a project this report was never asked about). Both
+    otherwise surface only later, as a Zephyr build failing on a
+    wrong-version package that names the SYMPTOM, not the cause.
+
+    **A WARNING, not a re-resolution (tan-cli#292 rc3 scope).** The record is
+    not yet the resolver's primary source -- `tan build` still uses whatever
+    `find_workspace_venv`'s search resolved; this only tells the customer
+    that venv's packages may not match BEFORE a build fails on it. Consequence
+    1's upward-walk case is caught only when the neighbouring venv carries its
+    OWN record; one populated by a bare `west update` with no tan involvement
+    anywhere still resolves silently -- the same gap `west_workspace_dir`'s
+    `$ZEPHYR_BASE` manifest guard cannot close for an unrelated tree with no
+    alp-sdk manifest to check against either. The full record-primary
+    resolver the issue also proposes is out of scope for this fix; see the
+    issue for the follow-up.
+
+    `None` (no check emitted, matching `zephyr_version_preflight_check`'s own
+    skip) when there is nothing to compare: no venv resolved, it carries no
+    record at all -- a workspace bootstrapped by alp-sdk's own `bootstrap.sh`
+    writes none (`crates/tan-cli/src/venv.rs:25-27`), and neither does a tan
+    predating tan-cli#292 -- or no `sdk_root` resolved to compare against.
+    """
+    if record is None or sdk_root is None:
+        return None
+    if os.path.normcase(_abs_posix(record.sdk_path)) == os.path.normcase(_abs_posix(sdk_root)):
+        return Check(
+            "venvProvenance", "pass", f"workspace venv populated for the active SDK ({record.sdk_path})",
+            scope="project",
+        )
+    return Check(
+        "venvProvenance",
+        "warn",
+        f"workspace venv was populated for a different SDK ({record.sdk_path}) than the "
+        f"one currently selected ({sdk_root}) -- Zephyr packages installed into it may not "
+        "match; run `tan bootstrap` to resync the venv",
+        "tan bootstrap",
+        scope="project",
+    )
+
+
+# ---------------------------------------------------------------------------
+# SDK provenance (tan-cli#294 finding 5; no numbered GH issue -- the Rust
+# doc comment cites "conformance Issue 4 + 6").
+# ---------------------------------------------------------------------------
+
+
+def sdk_provenance_check(sdk_root: str) -> Check:
+    """`sdkProvenance` -- records the SDK checkout's git short-commit and
+    `metadata/sdk_version.yaml` version, so a build plan can be traced back
+    to the planner that produced it, and warns when the checkout is behind
+    its upstream tracking ref. Mirrors
+    `crates/tan-cli/src/commands/doctor.rs`'s `append_sdk_provenance`.
+
+    Advisory only: `git_behind_upstream` reads the local remote-tracking ref
+    and performs no network fetch, so it only reflects the checkout's state
+    as of the last `git fetch` -- never blocks a build over it.
+    """
+    # tan-cli#797: resolved ONCE and threaded through both git calls below --
+    # each spawns `git` itself, and re-resolving per call would not be wrong,
+    # only wasteful; the point that matters is that neither one hands
+    # `subprocess` the bare `"git"` (see `_resolve_git_executable`).
+    git_exe = _resolve_git_executable()
+    commit = _git_short_commit(sdk_root, git_exe)
+    version = _read_sdk_version(sdk_root)
+    if version and commit:
+        detail = f"alp-sdk {version} @ {commit}"
+    elif commit:
+        detail = f"alp-sdk @ {commit}"
+    elif version:
+        detail = f"alp-sdk {version}"
+    else:
+        detail = f"alp-sdk at {sdk_root} (no git checkout / metadata/sdk_version.yaml)"
+
+    behind = _git_behind_upstream(sdk_root, git_exe)
+    if behind is not None and behind > 0:
+        return Check(
+            "sdkProvenance",
+            "warn",
+            f"{detail} -- {behind} commit(s) behind upstream",
+            f"Update the SDK checkout: git -C {sdk_root} pull",
+            scope="project",
+        )
+    return Check("sdkProvenance", "pass", detail, scope="project")
+
+
+# _resolve_git_executable / _is_own_git_checkout / _git_short_commit /
+# _git_behind_upstream moved to tan.core.doctor_git (tan-cli#797 module-size
+# budget); imported above.
+
+def _read_sdk_version(root: str) -> str | None:
+    """Read a version from `<root>/metadata/sdk_version.yaml`. Shares
+    `sdk_cmd.parse_sdk_version_yaml` with `check_sdk_readiness`
+    (tan-cli#162), so `tan sdk install`/`current`/`switch` and this check
+    read the SAME version out of the SAME file rather than two copies of the
+    scan able to disagree."""
+    text = _read_text(Path(root) / "metadata" / "sdk_version.yaml")
+    if text is None:
+        return None
+    return parse_sdk_version_yaml(text)
+
+
+# ---------------------------------------------------------------------------
+# Aggregation
+# ---------------------------------------------------------------------------
+
+
+def summarise(checks: list[Check]) -> dict[str, int]:
+    """`pass`/`warn`/`fail` counts. `unknown` lands in NONE of them, so
+    `sum(summary.values())` can be smaller than `len(checks)` -- deliberate, and
+    the same shape the Rust `DoctorSummary` has."""
+    return {
+        "pass": sum(1 for c in checks if c.status == "pass"),
+        "warn": sum(1 for c in checks if c.status == "warn"),
+        "fail": sum(1 for c in checks if c.status == "fail"),
+    }
+
+
+def next_steps(checks: list[Check]) -> list[str]:
+    """Deduplicated fixes for non-passing checks. `unknown` contributes none:
+    a check nobody could run has nothing to remediate."""
+    steps: list[str] = []
+    for check in checks:
+        if check.status in ("pass", "unknown") or check.fix is None:
+            continue
+        if check.fix not in steps:
+            steps.append(check.fix)
+    return steps
+
+
+_CAMEL_BOUNDARY = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+def kebab_check_name(name: str) -> str:
+    """`Check.name` (camelCase, also a JSON data key/display string -- left
+    alone) -> the kebab-case slug an issue *code* uses, e.g. `'sevenZip'` ->
+    `'seven-zip'`. `contract/issue-codes.json`'s registry gate
+    (`^[a-z][a-z0-9-]*\\.[a-z0-9-]+$`) rejects camelCase; 27 issue codes
+    derived straight from `check.name` shipped camelCase in v0.5.0 before this
+    existed."""
+    return _CAMEL_BOUNDARY.sub("-", name).lower()
+
+
+def checks_to_issues(checks: list[Check]) -> list[Issue]:
+    """Warn/fail checks become issues; `unknown` raises none (it is not a
+    problem, the question was simply not askable). The code is the check's own
+    when it has one -- the frozen `bootstrap.*` spellings -- else Rust's
+    `doctor.<checkName>` convention, kebab-cased (`kebab_check_name`)."""
+    return [
+        Issue(
+            check.code or f"doctor.{kebab_check_name(check.name)}",
+            "error" if check.status == "fail" else "warning",
+            check.detail,
+        )
+        for check in checks
+        if check.status in ("warn", "fail")
+    ]
+
+
+def exit_code_for(checks: list[Check]) -> ExitCode:
+    """Exit 4 on any failure. Never 0 on an unhealthy host: a green doctor over a
+    broken environment converts a fixable setup problem into a mystery inside
+    somebody else's build system."""
+    return (
+        ExitCode.DOCTOR_FAILURE
+        if any(c.status == "fail" for c in checks)
+        else ExitCode.SUCCESS
+    )
+
+
+# ---------------------------------------------------------------------------
+# The IO layer: probe the host, then hand facts to the pure checks above
+# ---------------------------------------------------------------------------
+
+
+#: `platform.machine()` -> the Zephyr-SDK-release arch token
+#: (`tan_core::host_env::ZEPHYR_SDK_HOSTS`'s spelling). Values seen in
+#: practice: Windows `AMD64`/`ARM64`, macOS `x86_64`/`arm64`, Linux
+#: `x86_64`/`aarch64`. An unrecognised value is passed through unchanged, so
+#: `zephyr_sdk_host_check` reports it as a real, unserved tag rather than
+#: silently mapping it onto a served one.
+_ARCH_TAGS = {
+    "amd64": "x86_64",
+    "x86_64": "x86_64",
+    "arm64": "aarch64",
+    "aarch64": "aarch64",
+}
+
+
+def _macos_rosetta_translated() -> bool:
+    """`True` when THIS process's Python interpreter is an x86_64 binary
+    running under Rosetta on Apple silicon -- `sysctl -n
+    sysctl.proc_translated` == 1. Mirrors
+    `tan_core::host_env::arch_for_proc_translated`'s macOS probe
+    (`crates/tan-cli/src/commands/doctor.rs:601-611`) via the `sysctl` CLI
+    rather than a `ctypes` binding to the same `sysctlbyname` FFI -- this
+    module's probes are all subprocess-based, and the sysctl is a stable
+    macOS command-line surface. `probe()` (and so this) returns `False` on a
+    pre-Big-Sur host where the sysctl does not exist -- the compiled arch is
+    already correct there, matching Rust's `rc == 0 && translated == 1`.
+
+    `sysctl` itself is resolved through `tool_lookup.resolve_tool` before the
+    spawn (tan-cli#797), the same treatment as this module's other probes --
+    POSIX `execvp` never searches the current directory the way Windows'
+    `CreateProcess` does, so a bare `argv[0]` here was never the strong form
+    of the hazard, but leaving one spawn unresolved while the rest of the
+    module resolves would be a needless inconsistency for the next reader to
+    puzzle over. `False` when `sysctl` is not on PATH at all -- the same
+    "nothing to report" verdict as every other way this probe can fail.
+    """
+    resolved = resolve_tool("sysctl", os.environ).resolved
+    if resolved is None:
+        return False
+    return (
+        probe(["sysctl", "-n", "sysctl.proc_translated"], executable=resolved) or ""
+    ).strip() == "1"
+
+
+def _host_os_arch_tags() -> tuple[str, str]:
+    """`(os, arch)` in `tan_core::host_env::ZEPHYR_SDK_HOSTS`'s tokens, read
+    from `platform.system()`/`platform.machine()`, corrected for Rosetta.
+
+    Unlike the Rust oracle, this does NOT detect Windows-on-ARM x64 emulation
+    (`IsWow64Process2`): tan's Python port runs under whatever interpreter is
+    already installed rather than a separately-compiled per-arch binary, so
+    `platform.machine()` reflects the INTERPRETER's real architecture in the
+    overwhelming majority of cases (a user who installed an x86_64 Python on
+    Windows-on-ARM, where Python.org has shipped a native ARM64 installer for
+    some time, is the one host this can under-report -- tracked, not silently
+    claimed complete).
+
+    macOS IS corrected (tan-cli#294 review): the opposite direction is common
+    there and worse. Rosetta silently runs the far more widely distributed
+    x86_64 Python build on Apple silicon, so `platform.machine()` alone
+    reported `macos-x86_64` -- a FALSE HARD REFUSAL
+    (`zephyr_sdk_host_check`'s `Fail`, exit 4, "build on a Linux host") on
+    hardware the pinned SDK serves natively as `macos-aarch64`.
+    """
+    system = platform.system().lower()
+    host_os = {"windows": "windows", "darwin": "macos", "linux": "linux"}.get(system, system)
+    machine = platform.machine().lower()
+    arch = _ARCH_TAGS.get(machine, machine)
+    if host_os == "macos" and arch == "x86_64" and _macos_rosetta_translated():
+        arch = "aarch64"
+    return host_os, arch
+
+
+# classify_git_core_longpaths / _git_core_longpaths moved to
+# tan.core.doctor_git (tan-cli#797 module-size budget); imported above.
+
+
+def _long_paths_enabled() -> bool | None:
+    """Windows `HKLM\\SYSTEM\\CurrentControlSet\\Control\\FileSystem\\
+    LongPathsEnabled`, via the stdlib `winreg` module (Windows-only).
+
+    `None` off Windows (`long_paths_check` is never reached there --
+    `_collect` gates the append on `os.name == "nt"`) and on any registry
+    read failure OTHER than the value/subkey being absent -- an access
+    denial, a value of the wrong type -- so the check can say "unknown"
+    rather than guess. An absent value/subkey (`FileNotFoundError`) IS
+    "disabled": that is the Windows default-off state and by far the most
+    common one, matching `tan_core::host_env::classify_long_paths`.
+    """
+    if os.name != "nt":
+        return None
+    try:
+        import winreg
+    except ImportError:  # pragma: no cover -- always present on Windows CPython
+        return None
+    try:
+        with winreg.OpenKey(
+            winreg.HKEY_LOCAL_MACHINE, r"SYSTEM\CurrentControlSet\Control\FileSystem"
+        ) as key:
+            value, _ = winreg.QueryValueEx(key, "LongPathsEnabled")
+            return bool(value)
+    except FileNotFoundError:
+        return False
+    except OSError:
+        return None
+
+
+#: Where the `arm-zephyr-eabi` cross compiler sits INSIDE a zephyr-sdk-1.0.1
+#: root -- the version `ZEPHYR_SDK_INSTALL_VERSION` above pins and the only
+#: one this file's fix hints (`zephyr_sdk_install_command`) ever name.
+#:
+#: tan-cli#286 third pass: the SECOND pass's blocker. `_zephyr_sdk_root_valid`
+#: and `test_doctor_command.py`'s own `_plant_zephyr_sdk` fixture both
+#: previously hardcoded the WRONG layout (un-prefixed `arm-zephyr-eabi/bin/`)
+#: independently, so they agreed with EACH OTHER instead of with a real SDK
+#: and 77 tests passed over a broken probe. Both now build from this one
+#: tuple so they cannot drift back to silently matching only each other.
+#:
+#: The `gnu/` prefix is decisive, not guessed: a maintainer build log on the
+#: exact host this check hard-failed on -- "Found assembler:
+#: <home>/zephyr-sdk-1.0.1/gnu/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc.exe"
+#: -- plus three in-repo measurements agreeing byte-for-byte:
+#: `crates/tan-core/src/runners.rs`'s real-AEN801-build fixture (`gdb:
+#: /zephyr-sdk-1.0.1/gnu/arm-zephyr-eabi/bin/arm-zephyr-eabi-gdb-py`),
+#: `crates/tan-core/src/debug_launch.rs`'s resolution test (same `gdbPath`),
+#: and `contract/fixtures/toolchains/toolchains.json`'s `du -sb` measurement
+#: of `gnu/arm-zephyr-eabi/` (784086497 bytes) as its own line item, separate
+#: from `hosttools/`.
+#:
+#: NOT widened to also accept the older, un-prefixed `arm-zephyr-eabi/bin/`
+#: layout (0.16.x): every fix hint in this file already promises exactly
+#: `--version 1.0.1`, so treating a stale sub-1.0 install as a Pass would
+#: validate a toolchain this file's own advice says to replace. NOT probing
+#: the SDK's own `sdk_version`/`sdk_toolchains` marker files either, tempting
+#: as a layout-proof alternative would be: no measurement of either file's
+#: real name, location or format exists anywhere in this repo, and guessing
+#: at one is the exact unverified-brief mistake that put the wrong compiler
+#: path here to begin with.
+ZEPHYR_SDK_TOOLCHAIN_DIR = ("gnu", "arm-zephyr-eabi", "bin")
+
+
+def _zephyr_sdk_root_valid(root: Path) -> bool:
+    """`True` when `root` is an actually-installed Zephyr SDK -- not merely a
+    directory that happens to be named right, or still named by a stale
+    `ZEPHYR_SDK_INSTALL_DIR`. Probes the one file every downstream check
+    (`west build`, `west flash`) actually needs: the `arm-zephyr-eabi` cross
+    compiler, at `ZEPHYR_SDK_TOOLCHAIN_DIR`. `is_dir()` alone passes on an
+    EMPTY directory -- the exact false Pass tan-cli#286 exists to fix;
+    measuring the shipped thing instead of a directory-name proxy is what
+    makes this port's docstring true.
+    """
+    exe = "arm-zephyr-eabi-gcc.exe" if os.name == "nt" else "arm-zephyr-eabi-gcc"
+    try:
+        return root.joinpath(*ZEPHYR_SDK_TOOLCHAIN_DIR, exe).is_file()
+    except OSError:
+        return False
+
+
+def _zephyr_sdk_scan_roots() -> list[Path]:
+    """Every directory `_zephyr_sdk_detected` scans for a `zephyr-sdk-*`
+    install, besides `/opt` -- `$HOME`, `%USERPROFILE%` AND `Path.home()`,
+    ALL of them, never `HOME or USERPROFILE` -- PLUS the ADR 0021
+    artifact-keyed store (`~/.alp/toolchains`, or `$ALP_TOOLCHAIN_ROOT`)
+    `tan bootstrap`'s own toolchain phase installs into, two directory
+    levels below `$HOME` and invisible to the first four roots (tan-cli#1186:
+    a real compiler planted at that exact bootstrap-filled path was measured
+    returning `False` here before this root was added).
+    `_toolchain_store_scan_root`/`_is_toolchain_wreckage` are reused from
+    `build.toolchain` rather than re-derived -- the SAME store root
+    `${TOOLCHAIN_ROOT}` substitution (tan-cli#547) already scans, so this
+    check and that one cannot independently drift on where tan's own
+    installs live, and the SAME `.tmp-<pid>` wreckage exclusion applies (an
+    interrupted acquisition's leftover also starts with `zephyr-sdk`). Routed
+    through the same string-level `seen` dedup as the other four roots (an
+    `ALP_TOOLCHAIN_ROOT` pointed at `$HOME` or `/opt` -- both legitimate,
+    e.g. a bench-machine escape hatch -- would otherwise list that directory
+    twice; harmless for this yes/no scan but not for the invariant the other
+    roots already hold).
+
+    Under Git Bash/MSYS on Windows, `HOME` is a POSIX-translated path
+    (`/c/Users/dev`) while the real Zephyr SDK sits under the native
+    `%USERPROFILE%` (`C:\\Users\\dev\\zephyr-sdk-1.0.1`). `or`ing the two
+    picks whichever is set first and silently drops the other -- proven on a
+    real host: that host HAS the SDK and `_zephyr_sdk_detected()` still
+    returned `False`, a hard doctor FAIL worse than the false PASS #286
+    exists to fix. `Path.home()` resolves independently of both env vars
+    (POSIX `pwd`/`$HOME`; Windows `USERPROFILE` via CPython's own
+    `ntpath.expanduser`) and can disagree with both, so it is scanned too,
+    not assumed redundant.
+    """
+    roots = [Path("/opt")]
+    seen: set[str] = {str(roots[0])}
+    for raw in (os.environ.get("HOME"), os.environ.get("USERPROFILE")):
+        if raw and raw not in seen:
+            seen.add(raw)
+            roots.append(Path(raw))
+    try:
+        home = Path.home()
+    except (OSError, RuntimeError):
+        home = None
+    if home is not None and str(home) not in seen:
+        roots.append(home)
+        seen.add(str(home))
+    store_root = _toolchain_store_scan_root()
+    if str(store_root) not in seen:
+        roots.append(store_root)
+    return roots
+
+
+def _zephyr_sdk_detected_roots() -> list[Path]:
+    """EVERY root the scan validates, in precedence order (tan-cli#1483: the
+    adoption check needs to see all of them, not just the first -- a
+    mismatched `ZEPHYR_SDK_INSTALL_DIR` must not hide an installed copy of the
+    pinned version). `ZEPHYR_SDK_INSTALL_DIR` first, then each `zephyr-sdk*`
+    entry under `_zephyr_sdk_scan_roots()`.
+
+    Never raises: an unreadable or missing scan root is "nothing found
+    there", not a doctor crash.
+    """
+    found: list[Path] = []
+    env_dir = os.environ.get("ZEPHYR_SDK_INSTALL_DIR")
+    if env_dir and _zephyr_sdk_root_valid(Path(env_dir)):
+        found.append(Path(env_dir))
+    for root in _zephyr_sdk_scan_roots():
+        try:
+            entries = sorted(root.iterdir())
+        except OSError:
+            continue
+        for entry in entries:
+            if (
+                entry.name.startswith("zephyr-sdk")
+                and not _is_toolchain_wreckage(entry.name)
+                and _zephyr_sdk_root_valid(entry)
+            ):
+                found.append(entry)
+    return found
+
+
+def _zephyr_sdk_detected_root() -> Path | None:
+    """The first root `_zephyr_sdk_detected_roots` validates, or `None`."""
+    roots = _zephyr_sdk_detected_roots()
+    return roots[0] if roots else None
+
+
+def _zephyr_sdk_detected() -> bool:
+    """`True` when a Zephyr SDK toolchain is installed anywhere this host
+    would resolve one from. Descends from `crate::toolchain::
+    resolve_toolchain_root`/`zephyr_sdk_detected` in the now-deleted Rust
+    oracle (`crates/` retired in tan-cli#601) -- doctor only ever needed that
+    pair's yes/no half. Build-plan `${TOOLCHAIN_ROOT}` substitution is its own
+    resolver now, not `None` as it was when this docstring was last true:
+    `build.toolchain.resolve_toolchain_root` (tan-cli#547), which
+    `build_cmd.py` calls and passes on as `toolchain_root=toolchain.root`.
+    That resolver is stricter on purpose -- a host with SEVERAL candidate
+    installs and no `ZEPHYR_SDK_INSTALL_DIR` to choose between them must FAIL
+    a substitution (the wrong one silently baked into a slice is worse than
+    refusing), but should not fail doctor's plain yes/no here, which only
+    needs to know that AT LEAST one usable toolchain exists somewhere:
+    `ZEPHYR_SDK_INSTALL_DIR`, honored ONLY when the directory it names
+    actually CONTAINS the toolchain (`_zephyr_sdk_root_valid` -- the variable
+    is exported from a shell profile and routinely outlives the SDK it once
+    pointed at, e.g. after `rm -rf ~/zephyr-sdk-0.16.5`, and an empty
+    directory it never pointed at anything real for is the same failure mode
+    -- trusting presence alone would report a false Pass here and the real
+    failure would surface later as a raw CMake toolchain error); else any
+    `zephyr-sdk*`-named directory, similarly validated, directly under
+    `_zephyr_sdk_scan_roots()` -- which now also covers the ADR 0021
+    artifact-keyed store `tan bootstrap` fills (tan-cli#1186). Several
+    installs still count as detected here -- this is only doctor's yes/no,
+    not the ambiguous-root pick `${TOOLCHAIN_ROOT}` substitution needs.
+
+    Never raises: an unreadable or missing scan root is "nothing found
+    there", not a doctor crash. Delegates to `_zephyr_sdk_detected_root` so
+    the two cannot independently drift on what "detected" means.
+    """
+    return _zephyr_sdk_detected_root() is not None
+
+
+def _resolve_dtc() -> devicetree_lint.DtcResolution:
+    """Resolve `dtc` the way `zephyr/cmake/modules/FindDtc.cmake` would, and
+    ask it its version -- the IO half of `devicetree_lint_check`.
+
+    Order matters and is CMake's, not this file's: `find_program` searches
+    `CMAKE_PREFIX_PATH` BEFORE the ambient `PATH`, and the SDK's own
+    `cmake/zephyr/host-tools.cmake` is the only thing that puts a
+    `dtc`-bearing prefix on that list. A PATH-first probe would attribute the
+    reported version to the wrong binary on a host that has both -- the same
+    "which binary answered" defect tan-cli#123/#488 closed for `west`.
+
+    The SDK root comes from `_zephyr_sdk_detected_root()` -- the SAME
+    `ZEPHYR_SDK_INSTALL_DIR`-then-scan precedence `zephyrSdk` and `toolchain`
+    already trust, reused rather than re-rolled. One narrowing, stated rather
+    than glossed: an SDK reachable ONLY through CMake's user package registry
+    (`~/.cmake/packages/Zephyr-sdk/*`, which `west sdk install` writes and
+    `FindZephyr-sdk.cmake`'s CONFIG-mode lookup consults) and living outside
+    `$HOME` and `/opt` is not consulted here. That can only ever move a hosttools
+    `dtc` from the first arm to the third -- `pass` either way -- and never
+    manufacture the `warn`, which is the arm that would cost a customer
+    attention.
+
+    Never raises: `_zephyr_sdk_detected_root`, `on_path` and `probe` are all
+    non-raising by contract (see the module docstring), and the one direct
+    filesystem touch here catches `OSError` itself.
+    """
+    host_os, host_arch = _host_os_arch_tags()
+    found: str | None = None
+    origin = devicetree_lint.ORIGIN_ABSENT
+    sdk_dir = _zephyr_sdk_detected_root()
+    if sdk_dir is not None:
+        bin_dir = devicetree_lint.hosttools_bin_dir(sdk_dir, host_os, host_arch)
+        if bin_dir is not None:
+            candidate = bin_dir / ("dtc.exe" if os.name == "nt" else "dtc")
+            try:
+                present = candidate.is_file()
+            except OSError:
+                present = False
+            if present:
+                found, origin = str(candidate), devicetree_lint.ORIGIN_HOSTTOOLS
+    if found is None:
+        on_path_dtc = on_path("dtc")
+        if on_path_dtc is not None:
+            found, origin = on_path_dtc, devicetree_lint.ORIGIN_PATH
+    version = (
+        devicetree_lint.parse_dtc_version(probe([found, "--version"]))
+        if found is not None
+        else None
+    )
+    return devicetree_lint.DtcResolution(found, origin, version)
+
+
+def _probe_host_python(
+    floor: tuple[int, int], candidates: list | None = None
+) -> tuple[str, tuple[int, int], str] | None:
+    """First candidate that RUNS and clears `floor`; else the first that merely
+    ran, so the too-old message can name a real version instead of "did not
+    run". Mirrors `crate::util::probe_host_python`.
+
+    tan-cli#797: `candidate[0]` (`"py"`/`"python"`/`"python3"`) is resolved
+    through `tool_lookup.resolve_tool` and spawned as `executable=`, keeping
+    `candidate` itself -- and therefore `entry`'s display spelling -- bare. A
+    candidate that does not resolve is skipped outright, the same "no answer"
+    treatment `probe()` already gives every other way this can fail; it is
+    never handed to `subprocess` unresolved.
+
+    The returned 3-tuple carries the RESOLVED path as its third element
+    alongside the display spelling and version, so a caller that needs to
+    spawn this same interpreter again (`_posix_venv_capable`'s `ensurepip`
+    probe) threads the already-resolved path through as `executable=` instead
+    of re-deriving argv from the display spelling and handing THAT bare to
+    `subprocess` -- the resolve-then-spawn-something-else divergence
+    tan-cli#797 exists to close. `python_check` only reads the first two
+    elements; a caller wanting just those may slice `found[:2]`.
+    """
+    if candidates is None:
+        candidates = probe_all_host_pythons()
+    found = select_host_python(candidates, floor)
+    return None if found is None else (found.display, found.version, found.resolved)
+
+
+@dataclass(frozen=True)
+class ManifestLoad:
+    """The result of resolving `<sdk>/metadata/bootstrap.json`.
+
+    `is_real` is the provenance verdict as DATA, set exactly once, at the one
+    return that actually read and parsed a manifest -- never re-derived by a
+    caller sniffing `source`'s prose. `source` is still carried for display
+    (the message names WHICH file or fallback), but nothing downstream may
+    infer `is_real` from it: that used to be `source.startswith("facts from
+    alp-sdk")`, which silently flips the verdict the moment this docstring's
+    or `source`'s wording changes, with nothing to catch it.
+    """
+
+    facts: dict
+    source: str
+    error: str | None
+    is_real: bool
+    #: tan-cli#1066 review: what was unreadable inside a manifest that was
+    #: otherwise read FINE -- today only the `artifactProvenance` block. A
+    #: SECOND field rather than reusing `error`, because the two mean opposite
+    #: things to the caller: `error` says "this manifest was rejected and the
+    #: built-in fallback list is in play", which would be false here (the tool
+    #: list, the floor and the install commands were all read normally, and
+    #: `is_real` stays true). Both raise the same `bootstrapManifest` warn and
+    #: the same `doctor.bootstrap-manifest` issue -- they differ only in what
+    #: the line says, and saying the wrong one would send a customer hunting a
+    #: prerequisite list that is not actually stale.
+    provenance_error: str | None = None
+
+
+def _load_manifest(sdk_root: str | None) -> ManifestLoad:
+    """Resolve the prerequisites facts from `<sdk>/metadata/bootstrap.json`.
+
+    A missing or malformed manifest is a WARNING with documented fallbacks, not
+    a refusal: doctor's whole job is to run on a host where things are wrong,
+    and a doctor that cannot start because the thing it diagnoses is broken is
+    the failure mode it exists to prevent.
+    """
+    fallback = {
+        "posix": ["git", "cmake", "python3", "ninja"],
+        "windows": ["git", "cmake", "python", "ninja"],
+        "pythonMinVersion": f"{FALLBACK_PYTHON_FLOOR[0]}.{FALLBACK_PYTHON_FLOOR[1]}",
+        "install": {},
+    }
+    if sdk_root is None:
+        return ManifestLoad(
+            fallback,
+            "tan's built-in fallback list (no alp-sdk checkout resolved)",
+            None,
+            is_real=False,
+        )
+    path = Path(sdk_root) / "metadata" / "bootstrap.json"
+    text = _read_text(path)
+    if text is None:
+        return ManifestLoad(
+            fallback,
+            "tan's built-in fallback list",
+            f"could not read {path}",
+            is_real=False,
+        )
+    try:
+        facts = json.loads(text)
+    except ValueError as err:
+        return ManifestLoad(
+            fallback, "tan's built-in fallback list", f"{path} is not valid JSON: {err}", is_real=False
+        )
+    if not isinstance(facts, dict):
+        return ManifestLoad(
+            fallback, "tan's built-in fallback list", f"{path} is not a JSON object", is_real=False
+        )
+    # tan-cli#488 defect 3: `schemaVersion` read on its own FIRST, mirroring
+    # `tan.core.bootstrap.parse_bootstrap_manifest` -- the ONE other reader of
+    # this same file -- so the two commands agree about what a future,
+    # reshaped manifest means. Before this, `_load_manifest` accepted ANY
+    # `prerequisites` object regardless of `schemaVersion`, so an SDK whose
+    # manifest `tan bootstrap` refuses outright (a schema this build does not
+    # understand) still yielded `hostPrerequisites: pass`, zero tools probed,
+    # and no `bootstrapManifest` warning -- a clean bill of health for a
+    # manifest that was never actually read. `bool` excluded explicitly, same
+    # reason `parse_bootstrap_manifest` excludes it: `True == 1` in Python.
+    schema_version = facts.get("schemaVersion")
+    if not isinstance(schema_version, int) or isinstance(schema_version, bool):
+        return ManifestLoad(
+            fallback,
+            "tan's built-in fallback list",
+            f"{path} could not be read: missing `schemaVersion`",
+            is_real=False,
+        )
+    if schema_version != BOOTSTRAP_MANIFEST_SCHEMA_VERSION:
+        return ManifestLoad(
+            fallback,
+            "tan's built-in fallback list",
+            # tan-cli#488 defect 2: no trailing period -- this string is
+            # always read back through `f"... rejected: {loaded.error}. Falling
+            # back to ..."` (below), which supplies its own; a period here
+            # rendered "...outright.. Falling back to" (double stop).
+            f"{path} declares schemaVersion {schema_version}, but this `tan` "
+            f"supports only {BOOTSTRAP_MANIFEST_SCHEMA_VERSION}. Update `tan`, or "
+            f"pin an SDK whose metadata/bootstrap.json this version understands; "
+            f"`tan bootstrap` already refuses this manifest outright",
+            is_real=False,
+        )
+    prerequisites = facts.get("prerequisites")
+    if not isinstance(prerequisites, dict):
+        return ManifestLoad(
+            fallback,
+            "tan's built-in fallback list",
+            f"{path} has no `prerequisites` object",
+            is_real=False,
+        )
+    west = facts.get("west")
+    if isinstance(west, dict):
+        prerequisites = {**prerequisites, "_pipSpec": west.get("pipSpec")}
+    # tan-cli#606: `zephyr.pythonMinVersion` is a SEPARATE, Zephyr-scoped
+    # floor from `prerequisites.pythonMinVersion` above (alp-sdk#1078) -- not
+    # a duplicate of it. Injected onto the returned `prerequisites` dict the
+    # same way `_pipSpec` is, so `_zephyr_manifest_floor_from_facts` has one
+    # place to read it from without a second manifest parse.
+    zephyr = facts.get("zephyr")
+    if isinstance(zephyr, dict) and isinstance(zephyr.get("pythonMinVersion"), str):
+        prerequisites = {
+            **prerequisites,
+            "_zephyrPythonMinVersion": zephyr["pythonMinVersion"],
+        }
+    # tan-cli#1066: `artifactProvenance` is TOP-LEVEL in the manifest
+    # (alp-sdk#1574) while everything else this reader returns lives under
+    # `prerequisites` -- injected onto the returned dict the same way
+    # `_pipSpec` and `_zephyrPythonMinVersion` are, so `prerequisites_check`
+    # has one place to read it from and this file keeps its single parse.
+    # ALWAYS injected, even when absent/malformed: `parse_table` answers `{}`
+    # for both, and `{}` is the same "nothing reported" a tool with no entry
+    # gets -- so no caller has to branch on whether the key was there.
+    prerequisites = {
+        **prerequisites,
+        "_artifactProvenance": artifact_provenance.parse_table(
+            facts.get(artifact_provenance.BLOCK_KEY)
+        ),
+    }
+    return ManifestLoad(
+        prerequisites,
+        f"facts from alp-sdk {path}",
+        None,
+        is_real=True,
+        # Reported, never refused: a corrupt provenance block must not cost
+        # this customer their diagnosis (tan-cli#1066), and must not cost the
+        # NEXT one the ability to see that alp-sdk's generator regressed
+        # (#1066 review -- a silent degrade is byte-identical to a pre-v0.16.0
+        # SDK, so the producer bug is undetectable from here).
+        provenance_error=artifact_provenance.problems_in(facts),
+    )
+
+
+def _manifest_floor_from_facts(facts: dict) -> tuple[int, int]:
+    """The `pythonMinVersion` `facts` declares, or `FALLBACK_PYTHON_FLOOR` when
+    absent/unparseable -- shared by `_collect` and `resolve_manifest_python_floor`
+    so the two never parse the same field two different ways."""
+    return _parse_two(str(facts.get("pythonMinVersion") or "")) or FALLBACK_PYTHON_FLOOR
+
+
+def _zephyr_manifest_floor_from_facts(facts: dict) -> tuple[int, int] | None:
+    """The `zephyr.pythonMinVersion` `facts` declares (tan-cli#606), or `None`
+    when absent/unparseable/no manifest resolved at all -- callers fall back
+    to `ZEPHYR_PYTHON_FLOOR` in that case, same as before this field existed.
+    Unlike `_manifest_floor_from_facts`, `None` is a normal result, not a
+    degraded one: most manifests on disk today predate this key."""
+    raw = facts.get("_zephyrPythonMinVersion")
+    if not isinstance(raw, str):
+        return None
+    return _parse_two(raw)
+
+
+def resolve_manifest_python_floor(sdk_root: str | None) -> tuple[tuple[int, int], str]:
+    """`(floor, provenance)` for the SDK's OWN declared Python floor --
+    `<sdk>/metadata/bootstrap.json`'s `prerequisites.pythonMinVersion` -- for
+    callers gating a SPAWNED SDK interpreter (`generate`/`model`) rather than a
+    Zephyr build, so they want this floor, not `_collect`'s Zephyr-composed
+    effective one. The ONE reader: before this, `generate_cmd` and `model_cmd`
+    each carried their own hardcoded `MIN_PYTHON = (3, 10)`, a floor that could
+    drift from the manifest's -- and from each other's -- without either
+    command noticing.
+    """
+    loaded = _load_manifest(sdk_root)
+    return _manifest_floor_from_facts(loaded.facts), loaded.source
+
+
+#: Generous on purpose: a real install can pull a package over the network,
+#: unlike every OTHER timeout in this file (`PROBE_TIMEOUT_S`), which only
+#: ever waits on a local `--version` banner. `ponytail`: one fixed ceiling,
+#: no live progress WITHIN a single install -- `run_fix`'s `on_check` streams
+#: a Check the MOMENT one tool's own outcome is known, which closes the blank
+#: window BETWEEN tools, not the window a single slow install itself still
+#: opens; raise this ceiling, or stream that install's own output, if one
+#: exceeds it before this is revisited.
+FIX_INSTALL_TIMEOUT_S = 300
+
+
+def fix_needs_sudo_check(tool: str, command: str) -> Check:
+    """`doctor.fix-needs-sudo` -- ADR 0021's Tier-B refusal (tan-cli#91,
+    MAINTAINER DECISION): tan never spawns the `sudo` PROGRAM on the
+    customer's behalf.
+
+    Under `--format json` this process's stdio is captured end to end, so a
+    `sudo` password prompt has nowhere to go -- it would hang forever rather
+    than fail loudly, which is a worse outcome than refusing up front. REFUSE
+    AND PRINT: name the exact command, verbatim, so it can be pasted into a
+    real terminal, and stop there. `run_fix` below is the only caller, and
+    only reaches this branch for a command whose first word IS literally
+    `sudo` -- the manifest's own POSIX `prerequisites.install` commands are
+    the one place that word appears in this codebase at all; Windows
+    (`winget`, user-scope) and macOS (`brew`) never need it.
+
+    tan-cli#650: `run_fix` only reaches THIS branch when the caller is NOT
+    already root -- a root caller has nothing left to elevate to, and
+    `run_fix` strips the literal `sudo ` word and runs the manifest's own
+    remaining command directly instead of calling this function at all. That
+    still never spawns the `sudo` program (the MAINTAINER DECISION above is
+    about the program, not the elevation it grants), so a root caller getting
+    real remediation here does not contradict it -- it recognises that
+    "needs elevation" is already satisfied when the process asking is root.
+    """
+    return Check(
+        f"fix:{tool}",
+        "warn",
+        f'`--fix` will not run `{command}` for {tool}: it needs elevation '
+        f'("sudo"), and tan never spawns sudo itself. Run it yourself, then '
+        f"re-run `tan doctor`.",
+        command,
+        code="doctor.fix-needs-sudo",
+        scope="host",
+    )
+
+
+def fix_installed_check(
+    tool: str, command: str, *, elevation_skipped: bool = False
+) -> Check:
+    """`doctor.fix-installed` -- `--fix` ran a manifest install command that
+    needed no elevation (ADR 0021 Tier A), and the child process exited 0.
+
+    Deliberately NOT a claim that `{tool}` is now on PATH: this process
+    already read its own PATH at start-up (tan-cli#91), so an install that
+    lands after that moment is invisible to it -- there is no same-process
+    re-check to perform, honestly or otherwise. "Installed; reopen your
+    shell" is the whole truth this check can tell; `hostPrerequisites`
+    above still reports `{tool}` missing in THIS report, which is correct
+    for THIS report.
+
+    `elevation_skipped` (tan-cli#650): set when `command` is the manifest's
+    own line with its literal `sudo ` prefix already removed by `run_fix`,
+    because the caller was ALREADY root -- there was no elevation left to
+    acquire. Said explicitly so this reads as the root-aware Tier-B path it
+    is, not as an ordinary Tier-A ("this tool never needed elevation at
+    all") outcome; the two are true for different reasons and a reader
+    deciding whether to trust `--fix` on their next root container should be
+    able to tell them apart.
+    """
+    lede = (
+        f"`--fix` ran `{command}` for {tool} (already running as root, so "
+        f"the manifest's `sudo` was not needed and was not run)."
+        if elevation_skipped
+        else f"`--fix` ran `{command}` for {tool}."
+    )
+    return Check(
+        f"fix:{tool}",
+        "warn",
+        f"{lede} tan cannot see a PATH change made after it started -- open "
+        f"a new shell, then re-run `tan doctor` there to confirm.",
+        code="doctor.fix-installed",
+        scope="host",
+    )
+
+
+def fix_spawn_failed_check(tool: str, command: str, err: Exception) -> Check:
+    """`doctor.fix-spawn-failed` -- `--fix` resolved `{tool}`'s install
+    command on PATH (`on_path` already succeeded) but starting it raised
+    (`OSError`/`ValueError`/`subprocess.SubprocessError` other than a
+    timeout). Distinct from silence: without this, a customer watching
+    `--fix` do nothing cannot tell "the OS refused to start it" from "tan
+    never tried"."""
+    return Check(
+        f"fix:{tool}",
+        "warn",
+        f"`--fix` could not start `{command}` for {tool}: {err}. Run it "
+        f"yourself, then re-run `tan doctor`.",
+        command,
+        code="doctor.fix-spawn-failed",
+        scope="host",
+    )
+
+
+def fix_failed_check(tool: str, command: str, returncode: int) -> Check:
+    """`doctor.fix-failed` -- `--fix` ran `{tool}`'s install command and the
+    child exited non-zero. `hostPrerequisites` above still reports `{tool}`
+    missing in THIS report (same no-same-process-recheck honesty as
+    `fix_installed_check`) -- this Check is the only place a customer learns
+    the install itself failed, rather than merely "still missing"."""
+    return Check(
+        f"fix:{tool}",
+        "warn",
+        f"`--fix` ran `{command}` for {tool}; it exited {returncode}. Run it "
+        f"yourself to see the full output, then re-run `tan doctor`.",
+        command,
+        code="doctor.fix-failed",
+        scope="host",
+    )
+
+
+def fix_timed_out_check(tool: str, command: str) -> Check:
+    """`doctor.fix-timed-out` -- `{tool}`'s install command did not finish
+    inside `FIX_INSTALL_TIMEOUT_S` (300s) and was killed. Without this, a
+    hang here reads as up to 20 minutes of silent terminal: text-mode output
+    only prints after the WHOLE report completes."""
+    return Check(
+        f"fix:{tool}",
+        "warn",
+        f"`--fix` killed `{command}` for {tool} after {FIX_INSTALL_TIMEOUT_S}s "
+        f"with no result. Run it yourself, then re-run `tan doctor`.",
+        command,
+        code="doctor.fix-timed-out",
+        scope="host",
+    )
+
+
+#: Per-installer remedy for `fix_installer_not_found_check`, keyed by the first
+#: word of the command actually resolved and spawned -- for a `sudo`-prefixed
+#: manifest line that is the word AFTER `sudo` (tan-cli#650 strips it for an
+#: already-root caller before this table is ever consulted; a non-root caller
+#: is refused by `fix_needs_sudo_check` long before this point, so `sudo`
+#: itself never appears here as a key). Two named entries: `metadata/
+#: bootstrap.json`'s `prerequisites.install` produces `brew` on macOS and
+#: `winget` on Windows (see `_fallback_install_commands` in `tan.core.
+#: bootstrap`, which is byte-pinned to the manifest). Anything else --
+#: including `apt-get`, on the rare root-container host missing it -- gets
+#: the generic remedy below: a manifest is free to name a package manager
+#: this table has never heard of, and "not found" with no advice is the
+#: exact silence tan-cli#360 is about.
+INSTALLER_REMEDIES = {
+    "brew": (
+        "Homebrew is not installed -- install it from https://brew.sh, then "
+        "re-run `tan doctor --fix`."
+    ),
+    "winget": (
+        'winget comes from the App Installer package -- install "App '
+        'Installer" from the Microsoft Store (Windows 10 1809 or newer), open '
+        "a new shell so PATH picks it up, then re-run `tan doctor --fix`."
+    ),
+}
+
+
+def fix_installer_not_found_check(installer: str, tools: list[str]) -> Check:
+    """`doctor.fix-installer-not-found` -- tan-cli#360: `--fix` could not
+    resolve the program the manifest's install command starts with, so it ran
+    NO repair for the tools that command covers.
+
+    This used to be a bare `continue` in `run_fix` -- the one outcome that
+    emitted no Check at all, in a function whose whole stated invariant is
+    that every entry is either run or refused and every outcome is reported.
+    It is also the single most likely outcome on the hosts `--fix` exists
+    for: the manifest installs with `brew` on macOS and `winget` on Windows,
+    so a fresh Mac without Homebrew, or a Windows image with no usable
+    winget, reported tools missing, ACCEPTED `--fix`, and then printed
+    exactly the same report back with no `fix:*` line anywhere. The
+    least-equipped host got the least diagnostic behaviour, and could not
+    tell "nothing needed fixing" from "tan never found the installer to try
+    with".
+
+    ONE Check per installer, not per tool: a fresh Mac is missing all six
+    manifest prerequisites at once and every one of them says `brew`, so
+    per-tool would print the same "install Homebrew" paragraph six times over
+    -- six restatements of one fact, in a report a customer is reading to
+    find out what is actually wrong. `tools` therefore carries every tool
+    this one absence blocked, and `run_fix` groups them.
+
+    Named `fix:{installer}` rather than `fix:{tool}` for the same reason --
+    the subject of this verdict is the installer, and one name per absent
+    installer is what keeps the grouping legible in the text report. No
+    `fix` field, and no "see `hostPrerequisites` above" either (tan-cli#760
+    review round 3, MINOR): the per-tool commands are not runnable until the
+    installer exists, and this Check fires precisely when that installer is
+    unconfirmed -- the exact condition under which `hostPrerequisites.
+    missing[].command` is `null` too, so pointing at it would be false on
+    the one host this Check describes.
+    """
+    named = ", ".join(tools)
+    many = len(tools) > 1
+    remedy = INSTALLER_REMEDIES.get(installer) or (
+        f"Install `{installer}`, then re-run `tan doctor --fix`."
+    )
+    return Check(
+        f"fix:{installer}",
+        "warn",
+        f"`--fix` ran no repair for {named}: the manifest installs "
+        f"{'them' if many else 'it'} with `{installer}`, which is not on "
+        f"PATH. {remedy} Or install {'those tools' if many else named} with a "
+        f"package manager this host already has.",
+        code="doctor.fix-installer-not-found",
+        scope="host",
+    )
+
+
+def _running_as_root() -> bool:
+    """tan-cli#650: whether THIS process's effective UID is 0 -- POSIX only.
+
+    `os.geteuid` does not exist on Windows, where no manifest install
+    command ever carries a `sudo` prefix in the first place (`winget` is
+    user-scope) -- see `fix_needs_sudo_check`'s docstring -- so this is only
+    ever consulted from the one platform whose manifest can raise the
+    question at all, and `getattr` guards the call rather than an `if
+    sys.platform` branch so this stays correct if that ever changes.
+
+    The caller this exists for: a root container (`docker run`, most CI base
+    images, a fresh cloud VM before its first `useradd`) running `tan doctor
+    --build --fix`. There is no elevation left to acquire there, so
+    `run_fix` refusing every `sudo`-prefixed manifest command unconditionally
+    -- which it did before this -- was not caution, it was a false negative:
+    measured live via a real `geteuid() == 0` process (`unshare --user
+    --map-root-user`, a genuine root user namespace, since this box has no
+    passwordless real root), `run_fix` still emitted `doctor.fix-needs-sudo`
+    and ran nothing.
+    """
+    geteuid = getattr(os, "geteuid", None)
+    return geteuid is not None and geteuid() == 0
+
+
+def run_fix(
+    missing: list[dict[str, str | int | None]],
+    on_check: Callable[[Check], None] | None = None,
+) -> list[Check]:
+    """`--fix`'s ADR 0021 executor (tan-cli#91): for each tool
+    `hostPrerequisites` already reported missing, either run its manifest
+    install command (no elevation needed -- Tier A) or refuse and name it
+    (needs `sudo` -- Tier B), never both, never neither. `missing` is that
+    check's OWN structured field -- but `Check.fix_missing`, NOT `Check.
+    missing` (tan-cli#760 review round 3, MINOR: this used to say `Check.
+    missing`, which stopped being true the moment tan-cli#760 split the two).
+    `fix_missing` is the RAW twin: `missing` (`data.missingPrerequisites`,
+    the envelope) nulls a command whose own installer this host cannot
+    confirm, and feeding THAT to `run_fix` would silently disable the Tier B
+    diagnosis below the moment a tool's command is unconfirmed -- the exact
+    regression tan-cli#760's own review caught. Never a second,
+    independently recomputed tool/command list either way, so this can only
+    ever act on exactly what `prerequisites_check` already computed.
+
+    A tool with `command=None` (the manifest names no install command for
+    it) is skipped outright: nothing to run, nothing to refuse, and the
+    existing `hostPrerequisites` Fail already carries the honest "install it
+    yourself" advice for that case.
+
+    Every outcome becomes a `Check` -- `fix_needs_sudo_check`/
+    `fix_installed_check` on the two "acted, and it's fine" paths, (as of
+    the tan-cli#91 follow-up below) `fix_spawn_failed_check`/`fix_failed_check`/
+    `fix_timed_out_check` on the three "acted, and it's NOT fine" paths, and
+    (tan-cli#360) `fix_installer_not_found_check` on the "could not act at
+    all" one -- never a bare side effect. A customer who typed `--fix` and
+    got the SAME report back used to have no way to tell "nothing needed
+    fixing" from "tan tried and silently gave up": a spawn error, a non-zero
+    exit, a `FIX_INSTALL_TIMEOUT_S` (300s) timeout, or an install command
+    whose own program is not on PATH each used to `continue` with no trace at
+    all. `hostPrerequisites`'s own Fail still names the tool and its command
+    either way; these Checks add the ONE fact it structurally cannot carry --
+    what `--fix` itself did about it.
+
+    `on_check` -- same shape, same job as `_collect`'s parameter of that
+    name: fired the MOMENT one tool's own outcome is known, not after every
+    tool has been tried. Before this, `--fix`'s checks streamed only once
+    `run_fix` returned IN FULL -- the LARGEST blank-terminal window in the
+    whole command, `FIX_INSTALL_TIMEOUT_S` (300s) times up to 4 tools,
+    against `PROBE_TIMEOUT_S` (15s) for the probes `_collect` already
+    streamed. `doctor()` passes it the SAME `_print_check` it gives
+    `_collect`, so a `--fix` outcome prints through the identical guarded
+    `_print_stream_lines` path (see its docstring) as every other check in
+    this report.
+
+    Only ever called from `doctor()`'s `--fix` branch, itself gated on
+    `can_prompt` (`tan.core.consent`) -- the one place in this module that
+    mutates the host rather than merely observing it, so it is confined
+    exactly there, never folded into `_collect` (pure probes, see the module
+    docstring).
+    """
+    results: list[Check] = []
+
+    def _add(check: Check) -> None:
+        # Mirrors `_collect`'s own `_add` closure exactly -- append, then
+        # stream, so a caller with no `on_check` (every direct unit-test
+        # caller of this function) sees no behaviour change at all.
+        results.append(check)
+        if on_check is not None:
+            on_check(check)
+
+    # installer -> every tool whose install command starts with it and that
+    # therefore went unrepaired (tan-cli#360). Insertion-ordered, so the
+    # grouped Checks appended below come out in `missing` order rather than
+    # an arbitrary one.
+    unresolved: dict[str, list[str]] = {}
+    for entry in missing:
+        tool = entry.get("tool")
+        command = entry.get("command")
+        if not tool or not command:
+            continue
+        # tan-cli#650: `effective_command` is what actually gets resolved and
+        # spawned below; `command` (the manifest's own, untouched line) is
+        # kept only for `fix_needs_sudo_check`'s refusal message, which must
+        # name the exact line a human would paste into a real terminal.
+        effective_command = command
+        elevation_skipped = False
+        if command.strip().startswith("sudo "):
+            if not _running_as_root():
+                _add(fix_needs_sudo_check(tool, command))
+                continue
+            # Already root: there is nothing left to elevate to, and this
+            # process still never spawns the `sudo` PROGRAM (see
+            # `fix_needs_sudo_check`'s docstring) -- it strips the literal
+            # `sudo ` word and runs the manifest's OWN remaining command
+            # directly, the same way every non-elevated entry already does.
+            effective_command = command.strip()[len("sudo ") :].lstrip()
+            elevation_skipped = True
+        argv = shlex.split(effective_command)
+        if not argv:
+            # The one deliberately silent skip left (tan-cli#360 reviewed the
+            # rest): an all-whitespace install command names no program to
+            # report as absent, so there is nothing this could say beyond what
+            # `hostPrerequisites`'s own Fail already says about the tool. A
+            # manifest defect, not a host one.
+            continue
+        # `on_path`, never bare `subprocess.run([name, ...])`: the same
+        # PATH-only, no-cwd-insertion resolver every other spawn in this
+        # module uses (see `on_path`'s own docstring) -- a project-local
+        # binary happening to share the tool's name must not be what `--fix`
+        # runs with elevated-sounding trust.
+        resolved_exe = on_path(argv[0])
+        if resolved_exe is None:
+            # tan-cli#360: collected, not silently dropped. Grouped by
+            # installer because one absent `brew` blocks every macOS
+            # prerequisite at once -- see `fix_installer_not_found_check`.
+            unresolved.setdefault(argv[0], []).append(tool)
+            continue
+        argv[0] = resolved_exe
+        try:
+            result = subprocess.run(
+                argv,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                stdin=subprocess.DEVNULL,
+                timeout=FIX_INSTALL_TIMEOUT_S,
+                env=spawn_env(),
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            _add(fix_timed_out_check(tool, effective_command))
+            continue
+        except (OSError, ValueError, subprocess.SubprocessError) as err:
+            _add(fix_spawn_failed_check(tool, effective_command, err))
+            continue
+        if result.returncode == 0:
+            _add(
+                fix_installed_check(
+                    tool, effective_command, elevation_skipped=elevation_skipped
+                )
+            )
+        else:
+            _add(fix_failed_check(tool, effective_command, result.returncode))
+    for installer, tools in unresolved.items():
+        _add(fix_installer_not_found_check(installer, tools))
+    return results
+
+
+def fix_suppressed_issue(*, non_interactive: bool, ci: bool, json_mode: bool) -> Issue:
+    """`doctor.fix-suppressed` -- tan-cli#91 P1, measured against the oracle:
+    `tan doctor --fix --format json` on an unhealthy host used to be a
+    byte-for-byte silent no-op vs. plain `tan doctor` -- no issue, no note,
+    exit code unchanged -- indistinguishable from a `--fix` that genuinely
+    found nothing to do. The oracle's own equivalent refuses outright
+    (`cli.parse-error`, exit 2); this port instead reports HONESTLY: `--fix`
+    was requested, the `can_prompt` consent gate (`tan.core.consent`) refused
+    it, and here is which of its conditions actually tripped -- not just that
+    nothing happened.
+
+    Only ever called from `doctor()`, and only when `fix` is set and
+    `can_prompt` returned `False` for these same three flags -- never the
+    other way around, so this can only ever explain a REAL suppression.
+
+    The `isatty()` pair is read ONLY when `not json_mode`, mirroring
+    `can_prompt`'s own short-circuit order (`... and not json_mode and
+    sys.stdin.isatty() and sys.stderr.isatty()`) rather than a coincidence:
+    under `--format json`, `tan.cli.main` tees `sys.stderr` through
+    `_TeeStderr`, which has no `isatty()` at all -- reading it unconditionally
+    here crashes this exact suppressed-fix report with
+    `AttributeError: '_TeeStderr' object has no attribute 'isatty'` (measured
+    against a real `tan doctor --fix --format json --ci` run). `json_mode`
+    is already a complete, accurate reason on its own; there is nothing the
+    tty state could add under it.
+
+    tan-cli#488 defect 6: `sys.stdin` is guarded with `is not None` before
+    `.isatty()` -- `sys.stdin` itself, not just `sys.stderr`, can be `None`
+    (a GUI-launched/`pythonw`-style process, or any host that runs tan with
+    its standard handles detached), and a bare `sys.stdin.isatty()` there
+    raises `AttributeError: 'NoneType' object has no attribute 'isatty'` for
+    the same reason the `_TeeStderr` case above already gets its own guard.
+
+    tan-cli#488 round 3: this was, for one round, the ONLY place that guard
+    existed -- `can_prompt` itself (`tan.core.consent`) still called the bare
+    `sys.stdin.isatty()`. Since `doctor()` calls `can_prompt` BEFORE it ever
+    calls this function (`fix_allowed = fix and can_prompt(...)`, evaluated
+    ahead of the `fix_suppressed_issue(...)` call site below it), a `None`
+    `sys.stdin` crashed there first, and this function's own guard never ran
+    at all -- caught only by `doctor()`'s outer `except Exception`, which
+    discarded the whole diagnosis. `can_prompt` now carries the identical
+    guard (the fix belongs there, once, not duplicated per caller -- see its
+    own docstring); the copy here stays only because this function explains
+    each tripped condition individually, not merely whether the aggregate
+    gate passed.
+
+    tan-cli#488 round 5: `sys.stderr`, the NEXT operand of this same `and`
+    chain, was left unguarded through rounds 3 and 4 -- `sys.stderr` can be
+    `None` independently of `sys.stdin` (each handle is detached on its own
+    by whatever spawned the process), so a host with a live, non-tty stdin
+    and a detached stderr still crashed here with the identical
+    `AttributeError`, one operand later. `can_prompt` now guards both; this
+    copy must match it exactly or the two diverge on the very host this
+    function exists to explain.
+
+    tan-cli#488 round 6: `is not None` still was not the whole guard -- it
+    stops a detached (`None`) handle from crashing `.isatty()`, but not a
+    handle that EXISTS and simply has no `.isatty()` method, exactly the
+    shape `sys.stderr` takes under `--format json` (`tan.cli.main`'s
+    `_TeeStderr`, which implements `write`/`flush`/`getvalue` only). The
+    `not json_mode` guard in front of this whole condition means this
+    particular copy was never observed to reach that shape in practice --
+    but `tan.commands.build_cmd._dispatch` hand-rolled the identical
+    `is not None and .isatty()` pair with no `json_mode` operand ahead of
+    it, and that one DID crash on a real `tan run --format json`
+    (`AttributeError: '_TeeStderr' object has no attribute 'isatty'`,
+    measured), one caller away from the same fate here. Both operands now
+    route through `tan.env.stdin_is_tty`/`stderr_is_tty` -- the one shared
+    probe (tan-cli#288) already used by `use_color`/`wrap_width` above and
+    now by `can_prompt` too -- instead of a fourth hand-rolled copy of a
+    guard three of the previous four rounds already got wrong once.
+    """
+    reasons = []
+    if json_mode:
+        reasons.append("`--format json` (no terminal to prompt on)")
+    if ci:
+        reasons.append("`--ci`")
+    if non_interactive:
+        reasons.append("`--non-interactive`")
+    if not json_mode and not (stdin_is_tty() and stderr_is_tty()):
+        reasons.append("no interactive terminal (stdin/stderr not a tty -- piped, redirected, or CI)")
+    return Issue(
+        "doctor.fix-suppressed",
+        "warning",
+        "`--fix` was requested but not run: " + "; ".join(reasons) + ". Re-run "
+        "`tan doctor --fix` from a real, interactive terminal, without "
+        "--ci/--non-interactive/--format json, to allow it.",
+    )
+
+
+@dataclass(frozen=True)
+class _PrerequisitesEnvironment:
+    """Everything `bootstrapManifest`/`hostPrerequisites` (and `_collect`'s
+    OWN `hostPython`/`pythonFloor`/`west` checks, which read the SAME
+    manifest load and Python probe) need, computed exactly once regardless of
+    which caller asked -- see `_resolve_prerequisites_environment` (tan-cli#441).
+    """
+
+    bootstrap_manifest_check: Check | None
+    prerequisites_check: Check
+    facts: dict
+    manifest_floor: tuple[int, int]
+    effective_floor: tuple[int, int]
+    effective_source: str
+    python_found: tuple[str, tuple[int, int], str] | None
+    manifest_is_real: bool
+    #: Every interpreter the ONE probe saw (tan-cli#1317) -- `hostPython`'s
+    #: build-readiness verdict reads this instead of probing a second time.
+    host_pythons: tuple = ()
+
+
+def _resolve_prerequisites_environment(
+    sdk_root: str | None, workspace_path: Path | None
+) -> _PrerequisitesEnvironment:
+    """The manifest load through `hostPrerequisites` -- moved verbatim out of
+    `_collect` (tan-cli#441) so `host_environment_checks` (support-bundle's
+    seam onto exactly these two checks; see its own docstring) and `_collect`
+    (`tan doctor`'s full checklist, which ALSO needs `hostPython`/
+    `pythonFloor`/`west`'s `facts.get("_pipSpec")` off the SAME manifest load
+    and the SAME Python probe) build `bootstrapManifest`/`hostPrerequisites`
+    from ONE copy of this logic and pay for the manifest read + the
+    `_probe_host_python` subprocess spawn exactly once per caller, instead of
+    a second copy drifting the moment either check changes.
+
+    `workspace_path` is a parameter, not resolved here, so a caller that
+    already has one (`_collect`, from its own earlier `west_workspace_dir`
+    call) never pays for a second walk -- `host_environment_checks` below
+    resolves its own before calling this.
+    """
+    loaded = _load_manifest(sdk_root)
+    facts, source = loaded.facts, loaded.source
+    bootstrap_manifest_check: Check | None = None
+    if loaded.error is not None:
+        bootstrap_manifest_check = Check(
+            "bootstrapManifest",
+            "warn",
+            f"metadata/bootstrap.json rejected: {loaded.error}. Falling back to "
+            f"tan's built-in prerequisite list, which may not match this SDK.",
+            "Update `tan` or pin an SDK whose metadata/bootstrap.json this "
+            "version understands; `tan bootstrap` will refuse outright until then.",
+            scope="project",
+        )
+    elif loaded.provenance_error is not None:
+        # tan-cli#1066 review. SAME check name and SAME issue code as the
+        # rejected-manifest arm above -- a consumer keying on
+        # `doctor.bootstrap-manifest` sees both -- but its own wording, because
+        # this manifest was NOT rejected: the tool list, the floor and the
+        # install commands were all read normally and `is_real` is true, so
+        # borrowing the "falling back to tan's built-in prerequisite list"
+        # sentence would send the reader hunting a staleness that does not
+        # exist. `warn`, never `fail`: the exit code and every reported entry
+        # are byte-identical to a run with no provenance at all (the four keys
+        # are still there, still `null`) -- what changes is that the failure is
+        # now SAYABLE. `elif`: a manifest that was rejected outright never had
+        # its provenance parsed in the first place, and the bigger fact wins.
+        bootstrap_manifest_check = Check(
+            "bootstrapManifest",
+            "warn",
+            f"metadata/bootstrap.json was read, but its artifactProvenance "
+            f"block is not readable: {loaded.provenance_error}. Any affected "
+            f"missingPrerequisites[] entries report tier/licence/sourceUrl/"
+            f"sizeBytes as null; the prerequisite list itself is unaffected.",
+            "Report this against alp-sdk -- its metadata/bootstrap.json "
+            "generator produced the block, and `tan` needs no change. Nothing "
+            "else in this report is affected.",
+            scope="project",
+        )
+
+    manifest_floor = _manifest_floor_from_facts(facts)
+    # tan-cli#301 (second half): read the SAME resolved workspace `zephyrWorkspace`
+    # reports above (`workspace_path`, from the shared `west_workspace_dir`) --
+    # NOT a second, independent `$ZEPHYR_BASE` read. A stale exported
+    # `$ZEPHYR_BASE` is common (Zephyr's own docs, and this command's own `tan
+    # bootstrap` next-steps block, both tell a customer to export it), and
+    # reading it here regardless of the resolved workspace is how one report
+    # ended up citing two different Zephyrs. `$ZEPHYR_BASE` is consulted only as
+    # `zephyr_python_floor`'s fallback, when no workspace resolved at all --
+    # mirroring #290's fix for `zephyrWorkspace` itself.
+    zephyr_source_base = (
+        str(workspace_path / "zephyr")
+        if workspace_path is not None
+        else os.environ.get("ZEPHYR_BASE")
+    )
+    # tan-cli#606: when no workspace resolves, prefer alp-sdk's OWN declared
+    # `zephyr.pythonMinVersion` over `ZEPHYR_PYTHON_FLOOR` -- same `facts`
+    # dict `manifest_floor` above already reads, so this is not a second
+    # manifest parse.
+    zephyr_manifest_floor = _zephyr_manifest_floor_from_facts(facts)
+    # tan tan-cli#1317: the ONE composition (`tan.core.python_floor`), shared
+    # with `tan build`'s interpreter pick.
+    effective_floor, effective_source = effective_python_floor(
+        manifest_floor, zephyr_source_base, zephyr_manifest_floor
+    )
+
+    host_pythons = probe_all_host_pythons()
+    python_found = _probe_host_python(effective_floor, host_pythons)
+
+    # tan-cli#488 defect 2: keyed on the HOST, not a `windows`/`posix` bool.
+    # `facts.get(...)` used to read straight off `"windows" if os.name == "nt"
+    # else "posix"`, which has no `macos` arm at all -- so a stock Mac (no
+    # `wget`, no standalone `xz`, both of which joined `prerequisites.posix`
+    # at alp-sdk v0.14.0) got handed the POSIX list wholesale and reported
+    # `hostPrerequisites: fail` on a host `tan bootstrap` accepts. Mirrors
+    # `tan.core.bootstrap.BootstrapFacts.prerequisites`'s own host-keyed read
+    # exactly, including its fallback: an EMPTY/absent `prerequisites.macos`
+    # means the manifest declared none (every SDK before v0.14.0), and macOS
+    # then reads `posix` exactly as it always did -- not a guess, the actual
+    # pre-v0.14.0 behaviour.
+    is_macos = sys.platform == "darwin"
+    required = facts.get("windows" if os.name == "nt" else ("macos" if is_macos else "posix"))
+    if is_macos and not (isinstance(required, list) and required):
+        required = facts.get("posix")
+    if not isinstance(required, list):
+        required = []
+    required = [t for t in required if isinstance(t, str)]
+    install = facts.get("install")
+    platform_key = "windows" if os.name == "nt" else ("macos" if sys.platform == "darwin" else "linux")
+    if platform_key == "linux":
+        # `install["linux"]` is package-manager-keyed, not tool-keyed like
+        # `macos`/`windows` (alp-sdk#1464 / tan-cli#760's second half) --
+        # `facts` is the RAW parsed manifest dict (`_load_manifest`), a
+        # separate reader from `tan.core.bootstrap.parse_bootstrap_manifest`,
+        # so it needs the SAME normalize/select reconciliation that reader
+        # applies, not a flat `.get(platform_key)` (which would silently
+        # return `{}` for every Linux tool, apt included).
+        linux_pm = detect_linux_pm(lambda binary: on_path(binary) is not None)
+        per_tool = select_linux_install(
+            normalize_linux_install(install.get("linux") if isinstance(install, dict) else None),
+            linux_pm,
+        )
+    else:
+        per_tool = install.get(platform_key) if isinstance(install, dict) else None
+        if not isinstance(per_tool, dict):
+            per_tool = {}
+    # RAW -- `prerequisites_check` below does its OWN tan-cli#760 PATH
+    # confirmation (`available=`) to build the customer-facing `missing`
+    # field; this dict stays unguarded because it is also the source of
+    # `fix_missing`, `--fix`'s (`run_fix`'s) own input -- see
+    # `prerequisites_check`'s docstring and tan-cli#760 review MAJOR 1 for
+    # why those two must NOT be the same value.
+    resolved_install = {k: v for k, v in per_tool.items() if isinstance(v, str)}
+    missing_tools = [tool for tool in required if on_path(tool) is None]
+    # tan-cli#294 finding 3: reintroduces tan-cli#161. Only reachable once the
+    # tool list itself is clean AND a Python actually ran -- mirrors
+    # `check_prerequisites`' own order (`crates/tan-cli/src/commands/
+    # bootstrap/steps.rs:296-298`): presence first, `ensurepip` only after.
+    venv_refusal = None
+    if (
+        sys.platform.startswith("linux")
+        and not missing_tools
+        and python_found is not None
+        and not _posix_venv_capable(python_found[0].split(), executable=python_found[2])
+    ):
+        venv_refusal = posix_venv_unusable()
+    built_prerequisites_check = prerequisites_check(
+        required,
+        missing_tools,
+        resolved_install,
+        source,
+        venv_refusal,
+        # tan-cli#760: confirmed -- not merely present, not GUESSED --
+        # against THIS host's real PATH walk (`on_path`, already used
+        # above for the tool-presence probe itself).
+        available=lambda binary: on_path(binary) is not None,
+        # tan-cli#1066. `facts` is the manifest `_load_manifest` already
+        # parsed and already resolved the SDK root for -- the join happens
+        # in the ONE process that holds both halves, which is the whole
+        # reason this lives in tan and not in the consumer.
+        provenance=facts.get("_artifactProvenance"),
+    )
+
+    return _PrerequisitesEnvironment(
+        bootstrap_manifest_check=bootstrap_manifest_check,
+        prerequisites_check=built_prerequisites_check,
+        facts=facts,
+        manifest_floor=manifest_floor,
+        effective_floor=effective_floor,
+        effective_source=effective_source,
+        python_found=python_found,
+        manifest_is_real=loaded.is_real,
+        host_pythons=tuple(host_pythons),
+    )
+
+
+def host_environment_checks(sdk_root: str | None, workspace_root: str = ".") -> list[Check]:
+    """The public/internal seam `support-bundle` harvests instead of running
+    `_collect`'s whole build/flash-readiness checklist (tan-cli#441).
+
+    Exactly the five HOST-only checks `_HOST_CHECK_ORDER`
+    (`support_bundle_cmd.py`) names -- `zephyrSdkAvailableForHost`,
+    `longPaths` (Windows only), `homePath`, `bootstrapManifest` (only on a
+    rejected manifest), `hostPrerequisites` -- none of which need a resolved
+    board.yaml, a spawned `west`/JLink/SETOOLS probe, or git provenance. Every
+    one of them is built by the SAME functions `_collect` calls
+    (`zephyr_sdk_host_check`/`long_paths_check`/`home_path_check` directly,
+    `bootstrapManifest`/`hostPrerequisites` via the shared
+    `_resolve_prerequisites_environment`) -- this is a second CALLER, not a
+    second COPY, so a change to any of the five reaches both `tan doctor` and
+    `tan support-bundle` from one place.
+
+    Returned unordered by name (construction order here, not
+    `_HOST_CHECK_ORDER`) -- `support_bundle_cmd._host_checks_from_doctor`
+    already re-indexes by `.name` before use, exactly as it did when it
+    harvested from `_collect`'s much longer list.
+    """
+    workspace_path = west_workspace_dir(
+        workspace_root, Path(sdk_root) if sdk_root is not None else None
+    )
+    host_os, host_arch = _host_os_arch_tags()
+    checks = [zephyr_sdk_host_check(host_os, host_arch)]
+    if os.name == "nt":
+        checks.append(
+            long_paths_check(_long_paths_enabled(), _git_core_longpaths(_resolve_git_executable()))
+        )
+    checks.append(home_path_check(os.environ.get("USERPROFILE" if os.name == "nt" else "HOME")))
+
+    prereq_env = _resolve_prerequisites_environment(sdk_root, workspace_path)
+    if prereq_env.bootstrap_manifest_check is not None:
+        checks.append(prereq_env.bootstrap_manifest_check)
+    checks.append(prereq_env.prerequisites_check)
+    return checks
+
+
+def _collect(
+    sdk_root: str | None,
+    build: bool = False,
+    board_yaml: str | None = None,
+    project_scope: str | None = None,
+    workspace_root: str = ".",
+    sdk_tier: str | None = None,
+    broken_global_default: str | None = None,
+    on_check: Callable[[Check], None] | None = None,
+) -> list[Check]:
+    """Every probe, in report order. `probe`/`on_path`/`_read_text` are the
+    three ways THIS function's own body touches the outside world, and none
+    of them can raise (see the module docstring).
+
+    `on_check`, when given, is a FOURTH path out -- `_collect` does not
+    control what it does, only that it fires, so this function's "nothing
+    here may raise" promise is only as strong as whatever callback the
+    caller supplies. `doctor()`'s real callback (`_print_check`) prints
+    through `_print_stream_lines`, which guards exactly that failure and
+    explains why (see its docstring for the mechanism -- not restated here)
+    rather than letting it unwind back through here and discard every check
+    already collected. A direct test caller that passes a callback of its
+    own is responsible for the same guarantee.
+
+    `on_check` (tan-cli streaming, change 3) fires the MOMENT each check is
+    added, in the exact same order -- `doctor()`'s text branch passes a
+    callback that prints that one check's block immediately, so a slow probe
+    later in this function never leaves an already-answered check unprinted
+    on screen. `None` (every direct test caller of this function, and JSON
+    mode) skips the callback entirely and this returns exactly the batch
+    `list[Check]` it always has.
+
+    `build` (`--build`) is accepted and forwarded from `doctor()` but no
+    longer changes anything here (tan-cli#290): `zephyrWorkspace`, the last
+    check it used to gate, now runs unconditionally alongside `workspace`/
+    `zephyrVersion` -- see `zephyr_workspace_check`'s docstring for why. Kept
+    as a parameter rather than dropped so every existing direct caller (this
+    file's own test suite, and the CLI's own forwarding call) keeps working
+    unchanged; `alp-sdk-vscode`'s `["doctor", "--build"]` call sites keep
+    working too, they just no longer see a different check list.
+
+    `board_yaml`/`project_scope`/`workspace_root` feed the tan-cli#294/#290
+    build-environment preflight (`sdk`/`boardYaml`/`workspace`/
+    `westResolved`/`venvProvenance`/`zephyrVersion`/`zephyrWorkspace`) -- all
+    default so every existing direct caller (this file's own test suite)
+    keeps working unchanged; those checks then simply report against "no
+    board.yaml"/"no workspace resolved from `.`", which is an honest verdict,
+    not a skipped one. `venvProvenance` (tan-cli#292) is the exception that
+    proves the rule: it emits NO check at all (not even against "no board.yaml")
+    when the resolved venv carries no provenance record, which is the common
+    case for a workspace alp-sdk's own `bootstrap.sh` set up.
+
+    `boardYaml`'s severity needs one more fact: whether a project was
+    actually SELECTED (`--project`/`--board-yaml` given), not merely whether
+    the guessed path exists (tan-cli#294 review). `board_yaml` doubles as
+    that signal here: the only way it is non-`None` while its file does NOT
+    exist is an explicitly-given `--board-yaml` (`doctor()`'s own
+    auto-discovery only ever sets it to a path that already `is_file()`), so
+    `board_yaml is not None` is a safe proxy for "explicitly given" exactly
+    where it matters -- the branch where `present` is False.
+
+    `sdk_tier` -- the `SdkSourceTier` `resolve_sdk_root_ladder` answered
+    `sdk_root` with, threaded through so `sdk_check` (tan-cli#301) can name
+    it. Optional/defaulted for the same reason every other parameter here is:
+    every existing direct caller keeps working, reporting `sdk` with no tier
+    parenthetical rather than a guessed one.
+
+    `broken_global_default` (tan-cli#344) -- the raw `sdkPath` a dangling
+    `~/.alp/sdk-default` pointer names, computed once by the caller
+    (`_broken_global_default`) and threaded straight to `sdk_check`. Optional/
+    defaulted like `sdk_tier`; only changes the `sdk` check's remedy text, and
+    only in the branch `sdk_root is None` already reaches.
+    """
+    checks: list[Check] = []
+
+    def _add(check: Check) -> None:
+        checks.append(check)
+        if on_check is not None:
+            on_check(check)
+
+    # tan-cli#294 finding 2: build-environment preflight -- LEADS the report,
+    # mirroring Rust's `prepend_doctor_checks(..., probe_build_preflight(...))`:
+    # "can a build even start" outranks every host-tool probe below.
+    #
+    # tan-cli#301: a checkout discoverable from cwd that a HIGHER tier
+    # outranked is surfaced too, but ONLY the discovery `sdk_check` itself
+    # would have used were nothing above it configured (`discover_sdk_root`,
+    # the WIDE walk `resolve_sdk_root_ladder`'s own tail already falls back
+    # to) -- reusing that exact helper instead of a second, hand-rolled scan
+    # is what keeps this a report-only addition: it can only ever name a
+    # candidate the ladder itself already knows how to reach, never invent
+    # one of its own. Skipped when the winning tier already IS discovery (or
+    # nothing): there is nothing "unselected" left to name.
+    unselected_candidate: str | None = None
+    if sdk_root is not None and sdk_tier not in (None, "discovery", "none"):
+        candidate = discover_sdk_root(Path(workspace_root))
+        # `normcase` BOTH sides. `_abs_posix` is `abspath` + slash-swap and
+        # deliberately does not resolve, so on Windows the SAME directory
+        # spelled with different case -- a `~/.alp/sdk-default` written from a
+        # differently-cased `tan sdk switch`, or a differing drive-letter case
+        # -- compared unequal and the report told the user to select the SDK
+        # that was already selected:
+        #     alp-sdk at ...\ws\ALP-SDK (globalDefault; a checkout at
+        #     ...\ws\alp-sdk was not selected -- pass --sdk-root ... to use it)
+        # A report that lies is the defect class #301 exists to close, so it
+        # must not be reintroduced by the fix for it. No-op on POSIX.
+        if candidate is not None and os.path.normcase(
+            _abs_posix(str(candidate))
+        ) != os.path.normcase(_abs_posix(sdk_root)):
+            unselected_candidate = str(candidate)
+    # tan-cli#407: the #301 block above deliberately says nothing when the
+    # winning tier already IS `discovery` -- and that is precisely the case
+    # where the second checkout is not merely "unselected" but ACTIVELY in
+    # use, by the four commands that take the wide ladder. Same report-only
+    # discipline as #301: the candidate can only ever be one
+    # `resolve_sdk_root_wide` itself would reach, never a scan of its own.
+    divergent_candidate: str | None = None
+    if sdk_root is not None and sdk_tier == "discovery":
+        wide = resolve_sdk_root_wide(None, Path(workspace_root)).path
+        # `normcase` both sides, for the reason spelled out in the #301 block
+        # above: `_abs_posix` does not resolve, so on Windows one directory
+        # under two spellings would be reported as two checkouts.
+        if wide is not None and os.path.normcase(_abs_posix(str(wide))) != os.path.normcase(
+            _abs_posix(sdk_root)
+        ):
+            divergent_candidate = str(wide)
+    # tan-cli#727. Guarded at THIS call site, not inside
+    # `resolve_sdk_root_ladder` -- the same placement `build_cmd`,
+    # `run_cmd`, `validate_cmd`, `clean_cmd.sdk_root_resolves` and
+    # `flash_cmd._resolve_sdk` each chose, because every other caller depends
+    # on the ladder handing the flag back unvalidated.
+    dangling_flag_root = (
+        sdk_root if sdk_tier == "sdkRootFlag" and not is_sdk_root(sdk_root) else None
+    )
+    _add(
+        sdk_check(
+            sdk_root,
+            project_scope,
+            sdk_tier,
+            unselected_candidate,
+            broken_global_default,
+            divergent_candidate,
+            dangling_flag_root,
+        )
+    )
+    project_selected = bool(project_scope and project_scope.strip()) or board_yaml is not None
+    _add(
+        board_yaml_preflight_check(
+            board_yaml is not None and Path(board_yaml).is_file(), project_selected
+        )
+    )
+    # Immediately after `boardYaml`, and reading the SAME two facts `sdk` and
+    # `boardYaml` just reported on -- the selection is a fact ABOUT that file,
+    # resolved against THAT checkout, so a report where the two disagree would
+    # be incoherent. Emits nothing at all for a project that selects no
+    # curated libraries (see `libraries_check`).
+    libraries = libraries_check(
+        inspect_selection(
+            Path(board_yaml) if board_yaml is not None else None,
+            Path(sdk_root) if sdk_root is not None else None,
+        )
+    )
+    if libraries is not None:
+        _add(libraries)
+    workspace_path = west_workspace_dir(
+        workspace_root, Path(sdk_root) if sdk_root is not None else None
+    )
+    _add(
+        workspace_preflight_check(
+            str(workspace_path) if workspace_path is not None else None,
+            start=workspace_root,
+            sdk_root=sdk_root,
+            zephyr_base=os.environ.get("ZEPHYR_BASE"),
+        )
+    )
+
+    # tan-cli#290: `westResolved`, right after `workspace` -- the same order
+    # Rust's `build_preflight_checks` uses (`sdk`, `boardYaml`, `workspace`,
+    # `westResolved`, `zephyrVersion`). The resolved binary is the SAME one
+    # `tan build` would spawn (`tan.core.venv.west_program`): an absolute
+    # venv path is trusted directly (`find_workspace_venv` already confirmed
+    # it exists), a bare `"west"` fallback is re-checked against PATH, never
+    # the reverse -- so a `westResolved` version can never be attributed to a
+    # different binary than the one that answered it (tan-cli#123's exact
+    # bug, reintroduced by the port and closed here).
+    resolved_west = west_program(workspace_root, sdk_root)
+    west_resolved_exe = (
+        resolved_west if os.path.isabs(resolved_west) else on_path(resolved_west)
+    )
+    # tan-cli#488 defect 1: `probe_status`, not `probe` -- `west_resolved_ran`
+    # tells `west_resolved_check` whether `--version` actually ran to a
+    # successful exit, separately from whether its output parsed. `probe()`
+    # alone collapses "could not be spawned" (a `west` launcher whose file
+    # survives a relocated/renamed workspace but whose interpreter does not)
+    # and "spawned, exited zero, printed something unparseable" into the same
+    # `None` -- `pass` is only correct for the second.
+    west_resolved_ran, west_resolved_stdout = (
+        probe_status([west_resolved_exe, "--version"])
+        if west_resolved_exe is not None
+        else (False, None)
+    )
+    west_resolved_version = _parse_two(west_resolved_stdout or "")
+    _add(west_resolved_check(west_resolved_exe, west_resolved_version, west_resolved_ran))
+
+    # tan-cli#292: `venvProvenance`, right beside `westResolved` -- it is a
+    # verdict on the SAME resolved venv (`find_workspace_venv`, the search
+    # `west_program` itself resolves `west` through), just reading its
+    # tan-written provenance record instead of probing the binary.
+    venv_path = find_workspace_venv(workspace_root, sdk_root)
+    venv_record: WorkspaceSdkRecord | None = None
+    if venv_path is not None:
+        record_text = _read_text(venv_path.parent / ".west" / "tan-workspace-sdk")
+        if record_text is not None:
+            venv_record = parse_workspace_sdk_record(record_text)
+    provenance_check = venv_provenance_check(venv_record, sdk_root)
+    if provenance_check is not None:
+        _add(provenance_check)
+
+    if workspace_path is not None:
+        workspace_version = None
+        version_body = _read_text(workspace_path / "zephyr" / "VERSION")
+        if version_body is not None:
+            workspace_version = parse_zephyr_version_file(version_body)
+        sdk_pin_for_workspace = None
+        if sdk_root is not None:
+            west_yml_body = _read_text(Path(sdk_root) / "west.yml")
+            if west_yml_body is not None:
+                sdk_pin_for_workspace = parse_west_zephyr_pin(west_yml_body)
+        zephyr_version_check = zephyr_version_preflight_check(
+            workspace_version, sdk_pin_for_workspace
+        )
+        if zephyr_version_check is not None:
+            _add(zephyr_version_check)
+        # tan-cli#290: unconditional now, sourced from these SAME resolved
+        # facts -- see `zephyr_workspace_check`'s docstring for why it still
+        # earns its own check beside `zephyrVersion` rather than being
+        # dropped as a duplicate.
+        _add(zephyr_workspace_check(str(workspace_path), workspace_version))
+        # tan-cli#1376: read-only; never raises, never fails an offline doctor.
+        _add(
+            workspace_patches_check(
+                check_workspace_patches(workspace_path, sdk_root, timeout=30), str(workspace_path)
+            )
+        )
+        zephyr_base_info = zephyr_base_check(os.environ.get("ZEPHYR_BASE"), str(workspace_path))
+        if zephyr_base_info is not None:
+            _add(zephyr_base_info)
+
+    # tan-cli#294 finding 1: host-environment checks -- also unconditional
+    # HOST facts (no board.yaml/workspace/SDK needed). See their docstrings.
+    host_os, host_arch = _host_os_arch_tags()
+    _add(zephyr_sdk_host_check(host_os, host_arch))
+    if os.name == "nt":
+        _add(
+            long_paths_check(_long_paths_enabled(), _git_core_longpaths(_resolve_git_executable()))
+        )
+    _add(home_path_check(os.environ.get("USERPROFILE" if os.name == "nt" else "HOME")))
+    # `tanInstall`: is this running tan behind the source it was installed from?
+    _add(_tan_install_check())
+
+    # tan-cli#441: `bootstrapManifest` + `hostPrerequisites` (and the manifest
+    # load + Python probe `hostPython`/`pythonFloor`/`west` below also need)
+    # are built by the ONE shared `_resolve_prerequisites_environment` --
+    # `host_environment_checks` calls the SAME function for support-bundle's
+    # seam, so the two callers can never build a diverging verdict.
+    #
+    # tan-cli#980 review nit 3, decided rather than restored: because this
+    # call now builds `hostPrerequisites` (PATH walk over `required`, plus
+    # the POSIX `_posix_venv_capable` spawn) EAGERLY as part of the same
+    # shared unit, `bootstrapManifest`/`hostPython`/`pythonFloor` below are
+    # `_add`ed -- and so, in `tan doctor` TEXT mode, printed by `on_check` --
+    # AFTER that PATH walk and spawn finish, where pre-#441 `_collect` built
+    # and `_add`ed each of the three the moment it had the data, before ever
+    # touching PATH or spawning `_posix_venv_capable`. The returned list
+    # order and the JSON envelope are byte-identical either way (verified in
+    # the PR's own equivalence pass) -- only the incremental print TIMING
+    # `on_check` exists for shifts by the wall-clock cost of two spawns this
+    # single caller already pays for regardless of which check the delay is
+    # attributed to. Restoring the old interleaving would mean splitting
+    # `_resolve_prerequisites_environment` back into a pre-PATH-walk half and
+    # a post-PATH-walk half so `_collect` could `_add` between them -- which
+    # reopens the exact two-copies-of-one-decision risk this helper exists to
+    # close, for a few hundred milliseconds of `tan doctor` console timing.
+    # Accepted as-is.
+    prereq_env = _resolve_prerequisites_environment(sdk_root, workspace_path)
+    if prereq_env.bootstrap_manifest_check is not None:
+        _add(prereq_env.bootstrap_manifest_check)
+    facts = prereq_env.facts
+    effective_floor = prereq_env.effective_floor
+    effective_source = prereq_env.effective_source
+    python_found = prereq_env.python_found
+
+    _add(
+        host_python_check(
+            python_found[:2] if python_found else None,
+            effective_floor,
+            effective_source,
+            find_workspace_venv(workspace_root, sdk_root) is not None,
+            list(prereq_env.host_pythons),
+        )
+    )
+    skew = python_floor_skew_check(
+        prereq_env.manifest_floor,
+        effective_floor,
+        effective_source,
+        manifest_is_real=prereq_env.manifest_is_real,
+    )
+    if skew is not None:
+        _add(skew)
+
+    _add(prereq_env.prerequisites_check)
+
+    west_exe = on_path("west")
+    # tan-cli#488 defect 5: probe `west_exe` -- the PATH-RESOLVED absolute
+    # path `on_path` just returned -- never a second, bare-name spawn.
+    # `on_path` deliberately excludes the cwd for exactly this reason (its own
+    # docstring: a project checked out with its own `west.exe` at its root
+    # must not be reported as this host's tooling); a bare `probe(["west",
+    # ...])` re-opens that gap outright -- CreateProcess searches the cwd
+    # before PATH on Windows, and an empty PATH element (a leading/trailing
+    # `:`, common in a hand-edited profile) does the same on POSIX -- so the
+    # reported version could come from a DIFFERENT binary than the one this
+    # check names. Every other probe in `_collect` already spawns the
+    # resolved path (`west_resolved_exe` above, `jlink_exe` below); this is
+    # the one that did not.
+    west_version = _parse_two(probe([west_exe, "--version"]) or "") if west_exe else None
+    # tan-cli#299 second half: feed `west_check` the SAME resolved venv path
+    # `westResolved` above already computed (`resolved_west`) -- never a
+    # second, independent probe -- so "absent from bare PATH, present in the
+    # resolved venv" (the default post-bootstrap state) reports `pass`
+    # instead of a permanent warn. Only passed when it is a real venv
+    # binary (an absolute path); `west_program`'s bare-`"west"` fallback
+    # carries no information `west_exe` above does not already have.
+    #
+    # tan-cli#488 defect 3: `west_resolved_ran` (computed above, the same
+    # `probe_status` result `westResolved` itself was fixed to consult for
+    # defect 1) also passed through -- so a resolved-but-unspawnable west
+    # cannot report `pass` here while `westResolved` reports `fail` for the
+    # identical binary.
+    _add(
+        west_check(
+            west_exe,
+            west_version,
+            _parse_two(str(facts.get("_pipSpec") or "")),
+            resolved_west if os.path.isabs(resolved_west) else None,
+            west_resolved_ran,
+        )
+    )
+
+    # Unconditional -- not gated on `build` or a resolved board.yaml/SDK. See
+    # `zephyr_sdk_check`'s docstring (tan-cli#286).
+    zephyr_sdk_ok = _zephyr_sdk_detected()
+    _add(zephyr_sdk_check(zephyr_sdk_ok, os.environ.get("ZEPHYR_SDK_INSTALL_DIR")))
+    # issue #474 (ADR 0021 Lane 1 P1): stamp-vs-pin, narrower than `zephyrSdk`
+    # above -- see `toolchain_check`'s own docstring for the distinction.
+    _add(toolchain_check(sdk_root))
+    # tan-cli#1192: beside the two toolchain checks because it reads the SAME
+    # resolved SDK install (`_zephyr_sdk_detected_root`) they do -- but it
+    # answers a question neither does: whether Zephyr's diagnostics-only `dtc`
+    # pass will run at all now that `tan bootstrap` acquires the SDK with
+    # `--no-hosttools` (tan-cli#1178) and so ships no `dtc`. NOT added to
+    # `host_environment_checks` below: `tan support-bundle` reports only the
+    # five checks `_HOST_CHECK_ORDER` names, and this is not one of them --
+    # see `devicetree_lint_check`'s docstring for why that is deliberate.
+    _add(devicetree_lint_check(_resolve_dtc()))
+    # tan-cli#736: unconditional on Windows. This used to ride the
+    # `zephyrSdk` Fail (`and not zephyr_sdk_ok`), which silently excused the
+    # host that has an SDK and no 7-Zip -- exactly the host whose next
+    # `west sdk install` dies with `Zephyr SDK setup requires '7z'`. Still a
+    # `warn`, not a `fail`: see `seven_zip_check`'s docstring and
+    # tan-cli#204 for why the SEVERITY is right and only the GATE was wrong.
+    if os.name == "nt":
+        # tan-cli#1523: same predicate `tan bootstrap`'s preflight uses, so
+        # doctor cannot pass a host (unar-only, or 7z.exe only in the cwd)
+        # that bootstrap refuses.
+        from tan.commands.bootstrap_toolchain_fetch import _find_seven_zip
+
+        _add(seven_zip_check(_find_seven_zip() is not None))
+
+    # tan-cli#1323: the precedence `tan flash` applies (`resolve_setools_dir`),
+    # minus the per-run `--setools-dir` flag doctor cannot see: $SETOOLS_DIR,
+    # then the built manifest's flash_args.setools_dir.
+    flash_info = project_flash(board_yaml)
+    setools_dir = os.environ.get("SETOOLS_DIR") or (
+        flash_info.setools_dir if flash_info is not None else None
+    )
+    setools_source = (
+        "$SETOOLS_DIR" if os.environ.get("SETOOLS_DIR") else "the manifest's flash_args.setools_dir"
+    )
+    _add(
+        setools_check(
+            setools_dir,
+            os.environ.get("SE_UART"),
+            sys.platform.startswith("linux"),
+            flash_info.methods if flash_info is not None else None,
+            jlink_available(
+                str(Path(board_yaml).parent) if board_yaml is not None else workspace_root,
+                sdk_root,
+            ),
+            setools_source,
+        )
+    )
+
+    jlink_name, jlink_exe = next(
+        (
+            (name, found)
+            for name in ("JLinkExe", "JLink", "JLinkGDBServerCL")
+            if (found := on_path(name))
+        ),
+        (None, None),
+    )
+    # JLinkExe has no `-?` flag (`Unknown command line option -?.`); the
+    # version banner it prints unprompted at the top of every real invocation
+    # is what `jlink_banner` reads instead. See its docstring. NOT spawned
+    # against `JLinkGDBServerCL` (the third fallback name): that binary never
+    # reads stdin and never quits on `jlink_banner`'s `exit\n`, so it would
+    # hold a GDB port for the full `PROBE_TIMEOUT_S` on every `tan doctor`
+    # run on a host where only the GDB server is on PATH. `jlink_check`
+    # already reports "found but version could not be read" for a `None`
+    # version, which is the correct outcome here too.
+    jlink_version = (
+        _parse_two(jlink_banner(jlink_exe) or "")
+        if jlink_exe and jlink_name != "JLinkGDBServerCL"
+        else None
+    )
+    resolved_device, device_source = jlink_flash_device(sdk_root)
+    _add(jlink_check(jlink_exe, jlink_version, resolved_device, device_source))
+
+    # tan-cli#294 finding 5: LAST, mirroring `assemble_doctor_report`'s own
+    # placement -- traces a report back to the SDK checkout that produced it.
+    # tan-cli#727: skipped for a `--sdk-root` the marker check rejected.
+    # `sdk_provenance_check` finds no git checkout and no
+    # `metadata/sdk_version.yaml` under a path that is not there, and its
+    # else-branch renders that absence as `pass | alp-sdk at <path> (no git
+    # checkout / metadata/sdk_version.yaml)` -- a green line asserting an
+    # alp-sdk at a directory that does not exist.
+    if sdk_root is not None and dangling_flag_root is None:
+        _add(sdk_provenance_check(sdk_root))
+
+    return checks
+
+
+def _generated_at() -> str:
+    """`SOURCE_DATE_EPOCH` when set, so a captured envelope is reproducible --
+    `tan.core.timestamp`, which NEVER raises.
+
+    An out-of-range epoch (the MILLISECONDS case) used to throw from here, and
+    the caller's own try/except then reported `doctor.internal-failure`: a
+    fabricated "tan is broken" verdict on a host that was diagnosed fine.
+    """
+    return generated_at_iso()
+
+
+def _print_stream_lines(lines: Iterable[str], label: str) -> None:
+    """The ONE guarded stderr-print path `doctor()`'s two streaming call
+    sites both go through -- once per finished check (`_print_check`) and
+    once more for the footer (summary / failed-checks / extra-issue lines)
+    -- neither prints via a bare `print()` loop of its own any more.
+
+    Measured, not inferred (this repo's own oracle rule -- established by
+    RUNNING, never by reasoning about it): `tan.cli.main` calls
+    `_reconfigure_stdio()` before any command runs, which puts `sys.stderr`
+    in utf-8/`errors="strict"` -- a legacy-codepage stream (`cp1252`) never
+    reaches this function on the real CLI path, and `cp1252` can encode `…`
+    (U+2026) anyway (`"\\u2026".encode("cp1252")` == `b"\\x85"`), so that was
+    never the actual risk. What DOES raise `UnicodeEncodeError` on a strict
+    utf-8 stream is a lone surrogate (e.g. `\\udcff`) -- a filesystem path
+    that reached Python via `surrogateescape` (`on_path`'s `shutil.which`
+    result, resolved off `PATH`) and that a check's `detail`/`fix` text goes
+    on to print verbatim; utf-8 cannot encode a lone surrogate no matter what
+    decoded it. `OSError` (its subclass `BrokenPipeError` in particular)
+    covers a closed PIPE (`tan doctor | head`); `ValueError` covers a stream
+    closed OUTRIGHT (`I/O operation on closed file` -- the object itself is
+    gone, not merely refusing writes at the far end) -- included
+    deliberately, because the one thing this guard exists to prevent,
+    discarding an already-finished diagnosis over how the stream died, does
+    not care which of the three killed it, and the `try` body here is
+    nothing but `print()` calls to a fixed stream, so a bare `ValueError`
+    catch has no wider blast radius to worry about.
+
+    Unguarded, any of the three propagates out of `_collect` (as `on_check`)
+    into `doctor()`'s own `except Exception`, discarding every check this
+    run already completed as a fabricated `doctor.internal-failure`; from
+    the footer call site (never inside that `try`) it would instead escape
+    `doctor()` outright as a raw, unhandled traceback. Caught here instead,
+    and never silently: a second, INDEPENDENT `try` wraps the failure note
+    itself, since it prints through the SAME `sys.stderr` that just failed.
+    Nothing left to do if even that fails -- the diagnosis behind it already
+    made it back to `doctor()` (or, for the footer, was already fully
+    rendered) regardless.
+    """
+    try:
+        for line in lines:
+            print(line, file=sys.stderr)
+    except (UnicodeError, OSError, ValueError) as err:
+        try:
+            print(
+                f"doctor: could not print the '{label}' block "
+                f"({type(err).__name__}: {err}).",
+                file=sys.stderr,
+            )
+        except (UnicodeError, OSError, ValueError):
+            pass
+
+
+def doctor(
+    project: str = typer.Option(
+        None, "--project", metavar="PATH", help="Project root (defaults to '.')."
+    ),
+    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."
+    ),
+    build: bool = typer.Option(
+        False,
+        "--build",
+        help=inert_help(
+            "Accepted for compatibility: zephyrWorkspace, the check this used "
+            "to gate, now runs unconditionally, so this flag no longer changes "
+            "the check list.",
+            COMPATIBILITY,
+            "tan-cli#290",
+        ),
+    ),
+    fix: bool = typer.Option(
+        False,
+        "--fix",
+        help="Run the manifest's own install command (ADR 0021) for any "
+        "hostPrerequisites tool this host is missing. A command needing no "
+        "elevation runs for any caller; a `sudo`-prefixed one runs too, but "
+        "only when this process is already root, with the literal `sudo` "
+        "word stripped first -- tan itself never spawns the `sudo` program. "
+        "A non-root caller instead gets that command printed to run by hand. "
+        "Only in an interactive, non-CI, text-mode run (a real terminal on "
+        "both stdin and stderr; --non-interactive/--ci/--format json all "
+        "disable it): a repair a human did not watch happen is not consent.",
+    ),
+    output_format: OutputFormat = typer.Option(OutputFormat.TEXT, "--format", help=FORMAT_HELP),
+    non_interactive: bool = typer.Option(
+        False,
+        "--non-interactive",
+        help="Never prompt, and never run --fix's repairs -- see --fix.",
+    ),
+    ci: bool = typer.Option(
+        False, "--ci", help="CI mode: implies --non-interactive and disables --fix."
+    ),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable ANSI colour."),
+) -> None:
+    """Diagnose whether this host can build and flash."""
+    json_mode = output_format == "json"
+
+    # Snapshot the RAW `--project` value before `project` is reassigned below
+    # to the envelope's `Project` object -- `sdk_check`'s scoped-switch hint
+    # (tan-cli#294 finding 2 / #101) needs the string, not the envelope block.
+    project_scope = project
+
+    # 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 prologue -- not only inside `_collect` -- still produces the
+    # `doctor.internal-failure` envelope the guard below promises, instead
+    # of a raw traceback with empty stdout. `Path.cwd()` a few lines below
+    # is the concrete case: a working directory deleted out from under the
+    # process (a cleanup script racing a `tan doctor` run in the same
+    # shell) 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. Every value here is overwritten the moment
+    # the try body below reaches its own assignment.
+    project_envelope: Project = 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
+    try:
+        # `util::cli_workspace_root`: `--project` joined onto the cwd, and
+        # everything below (board.yaml discovery, SDK discovery, the reported
+        # `project.root`) anchors on THAT -- see `build_cmd.build` for the same
+        # pattern and why an unanchored `--project` builds the wrong project.
+        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 the discovery branch below -- same pattern as `build_cmd.build`
+        # and `crates/tan-core/src/project.rs:198-208`'s `resolve_board_yaml_path`.
+        # Left unanchored, a relative `--board-yaml` under `--project app` reports
+        # (and would build/flash) the board.yaml sitting in the real cwd instead
+        # of the one inside `app`.
+        if board_yaml is not None and not os.path.isabs(board_yaml):
+            board_yaml = os.path.join(str(workspace_root), board_yaml)
+        if board_yaml is None and (workspace_root / "board.yaml").is_file():
+            board_yaml = str(workspace_root / "board.yaml")
+        # `--sdk-root` > `.alp/sdk-path` project pin > machine-global default >
+        # the positional walk (`resolve_sdk_root_ladder`) -- no `ALP_SDK_ROOT`
+        # tier (tried and reverted -- see `resolve_sdk_root_ladder`'s own
+        # docstring). Previously this skipped straight from `--sdk-root` to the
+        # positional walk, silently ignoring `tan init`'s own pointer 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
+        sdk_root = str(resolved_sdk_root) if resolved_sdk_root is not None else None
+        sdk = SdkInfo.from_resolution(sdk_root, sdk_resolution) if sdk_root is not None else None
+        # tan-cli#344: a dangling `~/.alp/sdk-default` is a distinct fact from
+        # "nothing configured" -- computed unconditionally (one small file read)
+        # so `sdk_check` can name it in the one branch (`sdk_root is None`) where
+        # the two used to print the identical sentence.
+        broken_global_default = _broken_global_default()
+        # Forward slashes -- the established envelope contract on this seam
+        # (`build_cmd.build`, `flash_cmd._resolve_project`), not the native
+        # separators `str(Path(...))` would emit on Windows.
+        #
+        # tan-cli#236: `boardYaml` reported only when the file really exists. An
+        # explicit `--board-yaml` skips the `is_file()` discovery guard above, so
+        # without this it could still name a path nothing sits at.
+        project_envelope = Project.resolved(
+            _abs_posix(str(workspace_root)),
+            _abs_posix(board_yaml) if board_yaml is not None else None,
+        )
+
+        # Text mode streams each check the MOMENT it completes (tan-cli doctor
+        # v2, change 3): `_collect` runs up to 15 subprocess probes at
+        # `PROBE_TIMEOUT_S` each, and the old code printed nothing until every
+        # one of them had answered -- on a host where one wedges, a blank
+        # terminal names nothing. Width floored at `TEXT_WRAP_MIN_WIDTH` -- a
+        # 20-column terminal must not fall to one word per line -- and measured
+        # through `tan.env.terminal_width`, the one place that reads a
+        # terminal's columns, sharing the 100-column fallback with
+        # `tan.env.wrap_width`. tan-cli#564: this used to be a bare
+        # `shutil.get_terminal_size(fallback=(100, 24))`, which measures
+        # `sys.__stdout__` -- but this report is printed to STDERR, so
+        # `tan doctor > report.txt` from a 70-column terminal took the 100 and
+        # put 94-, 95- and 105-column lines on a 70-column screen.
+        # `width`/`color` are resolved unconditionally, even under
+        # `--format json` where neither is ever read: both calls are cheap and
+        # emit nothing, so gating them behind `if stream` bought nothing but a
+        # second, held-together-by-an-11-line-comment invariant (`_print_check`
+        # closes over both) for no benefit.
+        #
+        # UNCONDITIONAL on stderr being a terminal at all (unlike
+        # `tan.env.wrap_width`, which `explain`/`sdk current` use instead): a
+        # piped `tan doctor` still wraps to `terminal_width`'s own fallback
+        # today. That is a real inconsistency with the new seam, left exactly as
+        # it shipped in PR #480 rather than silently fixed here -- see that PR
+        # for the call to change it.
+        stream = not json_mode
+        width = max(terminal_width(100), TEXT_WRAP_MIN_WIDTH)
+        color = use_color(no_color, ci)
+
+        def _print_check(check: Check) -> None:
+            """`on_check`'s real, streaming callback: render one check's block
+            and print it through `_print_stream_lines` -- the FOURTH way
+            `_collect` reaches the outside world (see its docstring), and the
+            only one of the four that can raise. See `_print_stream_lines`'s own
+            docstring for the guard and why it is shaped the way it is; not
+            restated here.
+            """
+            _print_stream_lines(render_check_lines(check.as_dict(), width, color), check.name)
+
+        checks = _collect(
+            sdk_root,
+            build=build,
+            board_yaml=board_yaml,
+            project_scope=project_scope,
+            workspace_root=str(workspace_root),
+            sdk_tier=sdk_tier,
+            broken_global_default=broken_global_default,
+            on_check=_print_check if stream else None,
+        )
+        # tan-cli#91 / ADR 0021: `--fix` only ever RUNS anything when a human
+        # is demonstrably present. `doctor` otherwise only REPORTS; this flag
+        # turns it into a machine-global, network-fetching installer, so the
+        # consent gate is the feature, not decoration around it.
+        #
+        # Delegated to [`tan.core.consent.can_prompt`] rather than spelled out
+        # inline, because spelling it out inline is exactly how this went
+        # wrong: the hand-written form tested only the three FLAGS
+        # (`!non_interactive && !ci && !is_json`) and omitted the two
+        # `isatty()` calls, so a CI runner that redirected its output but did
+        # not happen to pass `--ci` got unattended host mutation -- measured
+        # under fully captured pipes, four real `winget install` runs with
+        # nobody watching. The oracle's own `--non-interactive` help states
+        # the missing half ("the same rule applies unasked when stdin or
+        # stderr is not a terminal -- piped, redirected, or a CI runner").
+        # See that module for why BOTH handles matter, and why `stdout`
+        # deliberately does not.
+        fix_allowed = fix and can_prompt(non_interactive=non_interactive, ci=ci, json_mode=json_mode)
+        if fix_allowed:
+            # `fix_missing`, NEVER `missing`: tan-cli#760 review MAJOR 1.
+            # `missing` is the CONFIRMED, customer-facing field (`data.
+            # missingPrerequisites`) and nulls a command whose own installer
+            # this host cannot confirm; `run_fix` needs the RAW commands to
+            # do its OWN on_path resolution and keep reporting tan-cli#360's
+            # `doctor.fix-installer-not-found` diagnosis on the hosts #360
+            # exists for, instead of a silent no-op.
+            missing_for_fix = next(
+                (c.fix_missing for c in checks if c.name == "hostPrerequisites"), None
+            )
+            if missing_for_fix:
+                # These checks stream too, same as every check `_collect`
+                # produced above -- `run_fix` takes the SAME `on_check`
+                # `_collect` does, gated on `stream` directly (never on
+                # "`fix_allowed` already implies `not json_mode`": that
+                # inference only holds for the REAL `can_prompt`, and a test
+                # double stubbing `can_prompt` can make `fix_allowed` true
+                # under `--format json`, where printing a check block to
+                # stderr would be wrong regardless of `width`/`color` being
+                # bound -- both are resolved unconditionally now, see above).
+                fix_checks = run_fix(missing_for_fix, on_check=_print_check if stream else None)
+                checks = [*checks, *fix_checks]
+        exit_code = exit_code_for(checks)
+        issues = checks_to_issues(checks)
+        # tan-cli#91 P1: `--fix` requested and consent refused used to be a
+        # SILENT no-op, byte-for-byte identical to plain `tan doctor` --
+        # measured against the oracle (`doctor --fix --format json`, which the
+        # oracle instead refuses to parse outright). SAY SO instead: name
+        # every condition of `can_prompt`'s that actually tripped.
+        if fix and not fix_allowed:
+            issues = [
+                *issues,
+                fix_suppressed_issue(non_interactive=non_interactive, ci=ci, json_mode=json_mode),
+            ]
+        # tan-cli#294 finding 4 (#203/#210, alp-sdk-vscode#347, ADR 0021 P0a):
+        # `hostPrerequisites` is the only check that ever carries a
+        # `{tool, command}` pair, so it is the only place this reads from --
+        # mirrors `apply_prerequisite_check`'s report-level field. `alp-sdk-
+        # vscode`'s `runDependencyAction` sends `missingPrerequisites[].command`
+        # to a terminal; without this key that one-click affordance silently
+        # disappears on the extension side (the extension itself does not
+        # crash on absence -- it feature-detects on the key, per
+        # `vscodeAdapter.ts`).
+        missing_prerequisites = next(
+            (c.missing for c in checks if c.name == "hostPrerequisites"), None
+        )
+        data = {
+            "generatedAt": _generated_at(),
+            "summary": summarise(checks),
+            "checks": [c.as_dict() for c in checks],
+            "nextSteps": next_steps(checks),
+            "missingPrerequisites": missing_prerequisites,
+        }
+    except Exception as err:  # noqa: BLE001
+        # The port's most-repeated defect class: an uncaught exception escapes as
+        # a raw traceback, stdout stays empty, and the extension renders nothing
+        # with no error on either side. Every probe above is already guarded, and
+        # so is the one thing `_collect` calls that is not a probe: its `on_check`
+        # callback prints through `_print_stream_lines`, which guards its own
+        # failures (see its docstring) instead of letting them unwind here and
+        # discard a diagnosis that already finished -- so anything still reaching
+        # here is a tan bug -- reported as one, with an envelope. INTERNAL_FAILURE,
+        # not DOCTOR_FAILURE: the host was never diagnosed, and claiming it is
+        # unhealthy would be a fabricated verdict.
+        exit_code = ExitCode.INTERNAL_FAILURE
+        data = None
+        issues = [Issue("doctor.internal-failure", "error", f"{type(err).__name__}: {err}")]
+
+    # tan-cli#263 review: this is the "tan doctor says ready, 0 issues"
+    # report -- a `.alp/sdk-path` pin that silently missed must show up here,
+    # not just on a `sdk current` a suspicious operator has to think to run.
+    pin_issue = project_pin_issue(sdk_broken_pin, sdk_tier)
+    if pin_issue is not None:
+        issues = [pin_issue, *issues]
+    foreign_issue = global_default_foreign_project_issue(sdk_foreign_default)
+    if foreign_issue is not None:
+        issues = [foreign_issue, *issues]
+
+    if json_mode:
+        emit(Envelope("doctor", project_envelope, data, issues, exit_code, sdk=sdk))
+    elif data is None:
+        for issue in issues:
+            print(f"{issue.severity}: {issue.message}", file=sys.stderr)
+    else:
+        # tan-cli#375: an Issue with no backing Check -- a suppressed `--fix`
+        # (`fix_suppressed_issue`) or a broken `.alp/sdk-path` pin
+        # (`project_pin_issue`, tan-cli#263) -- used to vanish here
+        # completely: this branch (the non-exception path) used to print
+        # only the per-check lines and the summary, never `issues`. `--fix`'s
+        # consent gate (tan-cli#91) is right to suppress silently TOWARDS THE
+        # HOST -- it must never mutate anything unwatched -- but silence
+        # towards the CUSTOMER is a different bug: the JSON envelope already
+        # carried `doctor.fix-suppressed`/`sdk.project-pin-unresolved` and
+        # text mode carried neither. `checks_to_issues(checks)` already turns
+        # every warn/fail Check into an Issue, and each of those already
+        # rendered as its own `[  warn]`/`[  fail]` block, streamed above as
+        # `_collect` produced it -- reprinting them here would duplicate the
+        # whole report, so this filters down to exactly the codes no Check
+        # block already named. `render_doctor_footer` places these AFTER
+        # every check block (already on screen) and BEFORE the summary:
+        # findable without being buried mid-report, report still ends on the
+        # summary line.
+        # `kebab_check_name`, not the bare `c.name`: tan-cli#461 made the
+        # camelCase-to-kebab conversion the one shared way a `Check.name`
+        # becomes an issue-code suffix, so the set built here must be spelled
+        # the same way `checks_to_issues` spells the codes it is filtering
+        # against -- otherwise every check-backed issue misses the set and
+        # the whole report prints twice.
+        checked_codes = {c.code or f"doctor.{kebab_check_name(c.name)}" for c in checks}
+        extra_issue_lines = [
+            f"{issue.severity}: {issue.message}"
+            for issue in issues
+            if issue.code not in checked_codes
+        ]
+        _print_stream_lines(
+            render_doctor_footer(data["checks"], data["summary"], extra_issue_lines, width),
+            "footer",
+        )
+
+    raise typer.Exit(int(exit_code))
+
+
+# tan-cli#261: adds the four oracle `GlobalArgs` flags this command was still
+# missing (`--all`/`--quiet`/`--target`/`--verbose`) on top of `--no-color`/
+# `--non-interactive`/`--ci`, already declared and wired into `can_prompt`
+# above; see `tan.core.global_flags`.
+doctor = accept_global_flags(doctor)