fleet-sensor-baseline 0.2.2__tar.gz → 0.2.3__tar.gz

{fleet_sensor_baseline-0.2.2 → fleet_sensor_baseline-0.2.3}/.githooks/commit-msg

@@ -14,12 +14,17 @@
 # while the code did something else entirely. Nothing checked the claim, because it
 # was a claim in a comment.
 #
-# This runs the publication vocabulary over the message: must this text never be
-# published? It is the one surface that cannot be undone after a push.
+# Two checkers now, because they answer two different questions:
+#   hygiene_check.py --message   must this text never be published?
+#   commit_msg_check.py          is this message shaped like the others?
 #
-# To commit past it knowingly:   git commit --no-verify
-# Note that --no-verify also disables the pre-commit hygiene sweep.
+# Publication first: it is the one that cannot be undone after a push.
+#
+# To commit past both knowingly:   git commit --no-verify
+# Note that --no-verify also disables the pre-commit hygiene sweep. That is why
+# these refuse only on objective problems and merely note the heuristic ones.
 set -e
 ROOT="$(git rev-parse --show-toplevel)"
 
-exec python3 "$ROOT/tools/hygiene_check.py" --message "$1"
+python3 "$ROOT/tools/hygiene_check.py" --message "$1"
+exec python3 "$ROOT/tools/commit_msg_check.py" "$1"

fleet_sensor_baseline-0.2.3/.githooks/pre-commit

@@ -0,0 +1,82 @@
+#!/bin/sh
+# Refuse a commit carrying something that should not be published, and one whose
+# README no longer describes the suite.
+#
+# Activate once per clone:   git config core.hooksPath .githooks
+#
+# Versioned deliberately. A hook that lives only in .git/hooks exists on one
+# machine, is invisible in review, and is absent from every fresh clone -- which
+# for a repository authored in public means the safety check is missing exactly
+# when a new contributor needs it most.
+#
+# To commit past it knowingly:   git commit --no-verify
+# That is a real escape hatch and it should be rare enough to notice.
+set -e
+ROOT="$(git rev-parse --show-toplevel)"
+
+# FIRST, because it decides whether anything below it can speak for this commit.
+# Every other check here reads the WORKING TREE; the commit records the INDEX.
+# When they differ, a green hook is green about files that are not being
+# committed -- which is how this repository shipped a README test count that was
+# six short, twice in one day, with this hook passing both times.
+python3 "$ROOT/tools/hygiene_check.py" --staged-is-what-ships
+
+python3 "$ROOT/tools/hygiene_check.py"
+
+# The README's test count, checked where the drift is created rather than where it
+# is discovered. Dependency-free and about 0.2s.
+#
+# The count it checks is taken from what git TRACKS, not from what the directory
+# holds, and that is the whole reason it can run here at all. The published 289 was
+# measured on a working tree carrying a test file that was never committed: true of
+# that disk, false of this repository. A disk-derived count would make this hook
+# red on any tree with an untracked test in it -- red every run, for a reason that
+# is not a defect, which is how a check teaches people to pass --no-verify. That
+# flag also switches off the hygiene sweep above, so a check nobody can satisfy
+# costs more than the one it was added to provide.
+#
+# The identity this commit will carry.
+#
+# A commit's AUTHOR is neither its message nor a file in it, so no text scanner
+# reaches it -- the hygiene rules ran over both surfaces and a personal address
+# still reached 24 published commits, because a local `user.email` quietly beat
+# the global one and nothing read it. Checked here, before the commit exists,
+# because after it is pushed a force-push changes the SHAs and removes nothing:
+# the old objects stay fetchable and the address stays published.
+AUTHOR_EMAIL=$(git config user.email || true)
+case "$AUTHOR_EMAIL" in
+    *@users.noreply.github.com|*@noreply.github.com) ;;
+    "")
+        echo "pre-commit: no user.email is set, so this commit would carry a guess." >&2
+        exit 1 ;;
+    *)
+        echo "pre-commit: user.email is a real address, and a commit publishes it." >&2
+        echo "            Set the GitHub noreply address for this repository:" >&2
+        echo "              git config user.email <you>@users.noreply.github.com" >&2
+        echo "            A local setting beats the global one; that is how this" >&2
+        echo "            reached 24 published commits before anyone looked." >&2
+        exit 1 ;;
+esac
+
+# A missing pytest fails rather than skips. A gate that converts its own red into a
+# skip removes the failure and the evidence together.
+if ! python3 -c "import pytest" 2>/dev/null; then
+    echo "pre-commit: pytest is not installed, so the README count check cannot run." >&2
+    echo "            python3 -m pip install pytest    (or commit with --no-verify)" >&2
+    exit 1
+fi
+
+# The README-count check, where a repository has one.
+#
+# This step used to name `tests/test_readme_commands.py` outright. That file is
+# this repository's; the same hook copied into four others refused EVERY commit,
+# because pytest exits non-zero when it collects nothing and the hook could not
+# tell "no such test" from "the test failed". The hooks are meant to be one file
+# across the repositories, so the step has to find its target by SHAPE rather
+# than be told a name that is only true here.
+README_TESTS=$(ls "$ROOT"/tests/test_readme*.py 2>/dev/null || true)
+if [ -z "$README_TESTS" ]; then
+    exit 0
+fi
+
+exec python3 -m pytest $README_TESTS -q -p no:cacheprovider

{fleet_sensor_baseline-0.2.2 → fleet_sensor_baseline-0.2.3}/.github/workflows/checks.yml

@@ -113,6 +113,54 @@ jobs:
       - name: The publication vocabulary, over the tree
         run: python3 tools/hygiene_check.py --all
 
+      - name: Commit messages
+        # The commit-msg hook's backstop, and the reason this is not optional: a
+        # message is the one published surface no later commit can correct.
+        run: |
+          set -euo pipefail
+          BASE="${{ github.event.pull_request.base.sha || github.event.before || '' }}"
+          if [ -z "$BASE" ] || [ "$BASE" = "0000000000000000000000000000000000000000" ] \
+             || ! git cat-file -e "$BASE^{commit}" 2>/dev/null; then
+            echo "no usable base ref; checking HEAD only"
+            LIST=$(git rev-parse HEAD)
+          else
+            LIST=$(git rev-list "$BASE..${{ github.sha }}")
+            echo "checking $(echo "$LIST" | grep -c . ) commit message(s) in $BASE..${{ github.sha }}"
+          fi
+          FAILED=0
+          for SHA in $LIST; do
+            git log -1 --format=%B "$SHA" > /tmp/msg.txt
+            echo "--- $SHA"
+            python3 tools/commit_msg_check.py /tmp/msg.txt || FAILED=1
+          done
+          exit $FAILED
+
+      - name: Authorship
+        # A commit's author is neither its message nor a file in it, so neither
+        # check above can see it. A local `user.email` quietly beat the global
+        # one and a personal address reached 24 published commits. The hook
+        # checks the setting before the commit; this checks the RESULT after it,
+        # which is the thing that actually gets published.
+        run: |
+          set -euo pipefail
+          BASE="${{ github.event.pull_request.base.sha || github.event.before || '' }}"
+          if [ -z "$BASE" ] || [ "$BASE" = "0000000000000000000000000000000000000000" ] \
+             || ! git cat-file -e "$BASE^{commit}" 2>/dev/null; then
+            LIST=$(git rev-parse HEAD)
+          else
+            LIST=$(git rev-list "$BASE..${{ github.sha }}")
+          fi
+          FAILED=0
+          for SHA in $LIST; do
+            for WHO in $(git log -1 --format='%ae%n%ce' "$SHA"); do
+              case "$WHO" in
+                *@users.noreply.github.com|*@noreply.github.com) ;;
+                *) echo "::error::$SHA carries a real address in its authorship"; FAILED=1 ;;
+              esac
+            done
+          done
+          exit $FAILED
+
       - name: A mock rack, end to end
         # 0.3's exit criterion, stated as a command: a verdict produced from
         # nothing but BMC endpoints. It runs against fake machines, which is the

{fleet_sensor_baseline-0.2.2 → fleet_sensor_baseline-0.2.3}/NOTICE

@@ -1,5 +1,5 @@
 fleet-sensor-baseline
-Copyright 2026 James Sheen
+Copyright 2026 The Arbiter Project Authors
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 this file except in compliance with the License. You may obtain a copy of the

fleet_sensor_baseline-0.2.2/README.md → fleet_sensor_baseline-0.2.3/PKG-INFO

@@ -1,3 +1,22 @@
+Metadata-Version: 2.5
+Name: fleet-sensor-baseline
+Version: 0.2.3
+Summary: Which units differ from their cohort, and what changed across time.
+Project-URL: Homepage, https://github.com/james-sheen/fleet-sensor-baseline
+Project-URL: Source, https://github.com/james-sheen/fleet-sensor-baseline
+Project-URL: Issues, https://github.com/james-sheen/fleet-sensor-baseline/issues
+Author: James Sheen
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: baseline,bmc,drift,fleet,hardware,openbmc,redfish,sensors
+Requires-Python: >=3.10
+Provides-Extra: collect
+Requires-Dist: bmc-sensor-audit<0.4,>=0.2.0; extra == 'collect'
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
 # fleet-sensor-baseline
 
 **Which units differ from their cohort, and what changed on this unit across time.**
@@ -6,9 +25,18 @@
 list of machines and the history of captures, and answers the two questions the
 referee cannot.
 
-**Released — 0.2.2**, tagged `v0.2.2`, Apache-2.0, on PyPI as
+**Released — 0.2.3**, tagged `v0.2.3`, Apache-2.0, on PyPI as
 `fleet-sensor-baseline`.
 
+**0.2.3 admits the referee's 0.3 line, and stops a closed pipe reading as a
+finding.** The `collect` extra held `bmc-sensor-audit` below 0.3 for eighteen
+days after 0.3.0, and nothing here needed it: two tests read what 0.2 kept
+where. They read the referee as installed now, and the suite passes on
+referees 0.2.7, 0.3.0 and 0.3.5 -- which also lets this extra sit beside
+`odm-cert-generator`, whose releases from 0.2.2 require the 0.3 line. And every
+subcommand, `--help` included, raised `BrokenPipeError` when its reader closed
+the pipe, exiting 1, which this family reads as findings about a rack.
+
 **0.2.2 adds `compare`, the threshold audit across time.** `drift` reads records
 and never opens a walk, so a threshold edited on a sensor that stayed present was
 invisible to it — and invisible to `collect --etag-cache` too, which is why a
@@ -350,7 +378,7 @@ first would pass by finding nothing.
 
 | | count |
 |---|---|
-| tests collected | 363 |
+| tests collected | 447 |
 | of those, requiring `bmc-sensor-audit` | 40 |
 
 **The predicate**: `pytest --collect-only` over the test files git tracks, and
@@ -377,8 +405,12 @@ a walk with the referee's own reader and asserts the fixture still matches.
 
 ## Upstream
 
-Pinned at `bmc-sensor-audit>=0.2.0,<0.3`, and the floor is **derived, not
-chosen**. It has moved three times, each time to consume something reported from
+Pinned at `bmc-sensor-audit>=0.2.0,<0.4`. **The ceiling was `<0.3` until
+2026-09-26**, eighteen days into the referee's 0.3 line, and what held it there
+was this repository's own tests reading where 0.2 kept things -- the prefix
+parser, which moved to `presence-audit` at 0.3.0, and a ceiling typed into the
+pin guard. Both now read the referee as installed, and the suite passes on 0.2.7,
+0.3.0 and 0.3.5. The floor is **derived, not chosen**. It has moved three times, each time to consume something reported from
 here:
 
 - `>=0.1.2` for `--password-env`, so a credential never crosses argv, and for

fleet_sensor_baseline-0.2.2/PKG-INFO → fleet_sensor_baseline-0.2.3/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.5
-Name: fleet-sensor-baseline
-Version: 0.2.2
-Summary: Which units differ from their cohort, and what changed across time.
-Project-URL: Homepage, https://github.com/james-sheen/fleet-sensor-baseline
-Project-URL: Source, https://github.com/james-sheen/fleet-sensor-baseline
-Project-URL: Issues, https://github.com/james-sheen/fleet-sensor-baseline/issues
-Author: James Sheen
-License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Keywords: baseline,bmc,drift,fleet,hardware,openbmc,redfish,sensors
-Requires-Python: >=3.10
-Provides-Extra: collect
-Requires-Dist: bmc-sensor-audit<0.3,>=0.2.0; extra == 'collect'
-Provides-Extra: dev
-Requires-Dist: pytest>=7; extra == 'dev'
-Description-Content-Type: text/markdown
-
 # fleet-sensor-baseline
 
 **Which units differ from their cohort, and what changed on this unit across time.**
@@ -25,9 +6,18 @@ Description-Content-Type: text/markdown
 list of machines and the history of captures, and answers the two questions the
 referee cannot.
 
-**Released — 0.2.2**, tagged `v0.2.2`, Apache-2.0, on PyPI as
+**Released — 0.2.3**, tagged `v0.2.3`, Apache-2.0, on PyPI as
 `fleet-sensor-baseline`.
 
+**0.2.3 admits the referee's 0.3 line, and stops a closed pipe reading as a
+finding.** The `collect` extra held `bmc-sensor-audit` below 0.3 for eighteen
+days after 0.3.0, and nothing here needed it: two tests read what 0.2 kept
+where. They read the referee as installed now, and the suite passes on
+referees 0.2.7, 0.3.0 and 0.3.5 -- which also lets this extra sit beside
+`odm-cert-generator`, whose releases from 0.2.2 require the 0.3 line. And every
+subcommand, `--help` included, raised `BrokenPipeError` when its reader closed
+the pipe, exiting 1, which this family reads as findings about a rack.
+
 **0.2.2 adds `compare`, the threshold audit across time.** `drift` reads records
 and never opens a walk, so a threshold edited on a sensor that stayed present was
 invisible to it — and invisible to `collect --etag-cache` too, which is why a
@@ -369,7 +359,7 @@ first would pass by finding nothing.
 
 | | count |
 |---|---|
-| tests collected | 363 |
+| tests collected | 447 |
 | of those, requiring `bmc-sensor-audit` | 40 |
 
 **The predicate**: `pytest --collect-only` over the test files git tracks, and
@@ -396,8 +386,12 @@ a walk with the referee's own reader and asserts the fixture still matches.
 
 ## Upstream
 
-Pinned at `bmc-sensor-audit>=0.2.0,<0.3`, and the floor is **derived, not
-chosen**. It has moved three times, each time to consume something reported from
+Pinned at `bmc-sensor-audit>=0.2.0,<0.4`. **The ceiling was `<0.3` until
+2026-09-26**, eighteen days into the referee's 0.3 line, and what held it there
+was this repository's own tests reading where 0.2 kept things -- the prefix
+parser, which moved to `presence-audit` at 0.3.0, and a ceiling typed into the
+pin guard. Both now read the referee as installed, and the suite passes on 0.2.7,
+0.3.0 and 0.3.5. The floor is **derived, not chosen**. It has moved three times, each time to consume something reported from
 here:
 
 - `>=0.1.2` for `--password-env`, so a credential never crosses argv, and for

{fleet_sensor_baseline-0.2.2 → fleet_sensor_baseline-0.2.3}/pyproject.toml

@@ -75,7 +75,17 @@ dependencies = []
 # caller's install line.** `compare` needs the referee too -- it hands two
 # stored walks to `regression` -- so this extra now gates two commands. Both
 # were verified against every release the range admits: 0.2.0, 0.2.1, 0.2.2.
-collect = ["bmc-sensor-audit>=0.2.0,<0.3"]
+#
+# **The ceiling rose to <0.4 on 2026-09-26**, eighteen days after the referee
+# reached 0.3.0. Nothing here was wrong with the referee's 0.3 line: the only
+# reds were two tests reading what 0.2 happened to keep where -- the prefix
+# parser, which moved to `presence-audit` with the 0.3.0 split, and a ceiling
+# typed into the pin guard. Both read the referee as it is now. Measured
+# before the move: 446 passed on 0.2.7 and 8 failed on 0.3.5, all eight those
+# two; after it, the suite passes on 0.2.7, 0.3.0 and 0.3.5. Meanwhile
+# `odm-cert-generator` 0.2.2 already required the referee at >=0.3.0, so this
+# extra could not be installed beside the certificate renderer at all.
+collect = ["bmc-sensor-audit>=0.2.0,<0.4"]
 dev = ["pytest>=7"]
 
 [project.scripts]

{fleet_sensor_baseline-0.2.2 → fleet_sensor_baseline-0.2.3}/src/fleet_sensor_baseline/__init__.py

@@ -15,6 +15,6 @@ from __future__ import annotations
 # read this to decide whether the README may name a tag at all: an unreleased
 # tree that announces `v0.1.0` hands a reader a tag to check out that does not
 # exist. Bump this at step 1 of a release, not at step 9.
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 __all__ = ["__version__"]

{fleet_sensor_baseline-0.2.2 → fleet_sensor_baseline-0.2.3}/src/fleet_sensor_baseline/cli.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import sys
 from pathlib import Path
 from typing import Any, Iterable
@@ -714,13 +715,98 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
+class _StdoutThatOutlivesItsReader:
+    """`sys.stdout`, for a program whose exit code is a claim about a fleet.
+
+    **A reader that stops reading has said something about itself, not about
+    the rack.** `fleet-sensor-baseline baseline ... | head` is an ordinary
+    thing to do, and before this every subcommand died of it -- including
+    `--help`, which is the likeliest thing anyone pipes. The failure arrived
+    two ways, and neither is in the vocabulary `exits.py` defines: a report
+    long enough to fill the pipe buffer raised out of `print` and the
+    interpreter exited `1`, which this tool means as FINDINGS; a shorter one
+    survived to the shutdown flush, printed `Exception ignored` to stderr and
+    exited `120`, which is not a verdict at all.
+
+    Both replace a statement about the fleet with a statement about the
+    terminal. Absorbing rather than refusing is the point: `INCOMPLETE` says
+    the fleet could not be assessed, and a baseline whose reader walked away
+    was assessed perfectly well.
+
+    The sibling package has carried this since its own two occurrences. This
+    is the third in the family, and it shipped in 0.2.2.
+    """
+
+    def __init__(self, stream: Any) -> None:
+        self._stream = stream
+        self.reader_left = False
+
+    def _abandon(self) -> None:
+        """Point the descriptor at nowhere, then stop trying.
+
+        The interpreter flushes `stdout` again on its way out, on bytes this
+        stream may still hold. Without the redirect that second flush raises
+        where no `except` can reach it -- which is the `Exception ignored`
+        line, and the `120`.
+        """
+        self.reader_left = True
+        try:
+            fileno = self._stream.fileno()
+        except (AttributeError, ValueError, OSError):
+            return  # captured by a harness rather than piped; nothing to point
+        try:
+            os.dup2(os.open(os.devnull, os.O_WRONLY), fileno)
+        except OSError:
+            pass
+
+    def write(self, text: str) -> int:
+        if self.reader_left:
+            return len(text)
+        try:
+            return self._stream.write(text)
+        except BrokenPipeError:
+            self._abandon()
+            return len(text)
+
+    def flush(self) -> None:
+        if self.reader_left:
+            return
+        try:
+            self._stream.flush()
+        except BrokenPipeError:
+            self._abandon()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._stream, name)
+
+
 def main(argv: list[str] | None = None) -> int:
-    args = build_parser().parse_args(argv)
+    # Installed before the parser runs, because `--help` prints through it too
+    # and argparse exits from inside `parse_args`.
+    stdout = _StdoutThatOutlivesItsReader(sys.stdout)
+    sys.stdout = stdout
     try:
-        return args.func(args)
-    except StoreError as exc:
-        print(f"{args.command}: {exc}", file=sys.stderr)
+        args = build_parser().parse_args(argv)
+        try:
+            return args.func(args)
+        except StoreError as exc:
+            print(f"{args.command}: {exc}", file=sys.stderr)
+            return INCOMPLETE
+    except BrokenPipeError:
+        # A pipe that broke somewhere the wrapper does not cover is a failure
+        # to deliver, and this tool says so with the code that means it.
+        print("the output could not be written: the pipe closed",
+              file=sys.stderr)
         return INCOMPLETE
+    finally:
+        # **Flush through the wrapper, before handing the stream back.** A
+        # report short enough to sit in the buffer is not written until the
+        # interpreter flushes on its way out -- by which point this wrapper is
+        # gone and the failure lands where no `except` can reach it.
+        try:
+            stdout.flush()
+        finally:
+            sys.stdout = stdout._stream
 
 
 if __name__ == "__main__":  # pragma: no cover

fleet_sensor_baseline-0.2.3/tests/test_closed_pipe.py

@@ -0,0 +1,194 @@
+"""`| head` is not a fault in the fleet.
+
+**The exit code is the claim, and the claim is about a rack.** A reader that
+stops reading has said something about itself, not about the machines, so the
+code this tool returns must not move when somebody pipes a report into `head`.
+
+Until this was guarded it moved two different ways, and 0.2.2 shipped with both.
+A report long enough to fill the pipe buffer raised `BrokenPipeError` out of
+`print`, escaped `main`, and left Python to exit `1` -- and `1` in this
+vocabulary means FINDINGS, so a truncated report was indistinguishable from a
+complete one to anything reading the code. A short report failed later instead,
+at the interpreter's shutdown flush, printing `Exception ignored` and exiting
+`120`, which `exits.normalise` reads as INCOMPLETE. Either way an aggregator
+files a rack on the strength of where the operator's terminal stopped.
+
+`--help` was in the second class, which is the part worth stating plainly: the
+likeliest thing anybody pipes was the likeliest thing to fail.
+
+The sibling package guards this and has since its own two occurrences. This is
+the third in the family. The rule was written down after the second; writing it
+down is not a mechanism, and a test is, which is why this file exists rather
+than a line in a document.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+from conftest import record  # noqa: E402
+
+#: Enough one-line results to carry the rendered output comfortably past a 64KB
+#: pipe buffer, so the failure lands in `print` rather than at the shutdown
+#: flush. Both paths are exercised below; non-vacuity is asserted, not assumed.
+WIDE = 1200
+
+
+def _write_records(where: Path, count: int, *, valid: bool) -> list[str]:
+    paths = []
+    for index in range(count):
+        path = where / f"r{index:05d}.json"
+        if valid:
+            payload = record(f"rack-01/unit{index:05d}",
+                             captured_at="2026-08-20T00:00:00Z",
+                             digest="sha256:" + f"{index:064x}")
+        else:
+            payload = {"format": "fleet-sensor-baseline/fleet-record/1"}
+        path.write_text(json.dumps(payload), encoding="utf-8")
+        paths.append(str(path))
+    return paths
+
+
+@pytest.fixture(scope="module")
+def wide_clean(tmp_path_factory):
+    """A long report whose verdict is CLEAN, and the reason it must be.
+
+    **An unhandled `BrokenPipeError` makes Python exit `1`.** A fixture whose
+    honest verdict is also `1` cannot tell a preserved verdict from a crash --
+    the two agree by coincidence and the assertion passes against the unguarded
+    code. `validate` answers only `0` or `2`, so every fixture here is already
+    clear of the crash code; this one is pinned anyway, because the day
+    `validate` grows a FINDINGS path is the day these tests go quiet without
+    going red.
+    """
+    where = tmp_path_factory.mktemp("wide_clean")
+    return ["validate", *_write_records(where, WIDE, valid=True)]
+
+
+@pytest.fixture(scope="module")
+def wide_incomplete(tmp_path_factory):
+    """The same length, verdict INCOMPLETE.
+
+    Kept because `2` is the verdict an operator most often pipes into `head` --
+    the run that found something wrong is the run worth skimming.
+    """
+    where = tmp_path_factory.mktemp("wide_incomplete")
+    return ["validate", *_write_records(where, WIDE, valid=False)]
+
+
+@pytest.fixture(scope="module")
+def narrow(tmp_path_factory):
+    """A run whose report is short, and whose verdict is CLEAN.
+
+    Too little output to fail during `print`, so it reaches the shutdown flush
+    instead -- the path that produced `Exception ignored` and `120`.
+    """
+    where = tmp_path_factory.mktemp("narrow")
+    return ["validate", *_write_records(where, 2, valid=True)]
+
+
+def _environment() -> dict:
+    return {"PYTHONPATH": str(ROOT / "src"), "PATH": "/usr/bin:/bin"}
+
+
+def _unpiped(argv) -> subprocess.CompletedProcess:
+    return subprocess.run([sys.executable, "-m", "fleet_sensor_baseline.cli", *argv],
+                          capture_output=True, text=True, env=_environment())
+
+
+def _through_head(argv, lines: int) -> tuple[int, str]:
+    """`(writer exit code, writer stderr)` -- the writer's, never the pipe's.
+
+    A shell pipeline reports the LAST command's status, which here is `head`,
+    which is always `0`. Measuring that would make every assertion below
+    vacuously true; this project has three recorded instances of exactly that
+    mistake, so the writer is held open and asked directly.
+    """
+    writer = subprocess.Popen(
+        [sys.executable, "-m", "fleet_sensor_baseline.cli", *argv],
+        stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
+        env=_environment())
+    reader = subprocess.Popen(["head", "-n", str(lines)], stdin=writer.stdout,
+                              stdout=subprocess.DEVNULL)
+    writer.stdout.close()
+    reader.wait()
+    stderr = writer.stderr.read()
+    writer.stderr.close()
+    writer.wait()
+    return writer.returncode, stderr
+
+
+class TestTheReportIsLongEnoughToReachTheDefect:
+    def test_the_wide_fixture_would_fill_a_pipe_buffer(self, wide_clean):
+        """Non-vacuity for everything below. A report that fits inside the 64KB
+        buffer never makes the writer notice the reader has gone, so a suite
+        built on a short report passes against the unguarded code."""
+        rendered = _unpiped(wide_clean)
+        assert len(rendered.stdout) > 65536, (
+            f"the report is {len(rendered.stdout)} bytes and cannot close a "
+            f"pipe before the writer finishes")
+
+    def test_the_incomplete_fixture_is_long_too(self, wide_incomplete):
+        assert len(_unpiped(wide_incomplete).stdout) > 65536
+
+    def test_no_fixture_shares_the_crash_code(self, wide_clean, wide_incomplete,
+                                              narrow):
+        """`1` is what an unhandled exception exits with. If any fixture ever
+        returns it, the assertions below agree with a crash by coincidence."""
+        for argv in (wide_clean, wide_incomplete, narrow):
+            assert _unpiped(argv).returncode != 1
+
+
+class TestAClosedPipeDoesNotMoveTheVerdict:
+    def test_a_long_clean_report_keeps_its_exit_code(self, wide_clean):
+        """**The assertion the whole guard exists for.** Not *no traceback* --
+        a run that printed nothing and exited 120 would satisfy that."""
+        expected = _unpiped(wide_clean).returncode
+        assert expected == 0
+        code, _ = _through_head(wide_clean, 10)
+        assert code == expected, (
+            f"piping the report changed the verdict from {expected} to {code}")
+
+    def test_a_long_incomplete_report_keeps_its_exit_code(self, wide_incomplete):
+        expected = _unpiped(wide_incomplete).returncode
+        assert expected == 2
+        code, _ = _through_head(wide_incomplete, 10)
+        assert code == expected
+
+    def test_a_clean_run_stays_clean(self, narrow):
+        """The direction a refusal-shaped fix would break. Mapping a closed pipe
+        to INCOMPLETE would file a healthy rack as unwalked."""
+        assert _unpiped(narrow).returncode == 0
+        code, _ = _through_head(narrow, 1)
+        assert code == 0
+
+    def test_a_reader_that_leaves_immediately_is_also_clean(self, narrow):
+        """The shutdown-flush path, which is where `--help` failed."""
+        code, stderr = _through_head(narrow, 0)
+        assert code == 0, f"exit {code} for a clean run whose reader left"
+        assert "Exception ignored" not in stderr
+
+
+class TestNothingIsPrintedAboutIt:
+    @pytest.mark.parametrize("lines", [0, 1, 10])
+    def test_no_traceback_reaches_the_operator(self, wide_clean, lines):
+        _, stderr = _through_head(wide_clean, lines)
+        assert stderr == "", stderr
+
+    @pytest.mark.parametrize("argv", ["--help", "validate --help",
+                                      "baseline --help", "collect --help"])
+    def test_help_survives_its_likeliest_reader(self, argv):
+        """`--help | head` is the commonest pipe there is, and it was broken on
+        every subcommand. Parametrised over four because argparse exits from
+        inside `parse_args`, before anything this program wrote could run."""
+        code, stderr = _through_head(argv.split(), 0)
+        assert stderr == "", stderr
+        assert code == 0