dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/env_print.py

@@ -0,0 +1,378 @@
+"""The environment print — a content-addressed record of *under what* a verdict ran (docs/115 §2).
+
+> **DOS records *who did what* (the run-id spine, the lease WAL, the intent
+> ledger, git ancestry). It records nothing about *under what* — which kernel,
+> which Python, which OS, which toolchain adjudicated or produced the record. So
+> two runs in different environments can reach different verdicts on the same
+> input with no trace of the divergence in the fossil. An `EnvPrint` is the
+> missing fact: gathered ONCE at the build boundary (a `WorkspaceFacts` sibling),
+> frozen as data on the `SubstrateConfig`, and stamped onto the durable surfaces
+> so every adjudication is contestable — recompute it under the recorded print
+> and see if the verdict holds.**
+
+This is the object for docs/115 primitive 1. It is deliberately the
+``run_id``/``WorkspaceFacts`` shape, not a new pattern:
+
+  * **A pure, frozen dataclass** (`EnvPrint`) that round-trips through a JSONL line
+    (`to_dict`/`from_dict`, the `RunId.to_dict` idiom). Constructible with NO I/O —
+    a hand-built print for a unit test never shells `git` (the
+    ``WorkspaceFacts(root=…)`` test-construction rule).
+  * **One boundary gatherer** (`gather_env_print`) — the ONLY function here that
+    touches `sys`/`platform`/`git`/the declared tool binaries. Called by the config
+    BUILDERS (`default_config`/`job_config`/`load_workspace_config`), the same
+    boundary `gather_workspace_facts` runs at, never inside a pure verdict (the
+    "I/O at the boundary, data to the pure core" discipline — cf.
+    `git_delta`/`journal_delta` → `liveness.classify`).
+  * **A content-addressed `digest`** — a short, stable hash over the print's fields
+    (Crockford base32, the run-id token alphabet). Two environments with the same
+    `digest` are interchangeable *by declaration*; the kernel does NOT assert they
+    are behaviorally identical (the model-id caveat — a pinned weight set is not a
+    pinned behavior — applies to the whole print). The `digest` is the *`EnvId`*:
+    the cheap key a WAL entry carries, and the value docs/115 primitive 3's
+    `FLEET_ENV_MISMATCH` arbiter gate compares against a declared pin.
+
+What an `EnvPrint` is NOT (docs/115 §2):
+
+  * **Not a sandbox manager.** DOS does not create, snapshot, or enforce
+    environments — that is the host's container/Nix/devcontainer layer (the docs/99
+    actuation boundary: the kernel RECORDS and REFUSES, it does not ACTUATE). This
+    module records the *print* of whatever environment it was run in.
+  * **Not a behavioral guarantee.** A matching `digest` means "the same declared
+    inputs," never "the same output" (the temp-0-nondeterminism + model-id-drift
+    caveats forbid that claim). The print is evidence FOR a reproduction attempt,
+    not a proof OF reproducibility.
+  * **Not mandatory on the pure core.** A `SubstrateConfig` built without gathering
+    (the test path) carries ``env=None``; every consumer treats ``None`` as "not
+    recorded," exactly as ``WorkspaceFacts=None`` is treated. A pure verdict is
+    handed a print to STAMP, the way it is handed a clock — it never REQUIRES one.
+
+The `tools` set is DECLARED (``dos.toml [env] tools = ["git", "node"]``), not an
+open probe of everything on PATH: the kernel records only what a workspace says
+matters, keeping the print small, stable, and free of ambient noise (the
+closed-set-as-data discipline `reasons`/`stamp` ride, applied to the env axis).
+
+Every `EnvPrint` carries a `durable_schema` family (``"env-print"``, version 1)
+like every other durable record, so a print a newer kernel wrote is
+refused-don't-guessed at read, not misparsed (docs/115 primitive 4 closes the loop
+on the print itself).
+
+Pure stdlib + `dos.durable_schema` (a leaf) — no third-party imports. The git read
+is a guarded `subprocess` confined to `gather_env_print`, fail-safe to ``None`` on
+any failure (no git, timeout, non-git dir), the `git_delta` posture.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import platform
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+from dos import durable_schema as _schema
+
+# The durable-schema family + version every env-print record carries (§6/docs/115).
+# Bumped ONLY on a NON-additive shape change; a new optional field (a new declared
+# tool, say) is additive and does NOT bump it. A print tagged higher than this is
+# REFUSED at read (`durable_schema.classify`), never guessed.
+SCHEMA_FAMILY = "env-print"
+ENV_PRINT_SCHEMA = 1
+
+# The digest alphabet — Crockford base32, the same human-safe, case-folding set the
+# run-id token uses (no I/O/O confusion, sortable). The digest is a fixed-width
+# slice of a SHA-256 over the print's canonical fields, so it is short enough to
+# eyeball in a WAL entry and stable across processes/platforms (a hash, not a
+# Python `hash()` — which is salted per-process and would not match across runs).
+_CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+_DIGEST_WIDTH = 12  # 12 base32 chars ≈ 60 bits — ample for an interchangeability key
+
+
+@dataclass(frozen=True)
+class ToolVersion:
+    """One declared tool and the version string probed for it. Pure data.
+
+    ``name`` — the tool a workspace declared it cares about (``"git"``, ``"node"``).
+    ``version`` — the version string `gather_env_print` probed, or ``""`` when the
+        tool was declared but not found / did not answer (recorded as absent, not
+        dropped — "git was declared and missing" is itself a fact a reproduction
+        attempt needs, distinct from "git was never declared").
+    """
+
+    name: str
+    version: str = ""
+
+    def to_dict(self) -> dict:
+        return {"name": self.name, "version": self.version}
+
+    @classmethod
+    def from_obj(cls, obj: Any) -> "ToolVersion | None":
+        if not isinstance(obj, Mapping):
+            return None
+        name = obj.get("name")
+        if not isinstance(name, str) or not name:
+            return None
+        ver = obj.get("version")
+        return cls(name=name, version=ver if isinstance(ver, str) else "")
+
+
+@dataclass(frozen=True)
+class EnvPrint:
+    """A content-addressed record of the environment a verdict was computed in.
+
+    The `WorkspaceFacts` sibling on `SubstrateConfig` (`.env`): a frozen set of
+    facts about the *runtime*, gathered once at the build boundary and stamped onto
+    the durable surfaces. Pure — constructible with no I/O for a test.
+
+      kernel_version — `dos.__version__` (e.g. ``"0.8.0"``); the pip/dist version.
+      kernel_sha     — the git SHA of the KERNEL's own source tree (HEAD), or
+                       ``None`` when it cannot be determined (not a git checkout, a
+                       wheel install). The one fact that catches the stale-editable-
+                       `.pth` hazard directly: two worktrees at the same
+                       `kernel_version` but different commits print different SHAs,
+                       so a verdict from the wrong tree is self-evident in the fossil.
+      python         — the Python version (``"3.13.1"``), `sys.version_info` joined,
+                       NOT the full multi-line `sys.version` banner (stable across
+                       builds of the same x.y.z).
+      platform       — ``"<system>-<machine>"`` (``"win32-AMD64"`` / ``"linux-x86_64"``).
+      tools          — the DECLARED tool versions (`ToolVersion`s), in declaration
+                       order. Empty when a workspace declared none.
+
+    The `digest` (a property, not a stored field) is the `EnvId`: a stable hash over
+    (kernel_version, kernel_sha, python, platform, tools). Computed, never stored, so
+    it can never drift out of sync with the fields it summarizes — a record reads the
+    fields back and recomputes; a stored digest that disagreed with its fields would
+    be the exact silent-drift the kernel forbids.
+    """
+
+    kernel_version: str
+    kernel_sha: str | None = None
+    python: str = ""
+    platform: str = ""
+    tools: tuple[ToolVersion, ...] = ()
+
+    @property
+    def digest(self) -> str:
+        """The content-addressed `EnvId` — a stable base32 hash over the fields.
+
+        Deterministic across processes and platforms (a SHA-256 over a canonical
+        string, NOT Python's per-process-salted `hash()`), so the same environment
+        always prints the same digest and `FLEET_ENV_MISMATCH` (docs/115 §5) can
+        compare a worker's digest to a declared pin by equality. The tool set is
+        sorted into the canonical string so declaration ORDER does not change the
+        digest (two configs that declare ``["git","node"]`` vs ``["node","git"]``
+        describe the same environment and must hash alike).
+        """
+        tools_canon = ",".join(
+            f"{t.name}={t.version}" for t in sorted(self.tools, key=lambda t: t.name)
+        )
+        canon = "\x1f".join((
+            self.kernel_version,
+            self.kernel_sha or "",
+            self.python,
+            self.platform,
+            tools_canon,
+        ))
+        h = int.from_bytes(hashlib.sha256(canon.encode("utf-8")).digest(), "big")
+        out = []
+        for _ in range(_DIGEST_WIDTH):
+            out.append(_CROCKFORD[h & 0x1F])
+            h >>= 5
+        return "".join(reversed(out))
+
+    def to_dict(self) -> dict:
+        """The shape stamped onto a durable record (carries the schema tag).
+
+        Includes the computed `digest` as a convenience for a `--json` reader that
+        wants the key without recomputing — but `from_dict` RECOMPUTES it from the
+        fields and ignores any stored value, so a tampered/stale `digest` in a
+        record can never be believed (the field is authoritative, the stored digest
+        is a courtesy). The `durable_schema` tag rides here so a stamped print
+        self-declares its format (the `intent_entry` idiom).
+        """
+        return {
+            **_schema.tag(SCHEMA_FAMILY, ENV_PRINT_SCHEMA),
+            "kernel_version": self.kernel_version,
+            "kernel_sha": self.kernel_sha,
+            "python": self.python,
+            "platform": self.platform,
+            "tools": [t.to_dict() for t in self.tools],
+            "digest": self.digest,
+        }
+
+    @classmethod
+    def from_dict(cls, obj: Mapping[str, Any]) -> "EnvPrint | None":
+        """Parse an `EnvPrint` from a stamped record. None if absent/malformed.
+
+        Tolerant the way `SchemaTag.from_obj` is — a missing/garbled print yields
+        ``None``, not a crash (a fossil written by a kernel that did not stamp prints
+        simply has no print to read). The `digest` is RECOMPUTED from the parsed
+        fields; any stored ``"digest"`` is ignored, so the key can never disagree
+        with the data it summarizes.
+        """
+        if not isinstance(obj, Mapping):
+            return None
+        kv = obj.get("kernel_version")
+        if not isinstance(kv, str) or not kv:
+            return None
+        sha = obj.get("kernel_sha")
+        tools_raw = obj.get("tools")
+        tools: list[ToolVersion] = []
+        if isinstance(tools_raw, Iterable) and not isinstance(tools_raw, (str, bytes)):
+            for t in tools_raw:
+                tv = ToolVersion.from_obj(t)
+                if tv is not None:
+                    tools.append(tv)
+        return cls(
+            kernel_version=kv,
+            kernel_sha=sha if isinstance(sha, str) and sha else None,
+            python=obj.get("python") if isinstance(obj.get("python"), str) else "",
+            platform=obj.get("platform") if isinstance(obj.get("platform"), str) else "",
+            tools=tuple(tools),
+        )
+
+
+# ---------------------------------------------------------------------------
+# The boundary gatherer — the ONE I/O home (the `gather_workspace_facts` rule).
+# Everything above is pure; everything that touches sys/platform/git is here.
+# ---------------------------------------------------------------------------
+
+_GIT_TIMEOUT_S = 10  # the `git_delta` cap — a hung git never blocks a config build
+
+
+def _python_version() -> str:
+    """``"3.13.1"`` — the x.y.z, not the full `sys.version` banner."""
+    vi = sys.version_info
+    return f"{vi.major}.{vi.minor}.{vi.micro}"
+
+
+def _platform_tag() -> str:
+    """``"<system>-<machine>"`` — ``"linux-x86_64"`` / ``"win32-AMD64"``.
+
+    `sys.platform` for the OS (matches the value DOS already reports in `doctor`'s
+    environment block and the `_filelock` win32 branch keys on) + `platform.machine`
+    for the arch, so a print distinguishes the same OS on different CPUs.
+    """
+    machine = platform.machine() or "unknown"
+    return f"{sys.platform}-{machine}"
+
+
+def _kernel_sha(kernel_root: Path | None) -> str | None:
+    """The git HEAD SHA of the kernel's OWN tree, or ``None``. Guarded `subprocess`.
+
+    Anchored on the kernel package's own location (the directory `dos/` lives in),
+    NOT the served workspace — the question is "which commit of DOS is running,"
+    which is a property of the installed kernel, not of the repo it is adjudicating.
+    Fail-safe to ``None`` on every failure (no git, not a checkout, timeout) — a
+    wheel-installed kernel has no SHA and that is a recorded fact, not an error (the
+    `git_delta` returns-[] posture, lifted to "returns None").
+    """
+    root = kernel_root or Path(__file__).resolve().parent
+    try:
+        out = subprocess.run(
+            ["git", "-C", str(root), "rev-parse", "HEAD"],
+            capture_output=True,
+            text=True,
+            timeout=_GIT_TIMEOUT_S,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if out.returncode != 0:
+        return None
+    sha = out.stdout.strip()
+    return sha or None
+
+
+def _tool_version(name: str) -> str:
+    """Probe ``<name> --version`` → its first non-empty output line, or ``""``.
+
+    Guarded `subprocess`, fail-safe to ``""`` (declared-but-absent is a fact, not an
+    error). Returns the raw first line the tool prints — the kernel does not parse a
+    semantic version out of it (that would be tool-specific policy); the print
+    records what the tool SAID, and two runs of the same tool print the same line.
+    """
+    try:
+        out = subprocess.run(
+            [name, "--version"],
+            capture_output=True,
+            text=True,
+            timeout=_GIT_TIMEOUT_S,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    if out.returncode != 0:
+        return ""
+    for line in (out.stdout or out.stderr or "").splitlines():
+        s = line.strip()
+        if s:
+            return s
+    return ""
+
+
+# Per-process memo of gathered prints, keyed by (tools, kernel_root). The print
+# describes the RUNTIME — kernel version + kernel-SHA + Python + OS/arch + the
+# declared tools' versions — none of which change while the process lives (the
+# kernel SHA cannot move under a running server; `platform.machine()` is itself
+# CPython-cached). So the docstring's "probe the runtime ONCE" is literally true
+# per process: the FIRST gather pays the `git rev-parse` subprocess + the WMI
+# platform query (~tens of ms on Windows); every later gather returns the frozen
+# print for free. This is the single biggest cost on the MCP server's per-tool-call
+# config build (`load_workspace_config` → `default_config` → here), which used to
+# re-spawn `git` on every call. Cleared by `_clear_env_print_cache()` for the rare
+# test that wants to force a re-probe.
+_GATHER_CACHE: "dict[tuple, EnvPrint]" = {}
+
+
+def _clear_env_print_cache() -> None:
+    """Drop the per-process gather memo (test hook; a real process never needs it)."""
+    _GATHER_CACHE.clear()
+
+
+def gather_env_print(
+    *,
+    tools: Iterable[str] = (),
+    kernel_root: Path | None = None,
+) -> EnvPrint:
+    """Probe the runtime once and freeze the discovered `EnvPrint`. The I/O HOME.
+
+    Called by the config BUILDERS (the boundary already allowed to touch the disk),
+    never by a pure verdict — the `gather_workspace_facts` discipline. `tools` is the
+    workspace's DECLARED tool list (from ``dos.toml [env] tools``); each is probed
+    via ``<name> --version`` and recorded (present or absent). `kernel_root` overrides
+    where the kernel-SHA git read is anchored (tests / an oddly-installed kernel);
+    defaults to this module's own directory.
+
+    Memoized per process on ``(tools, kernel_root)`` (see `_GATHER_CACHE`): the print
+    is a property of the running KERNEL, constant for the process's lifetime, so the
+    git subprocess + platform probe run ONCE and every later call is free. This is the
+    "gathered once at the build boundary" contract made literal — and what keeps a
+    long-lived server (the MCP server builds a config per tool call) from re-spawning
+    `git rev-parse` on every call.
+
+    `dos.__version__` is read lazily here (not at module import) to avoid a circular
+    import — `dos/__init__.py` imports `config`, which will import this; reaching back
+    up to the package at import time would cycle. At CALL time the package is fully
+    loaded, the same lazy-resolve `gather_workspace_facts` uses for `self_modify`.
+    """
+    # Materialize `tools` ONCE — it is typed `Iterable[str]`, so a one-shot
+    # generator is legal, and we both key the cache on it and (on a miss) iterate
+    # it to probe; reusing the same tuple keeps a generator caller correct.
+    tool_names = tuple(tools)
+    key = (tool_names, kernel_root)
+    cached = _GATHER_CACHE.get(key)
+    if cached is not None:
+        return cached
+
+    from dos import __version__ as kernel_version  # noqa: PLC0415 — lazy, anti-cycle
+
+    probed = tuple(ToolVersion(name=n, version=_tool_version(n)) for n in tool_names)
+    print_ = EnvPrint(
+        kernel_version=kernel_version,
+        kernel_sha=_kernel_sha(kernel_root),
+        python=_python_version(),
+        platform=_platform_tag(),
+        tools=probed,
+    )
+    _GATHER_CACHE[key] = print_
+    return print_

dos/event_severity.py

@@ -0,0 +1,258 @@
+"""Operator-value severity for a dispatch-family bookkeeping event (noise filter).
+
+The dispatch family (`/dispatch`, `/dispatch-loop`, `/replan`, `/next-up`) commits
+and pushes an archive line for *every* iteration — even a 0-pick drain, a repeated
+rate-limit, or a no-op gardening sweep. Measured 2026-06-03: 82 of the last 200
+commits on `main` (41%) were this bookkeeping, ~20-28/hr at peak, and 67% of
+dispatch-loop archives shipped 0 picks. Peers pulling `main` absorb the whole flood.
+
+`classify_event()` is the keystone fix — a **pure** function that turns the event's
+already-computed facts (the `verdict=<X>` token the write step holds, the pick count,
+whether this is the *first* occurrence of a blocker this loop) into one typed
+`Severity`. Each operator-facing *sink* (push, local-commit, terminal, report,
+artifact) then admits or suppresses the event by comparing its severity against a
+per-sink threshold (an env var) — exactly the way a logging framework filters by
+level. The default thresholds make the common case quiet: only `SHIPPED` and a
+*newly-surfaced* blocker reach `origin`; a 0-pick drain or no-op replan still commits
+locally (audit kept) but never pushes.
+
+    SHIPPED      material change landed (>=1 pick, verdict=LIVE, or a plan
+                 promotion) — the thing the operator wants surfaced first
+    BLOCKED-NEW  a blocker / operator-decision / crash seen for the FIRST time
+                 this loop — actionable, may need a decision -> reaches peers
+    NOTICE       state-changing but routine — a STALE-STAMP false-drain, >=1
+                 finding/closure, a soft-claim, a --next-up-only packet
+    NOOP         a non-event — 0-pick DRAIN, a REPEATED blocker/rate-limit, a
+                 gardening-only quiet-sweep, a 0-net soft-claim
+
+⚓ Severity is `(verdict, first_occurrence)`, not verdict alone. A blocker the
+operator has not seen is high-value; the *same* blocker recurring every iteration is
+pure noise. The `first_occurrence` predicate is what collapses the repeated-blocked /
+repeated-RATE_LIMITED flood (13 of 16 chained archives on 2026-06-03) into `NOOP`.
+`SHIPPED` outranks `BLOCKED-NEW` because a landed pick is what the operator wants on
+top.
+
+⚓ Pure kernel, I/O on the edge (the dos composition idiom — mirrors `classify_packet`
+in `gate_classify.py`): `classify_event(EventState) -> Severity` is a frozen dataclass
+in, an enum out — no subprocess, no file/clock/git call. Every signal (`verdict`,
+`picks_shipped`, `first_occurrence`, the replan/next-up counters) is reduced to a
+scalar/bool by the caller at the write step, which is also the only place that knows
+them. The one concession to I/O is `sink_threshold()`, a single `os.environ.get`
+(the `fanout_state` module-level idiom) — kept beside the classifier so a consumer has
+one import. The classifier itself stays pure and is the unit-test surface.
+
+⚓ Reuse the verdict vocabulary, never re-list it. The classifier *input* is the
+`verdict=<X>` token the archive subject already carries; `normalize_token` (this
+package's `tokens.py`) is the one chokepoint that upper-cases it and folds the legacy
+`WEDGE -> BLOCKED` alias, so a historical `verdict=WEDGE` event classifies identically
+to `BLOCKED`. Do not duplicate the token set here.
+"""
+from __future__ import annotations
+
+import enum
+import os
+from dataclasses import dataclass
+
+from .tokens import normalize_token
+
+
+class Severity(str, enum.Enum):
+    """One typed operator-value level. `str`-valued so it round-trips as a bare
+    token through an env var and a commit subject (the `GateVerdict` pattern)."""
+
+    SHIPPED = "SHIPPED"
+    BLOCKED_NEW = "BLOCKED-NEW"
+    NOTICE = "NOTICE"
+    NOOP = "NOOP"
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+# Threshold ordering — a sink with MIN=NOTICE admits NOTICE/BLOCKED-NEW/SHIPPED and
+# rejects NOOP. Higher rank = higher operator value = harder to suppress.
+_RANK: dict[Severity, int] = {
+    Severity.NOOP: 0,
+    Severity.NOTICE: 1,
+    Severity.BLOCKED_NEW: 2,
+    Severity.SHIPPED: 3,
+}
+
+# The verdict tokens that mean "a blocker / crash / rate-limit happened" — first
+# occurrence is BLOCKED-NEW, a repeat is NOOP. Canonical (post-`normalize_token`)
+# spellings only; WEDGE folds to BLOCKED upstream so it is covered by "BLOCKED".
+_BLOCKER_VERDICTS = frozenset({"BLOCKED", "RACE", "ERROR", "RATE_LIMITED"})
+
+
+@dataclass(frozen=True)
+class EventState:
+    """Every input the write step already holds — no I/O happens to build this.
+
+    Mirrors `PickDisposition` / the `classify_packet` input: the caller reduces all
+    time/git/file state to these scalars at the I/O edge, then hands them in frozen.
+    """
+
+    family: str  # "dispatch-loop" | "dispatch" | "replan" | "next-up"
+    verdict: str = ""  # raw token from the archive subject (LIVE/DRAIN/BLOCKED/...)
+    picks_shipped: int = 0
+    # False = this verdict was already seen earlier this loop -> demote a blocker to
+    # NOOP. Defaults True so an unknown caller fails toward surfacing (never hides).
+    first_occurrence: bool = True
+    # --- replan §-counters (the gardening-sweep shape) -----------------------
+    new_findings: int = 0  # findings closed/added this sweep
+    substantive_ships: int = 0  # plan phases this sweep marked shipped
+    surfaced: int = 0  # inbox promotions this sweep (a real plan change)
+    # --- next-up render --------------------------------------------------------
+    soft_claims: int = 0  # picks soft-claimed by the rendered packet
+    # Did the staged pathspec actually differ from HEAD? False -> a no-op write.
+    staged_changed: bool = True
+
+
+def classify_event(ev: EventState) -> Severity:
+    """PURE — the event -> severity mapping verbatim. No file/git/clock/env call."""
+    fam = (ev.family or "").strip().lower()
+    v = normalize_token(ev.verdict) or ""
+
+    if fam in ("dispatch", "dispatch-loop"):
+        if ev.picks_shipped > 0 or v == "LIVE":
+            return Severity.SHIPPED
+        if v in _BLOCKER_VERDICTS:
+            # First time this loop -> actionable; a repeat -> noise.
+            return Severity.BLOCKED_NEW if ev.first_occurrence else Severity.NOOP
+        if v == "STALE-STAMP":
+            # A false-drain: routes a /replan (operator-relevant -> NOTICE) but the
+            # following /replan, not this stamp, carries the real signal to peers.
+            return Severity.NOTICE
+        # DRAIN / 0-pick / unknown-token fallthrough — the dominant non-event.
+        return Severity.NOOP
+
+    if fam == "replan":
+        if ev.surfaced > 0:
+            return Severity.SHIPPED  # an inbox promotion is a real plan change
+        if ev.new_findings > 0 or ev.substantive_ships > 0:
+            return Severity.NOTICE
+        # Gardening-only quiet-sweep (closed==0, added==0, surfaced==0): the §1.5
+        # SKIP gate already dropped the truly-empty case upstream; this is the
+        # "ran but only touched anchors/stale-claims" sweep — local audit, no push.
+        return Severity.NOOP
+
+    if fam == "next-up":
+        if not ev.staged_changed:
+            return Severity.NOOP  # the renderer staged nothing (already-active picks)
+        return Severity.NOTICE if ev.soft_claims > 0 else Severity.NOOP
+
+    # Unknown family — fail safe: surface it rather than silently swallow.
+    return Severity.NOTICE
+
+
+# ---------------------------------------------------------------------------
+# Subject lead-token — the mechanical commit-subject headline.
+#
+# ⚓ Why this is a kernel function, not a SKILL.md prose rule. The Phase-1 fix
+# pinned a *prose* rule to the replan write-step ("lead with the severity token,
+# the run ordinal NEVER appears"). The live git log on 2026-06-03 proved prose
+# does not fire: `docs/_plans: 185th /replan …` and `… (184th /replan)` still
+# leaked the monotonic ordinal AFTER Phase 1 shipped. A model retyping a subject
+# every iteration drifts; a function cannot. So the lead token is COMPUTED here —
+# the ordinal is structurally absent because this function never takes it as an
+# input. The write-step asks `severity_gate.py subject …` for the headline and
+# prepends only the immutable family prefix (`docs/_plans: replan <date> — `).
+#
+# PURE, like `classify_event` — the same `EventState` in, a short headline string
+# out. No clock/git/env/file call. The token is operator-facing English keyed off
+# the SAME severity the gate computes, so the headline and the gate decision can
+# never disagree about what happened.
+# ---------------------------------------------------------------------------
+def subject_lead_token(ev: EventState) -> str:
+    """The severity-shaped headline for `ev`'s commit subject (the lead phrase
+    after the immutable `docs/<family>: …` prefix). PURE — derived from the same
+    facts `classify_event` reads, so it always agrees with the gate verdict.
+
+    The run ordinal is *structurally* impossible here: it is not a field of
+    `EventState`, so a caller building the subject from this token cannot leak it
+    (the recurring `(185th /replan)` flood the prose rule failed to stop)."""
+    sev = classify_event(ev)
+    fam = (ev.family or "").strip().lower()
+    v = normalize_token(ev.verdict) or ""
+
+    if fam in ("dispatch", "dispatch-loop"):
+        if sev is Severity.SHIPPED:
+            n = ev.picks_shipped
+            return f"{n} pick{'s' if n != 1 else ''} shipped" if n > 0 else "shipped"
+        if sev is Severity.BLOCKED_NEW:
+            # A FIRST-seen blocker — name the blocker class so the operator can act.
+            # A bare "BLOCKED" verdict needs no parenthetical (it would read
+            # "blocked (blocked)"); a more specific token (RATE_LIMITED / RACE /
+            # ERROR) is surfaced so the operator sees WHICH wall they hit.
+            if not v or v == "BLOCKED":
+                return "blocked"
+            return f"blocked ({v.lower()})"
+        if v == "STALE-STAMP":
+            return "stale-stamp false-drain (/replan recommended)"
+        return "drained"  # NOOP — the dominant 0-pick non-event
+
+    if fam == "replan":
+        if sev is Severity.SHIPPED:
+            return f"inbox promoted: {ev.surfaced}"
+        if sev is Severity.NOTICE:
+            # State-changing gardening — lead with the counts that moved.
+            return f"{ev.new_findings} closed / {ev.substantive_ships} shipped"
+        return "quiet sweep"  # NOOP — gardening-only; NO ordinal
+
+    if fam == "next-up":
+        if sev is Severity.NOTICE:  # a real soft-claim
+            n = ev.soft_claims
+            return f"soft-claims ({n} pick{'s' if n != 1 else ''})"
+        return "no-op (lane drained)"  # NOOP
+
+    # Unknown family — surface the raw severity so nothing is silently swallowed.
+    return sev.value.lower()
+
+
+# ---------------------------------------------------------------------------
+# Per-sink thresholds — the one I/O concession (an env read), kept beside the
+# classifier so a consumer has a single import. Defaults make the common case quiet.
+# ---------------------------------------------------------------------------
+# Each sink: (neutral env key, JOB_-prefixed back-compat key, quiet default). The
+# kernel-NEUTRAL `DISPATCH_*_MIN_SEVERITY` is the PRIMARY namespace; the host-branded
+# `JOB_DISPATCH_*_MIN_SEVERITY` is a documented BACK-COMPAT fallback (the same
+# generic-primary / JOB_-fallback shape `lane_journal` uses for its journal-path env).
+# Before the userland-coupling audit 2026-06-08 the JOB_ key was the SOLE namespace,
+# so a generic workspace had no neutral surface for these thresholds.
+_SINK_ENV: dict[str, tuple[str, str, Severity]] = {
+    # what peers pulling main see — the highest bar
+    "push": ("DISPATCH_PUSH_MIN_SEVERITY", "JOB_DISPATCH_PUSH_MIN_SEVERITY", Severity.BLOCKED_NEW),
+    # local history / audit — keep everything (coalesced, not per-iter, in Phase 2)
+    "commit": ("DISPATCH_COMMIT_MIN_SEVERITY", "JOB_DISPATCH_COMMIT_MIN_SEVERITY", Severity.NOOP),
+    # the live heartbeat stream
+    "terminal": ("DISPATCH_TERMINAL_MIN_SEVERITY", "JOB_DISPATCH_TERMINAL_MIN_SEVERITY", Severity.NOTICE),
+    # the end-of-run report block (absence-as-signal Attention line)
+    "report": ("DISPATCH_REPORT_MIN_SEVERITY", "JOB_DISPATCH_REPORT_MIN_SEVERITY", Severity.NOTICE),
+    # the docs/ README tree (the result.json envelope is EXEMPT — load-bearing)
+    "artifact": ("DISPATCH_ARTIFACT_MIN_SEVERITY", "JOB_DISPATCH_ARTIFACT_MIN_SEVERITY", Severity.NOTICE),
+}
+
+SINKS: tuple[str, ...] = tuple(_SINK_ENV)
+
+
+def sink_threshold(sink: str) -> Severity:
+    """The configured MIN severity a sink admits. The ONLY I/O — an env read. The
+    kernel-neutral `DISPATCH_*_MIN_SEVERITY` wins; the host-branded
+    `JOB_DISPATCH_*_MIN_SEVERITY` is checked as a documented back-compat fallback.
+    An unset or unparseable value falls back to the (quiet) default for that sink."""
+    try:
+        neutral_key, job_key, default = _SINK_ENV[sink]
+    except KeyError as exc:
+        raise ValueError(f"unknown sink {sink!r}; known: {', '.join(SINKS)}") from exc
+    raw = (os.environ.get(neutral_key) or os.environ.get(job_key) or "").strip().upper()
+    if not raw:
+        return default
+    try:
+        return Severity(raw)
+    except ValueError:
+        return default
+
+
+def admits(sink: str, sev: Severity) -> bool:
+    """True iff an event of `sev` clears `sink`'s threshold (rank >= threshold rank)."""
+    return _RANK[sev] >= _RANK[sink_threshold(sink)]