dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/breaker.py

@@ -0,0 +1,311 @@
+"""BRK — the circuit breaker: *this keeps failing; stop, and escalate the rung.*
+
+docs/223 — idea **H2** from the Claude Code source audit (docs/189). A circuit
+breaker is the oldest pattern in reliability engineering: count failures, and when
+they pile up, *stop trying the same thing* — open the circuit so the caller does
+something else instead of hammering a broken path. DOS already has this pattern
+**six times over**, hand-coded inline in `loop_decide`: `consecutive_unclear`,
+`consecutive_overloaded`, `consecutive_dirty_zero`, `consecutive_stale_stamp` —
+each is the same ~15 lines (bump a counter, compare to a max, stop if reached,
+reset on a clean outcome), differing only in *which* counter, *what* threshold, and
+*what to do when it trips*. That repetition is the smell this module removes: the
+control logic is **mechanism** (identical everywhere), and the counter / threshold /
+trip-action are **policy** (different everywhere). Lift the mechanism into one pure
+leaf; make the policy data.
+
+This is the `malloc` move, stated plainly. `malloc` is in every C program because
+it is mechanism (hand out bytes) with policy (what you allocate) pushed out. A
+breaker hard-wired to "stop the dispatch loop after 3 UNCLEAR iterations" can never
+be universal — the 3, the UNCLEAR, and the dispatch loop are someone's policy baked
+into the mechanism. A breaker that knows only "this failure class has now happened N
+times consecutively (or M times total); the policy says that's too many" *can* be,
+because the caller names the class, the thresholds, and the response. The kernel
+counts; it never knows what failed.
+
+It is `liveness`/`productivity`'s shape — a pure verdict over already-gathered
+state — but for a different question. Where those ask "is the run moving / still
+productive?", BRK asks "has this *kind of thing* failed too many times to keep
+trying?":
+
+    liveness.classify      (ProgressEvidence, policy)   -> LivenessVerdict
+    productivity.classify  (WorkHistory, policy)         -> ProductivityVerdict
+    breaker.record_failure (BreakerState, policy)        -> BreakerTransition
+                           ^ THIS module
+
+**Two counters, lifted faithfully from CC** (`denialTracking.ts`). CC tracks
+`consecutiveDenials` (reset on a success) AND `totalDenials` (never reset), and
+trips on *either* (`shouldFallbackToPrompting`). The two catch different
+pathologies, and you need both:
+
+  - **consecutive** catches a *sustained* failure — N in a row with no recovery, a
+    path that is simply broken right now. Resets the moment something succeeds (the
+    incident cleared).
+  - **total** catches a *flapping* failure — fail, succeed, fail, succeed… — which
+    never trips a consecutive-only breaker but is still pathological (the path is
+    unreliable, just not consistently down). The cumulative count, which never
+    resets, is the only thing that sees it.
+
+A consecutive-only breaker (today's `loop_decide` shape) is blind to flapping; BRK
+fixes that by carrying both, exactly as CC does.
+
+**The DOS addition: the trip ESCALATES a rung, it doesn't just stop** (idea H3,
+folded in). CC's breaker falls back from the classifier to *prompting the human*.
+DOS already has a richer ladder for "who adjudicates when the cheaper mechanism is
+stuck" — the trust ladder ORACLE → JUDGE → HUMAN (`docs/86`, `dos.judges`). So an
+open breaker does not just say STOP; it names *where to escalate* — keep going on
+the same rung (NONE — the breaker is advisory and the caller may continue), kick the
+decision up to a non-deterministic JUDGE, or surface to a HUMAN. "Don't keep
+refusing identically — escalate the rung." The kernel computes the *trip*; the host
+decides what an escalation MEANS (re-dispatch under a judge, queue an operator
+decision) — the same advisory line `liveness`/`productivity` hold: BRK reports, it
+never kills a process or refuses a lease.
+
+**Byte-clean / no-I/O / no-policy-names.** The state is two integers the caller
+threads through its own loop; `record_failure` / `record_success` are pure folds —
+no clock, no file, no host vocabulary. The breaker never sees the failure's
+*identity* (it is handed a count, not an UNCLEAR token), so it cannot smuggle in a
+host assumption. A workspace declares the thresholds + escalation in `dos.toml
+[breaker]` per failure class (the closed-config-as-data pattern); the defaults are
+the CC constants (3 consecutive / 20 total).
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, replace
+from typing import Optional
+
+
+class BreakerState(str, enum.Enum):
+    """Is the circuit CLOSED (keep going) or OPEN (tripped)?
+
+    The classic two-state breaker. `str`-valued so it round-trips through a CLI
+    stdout token / exit-code map without a lookup table (the `liveness.Liveness` /
+    `productivity.Productivity` idiom). (No HALF_OPEN state: that is a *recovery*
+    probe — "let one request through to test the waters" — which is a host
+    actuation, not a kernel verdict. BRK reports the trip; the host decides whether
+    to retry, exactly the advisory line.)
+    """
+
+    CLOSED = "CLOSED"  # failures are under the limits — the path is still usable
+    OPEN = "OPEN"      # a limit was reached — stop hammering this path, escalate
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+class Escalation(str, enum.Enum):
+    """Where an OPEN breaker says to escalate — the trust-ladder rung (docs/86).
+
+    The DOS enrichment of CC's binary "fall back to prompting": instead of one
+    fallback, name the rung. The kernel computes which rung the *policy* declared
+    for this failure class; the host decides what acting on it means. ORACLE→JUDGE
+    →HUMAN is monotonic in trust-cost — a policy escalates UP the ladder, never
+    down (you don't answer a stuck human with a deterministic re-check).
+    """
+
+    NONE = "NONE"    # advisory only — report OPEN, let the caller decide (the default floor)
+    JUDGE = "JUDGE"  # kick the stuck decision to a non-deterministic adjudicator (dos.judges)
+    HUMAN = "HUMAN"  # surface to an operator — the irreducible seed (the dos decisions queue)
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+@dataclass(frozen=True)
+class BreakerPolicy:
+    """The thresholds + escalation that define ONE failure class's breaker — policy, not mechanism.
+
+    The same "mechanism is kernel, thresholds are config" split as `liveness`'s
+    windows and `productivity`'s floor. The defaults are the CC `denialTracking.ts`
+    constants (3 consecutive, 20 total). A workspace declares one of these per
+    failure class in `dos.toml [breaker]` (closed-config-as-data, like
+    `[lanes]`/`[liveness]`); the host names the class, the kernel just counts.
+
+      max_consecutive — trip when this many failures occur IN A ROW (reset by any
+                        success). Catches a *sustained* outage. CC's
+                        `maxConsecutive`. 0 disables the consecutive rung (only the
+                        total rung can trip).
+      max_total       — trip when this many failures occur in TOTAL over the
+                        breaker's life (never reset). Catches a *flapping* failure a
+                        consecutive count misses. CC's `maxTotal`. 0 disables the
+                        total rung.
+      on_trip         — the `Escalation` rung an OPEN verdict names (NONE / JUDGE /
+                        HUMAN). Default NONE — advisory, the kernel's safe floor.
+
+    At least one rung must be enabled (a policy with both maxima 0 can never trip,
+    which is almost certainly a config mistake — refuse it rather than silently
+    build a breaker that does nothing).
+    """
+
+    max_consecutive: int = 3       # CC maxConsecutive — N-in-a-row (sustained outage)
+    max_total: int = 20            # CC maxTotal — cumulative cap (flapping failure)
+    on_trip: Escalation = Escalation.NONE
+
+    def __post_init__(self) -> None:
+        if self.max_consecutive < 0 or self.max_total < 0:
+            raise ValueError("breaker thresholds must be non-negative")
+        if self.max_consecutive == 0 and self.max_total == 0:
+            raise ValueError(
+                "a breaker with both thresholds 0 can never trip — enable at least "
+                "one rung (max_consecutive or max_total)"
+            )
+
+
+DEFAULT_POLICY = BreakerPolicy()
+
+
+@dataclass(frozen=True)
+class BreakerCounts:
+    """The breaker's carried state — two integers the caller threads through its loop.
+
+    The whole state, by design: the breaker is a fold over a failure/success stream,
+    and these two counts are everything the fold needs (the `loop_decide.LoopState`
+    counters, extracted and named generically). Immutable — every transition returns
+    a NEW `BreakerCounts`, so a caller never re-derives the count by hand and the
+    state is replay-testable on frozen fixtures.
+
+      consecutive — failures since the last success (reset by `record_success`).
+      total       — failures over the breaker's whole life (never reset).
+    """
+
+    consecutive: int = 0
+    total: int = 0
+
+    def __post_init__(self) -> None:
+        if self.consecutive < 0 or self.total < 0:
+            raise ValueError("breaker counts must be non-negative")
+
+
+@dataclass(frozen=True)
+class BreakerVerdict:
+    """The verdict for one transition: CLOSED/OPEN + WHY + where to escalate.
+
+    `state` is the typed `BreakerState`. `escalation` is the rung an OPEN verdict
+    names (always NONE when CLOSED — there is nothing to escalate). `reason` is the
+    one-line operator-facing summary. `tripped_on` names which rung fired
+    ("consecutive"/"total"/None) so the consumer/forensics can tell a sustained
+    outage from a flapping one — legible distrust, the `liveness`/`productivity`
+    echo-the-evidence discipline.
+    """
+
+    state: BreakerState
+    escalation: Escalation
+    reason: str
+    tripped_on: Optional[str] = None  # "consecutive" | "total" | None (CLOSED)
+
+    @property
+    def is_open(self) -> bool:
+        return self.state is BreakerState.OPEN
+
+    def to_dict(self) -> dict:
+        return {
+            "state": self.state.value,
+            "escalation": self.escalation.value,
+            "reason": self.reason,
+            "tripped_on": self.tripped_on,
+        }
+
+
+@dataclass(frozen=True)
+class BreakerTransition:
+    """What `record_failure`/`record_success` return: the new counts + the verdict.
+
+    Bundling the two means the caller never has to re-thread the counts AND
+    re-classify them — it gets the next state to carry and the decision to act on in
+    one object (the `loop_decide.LoopDecision` shape: `next_state` + the action).
+    """
+
+    counts: BreakerCounts
+    verdict: BreakerVerdict
+
+
+def _classify(counts: BreakerCounts, policy: BreakerPolicy) -> BreakerVerdict:
+    """Classify already-counted state. PURE — the trip test, top to bottom.
+
+    Trips on EITHER rung (CC's `shouldFallbackToPrompting` OR-semantics). The
+    consecutive rung is checked first only so its (more specific, more urgent)
+    reason wins when both would fire; the verdict is OPEN either way. A disabled
+    rung (threshold 0) never fires (`__post_init__` guarantees at least one is on).
+    """
+    # consecutive rung — a sustained run of failures with no recovery.
+    if policy.max_consecutive > 0 and counts.consecutive >= policy.max_consecutive:
+        return BreakerVerdict(
+            state=BreakerState.OPEN,
+            escalation=policy.on_trip,
+            tripped_on="consecutive",
+            reason=(
+                f"{counts.consecutive} consecutive failures "
+                f"(>= max {policy.max_consecutive}) — a sustained failure, open the "
+                f"circuit"
+                + (f"; escalate to {policy.on_trip.value}"
+                   if policy.on_trip is not Escalation.NONE else "")
+            ),
+        )
+    # total rung — a flapping failure a consecutive count would miss.
+    if policy.max_total > 0 and counts.total >= policy.max_total:
+        return BreakerVerdict(
+            state=BreakerState.OPEN,
+            escalation=policy.on_trip,
+            tripped_on="total",
+            reason=(
+                f"{counts.total} total failures (>= max {policy.max_total}) — a "
+                f"flapping/unreliable path, open the circuit"
+                + (f"; escalate to {policy.on_trip.value}"
+                   if policy.on_trip is not Escalation.NONE else "")
+            ),
+        )
+    # CLOSED — under both limits.
+    return BreakerVerdict(
+        state=BreakerState.CLOSED,
+        escalation=Escalation.NONE,
+        tripped_on=None,
+        reason=(
+            f"{counts.consecutive} consecutive / {counts.total} total failures — "
+            f"under the limits (consecutive {policy.max_consecutive}, total "
+            f"{policy.max_total}); circuit closed"
+        ),
+    )
+
+
+def record_failure(
+    counts: BreakerCounts, policy: BreakerPolicy = DEFAULT_POLICY
+) -> BreakerTransition:
+    """Record one failure of this class and classify. PURE — no I/O.
+
+    Bumps BOTH counters (CC `recordDenial`), then classifies the new state. Returns
+    the next `BreakerCounts` to carry and the `BreakerVerdict` to act on. An already-
+    OPEN breaker stays OPEN (the counts only grow); recording past the trip is safe
+    and idempotent in outcome (the verdict stays OPEN), so a caller need not special-
+    case "already tripped."
+    """
+    bumped = replace(counts, consecutive=counts.consecutive + 1, total=counts.total + 1)
+    return BreakerTransition(counts=bumped, verdict=_classify(bumped, policy))
+
+
+def record_success(
+    counts: BreakerCounts, policy: BreakerPolicy = DEFAULT_POLICY
+) -> BreakerTransition:
+    """Record one success of this class and classify. PURE — no I/O.
+
+    Resets the CONSECUTIVE counter (the sustained-outage signal cleared) but NOT the
+    total (CC `recordSuccess` — a flapping path's cumulative count must survive its
+    intermittent successes, or flapping could never trip). So a success can CLOSE a
+    consecutive-tripped breaker, but it cannot un-trip a total-tripped one — which is
+    correct: a path that has failed 20 times total is unreliable no matter how many
+    times it also succeeded.
+    """
+    healed = replace(counts, consecutive=0)
+    return BreakerTransition(counts=healed, verdict=_classify(healed, policy))
+
+
+def classify(
+    counts: BreakerCounts, policy: BreakerPolicy = DEFAULT_POLICY
+) -> BreakerVerdict:
+    """Classify the CURRENT counts without recording anything. PURE — no I/O.
+
+    The read-only verdict (the `dos breaker` CLI / a `dos top` chip): "given these
+    counts, is the circuit open?" — without mutating the stream. `record_failure`/
+    `record_success` are the write path; this is the peek.
+    """
+    return _classify(counts, policy)

dos/churn.py

@@ -0,0 +1,226 @@
+"""churn — the pure "should this no-op archive coalesce into the prior commit?" fold.
+
+THE PROBLEM (measured 2026-06-04, the operator's "dispatch is still mega
+churning"). The dispatch family already gates the *push* surface — a repeated
+0-pick `BLOCKED`/`DRAIN` archive classifies NOOP and never reaches `origin`
+(`event_severity` + the per-sink `JOB_DISPATCH_*` thresholds). But every such
+iteration still writes its OWN local commit (the archive is unconditional by
+design — "archive always" so downstream tools see a terminal envelope). So
+`git log` fills with a limit cycle the operator stares at:
+
+    archive … verdict=BLOCKED, /replan recommended
+    replan  … quiet sweep (0 closed, 0 added)
+    archive … verdict=BLOCKED, /replan recommended      <- same cause, again
+    archive … verdict=BLOCKED, /replan recommended      <- and again
+    …
+
+Measured: 199 commits → 24 picks shipped (8.3 commits/pick); the single phrase
+`child2 skipped (/replan recommended)` recurred 22× over the window — a
+BLOCKED → no-op-replan → BLOCKED cycle that never converges. The push gate keeps
+peers clean; it does nothing for the LOCAL commit flood, which IS the churn.
+
+THE FIX (this kernel). When the current archive is a NOOP (a 0-pick
+blocker/drain) AND the immediately-prior commit on the branch is the SAME-family,
+SAME-cause NOOP archive, the write step should **amend** the prior commit instead
+of adding a new one — folding this run's README into it and bumping a recurrence
+count in the subject. The 22-commit cycle collapses to ~1 commit that says
+`blocked ×4 (recurring, coalesced)`; the full per-run audit still lives in the
+README tree (every run dir's `README.md` is preserved in the amended commit's
+pathspec), so nothing is lost — only the redundant `git log` rows.
+
+⚓ Pure kernel, I/O on the edge (the dos idiom — mirrors `classify_event` /
+`classify_recurring_wedge`): `decide_coalesce(ChurnState) -> CoalesceVerdict` is a
+frozen dataclass in, a frozen verdict out. The caller reduces the two facts the
+decision needs — *this* event and the *prior commit* — to scalars at the write
+step (one `git log -1` read + the `event_severity` classification it already
+runs), then hands them in frozen. No subprocess, no git/clock/file call here.
+
+⚓ Reuse the severity + cause vocabulary, never re-list it. The coalesce decision
+is layered ON TOP of `event_severity.classify_event` (only a NOOP coalesces) and
+keys recurrence on the SAME opaque `cause_key` string the host's
+`unstick_audit.classify_cause` / `dos.recurring_wedge` already produce. This
+module adds the *commit-shaping* rule; it does not re-derive severity or re-match
+cues.
+
+WHY a separate leaf and not a branch inside `event_severity`: severity answers
+"what operator value does this event carry?" (a push/report/terminal question).
+Coalescing answers "given the PRIOR commit, should this one merge into it?" (a
+git-history-shaping question that needs a second input — the prior commit — that
+severity never sees). Different question, different input, separate leaf — the
+`recurring_wedge`-vs-`wedge_reason` split pattern.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .event_severity import EventState, Severity, classify_event
+from .tokens import normalize_token
+
+# The minimum recurrence at which we coalesce. The FIRST no-op archive of a cause
+# always stands alone (it may be a genuine one-off the operator should see in the
+# log); the SECOND consecutive same-cause no-op is where the cycle starts and
+# coalescing kicks in. Mirrors `recurring_wedge.DEFAULT_MIN_RECURRENCE` (a cause
+# is "recurring" at 2 occurrences) so the two thresholds agree by construction.
+DEFAULT_MIN_COALESCE_RUN = 2
+
+# Families whose archives carry the per-run no-op cycle. `next-up` / `replan`
+# bookkeeping has its own quiet-sweep shape (already NOOP-gated for push) but does
+# NOT form the same prior-commit-amend cycle — a replan's commit legitimately
+# follows a dispatch archive and must not absorb it. So only the two dispatch
+# archive families coalesce.
+_COALESCING_FAMILIES = frozenset({"dispatch", "dispatch-loop"})
+
+
+@dataclass(frozen=True)
+class PriorCommit:
+    """The single prior commit the write step read with one `git log -1`.
+
+    Every field is parsed from the committed subject at the I/O edge — the kernel
+    never reads git. `is_coalesced` / `coalesce_count` let a THIRD consecutive
+    no-op extend an ALREADY-coalesced commit (×2 → ×3) rather than starting a new
+    coalesced commit beside it.
+    """
+
+    family: str  # the dispatch family the prior subject led with ("" if not ours)
+    severity: str  # the Severity value the prior event classified to ("" if unknown)
+    cause_key: str  # the opaque cause the prior no-op carried ("" if none / not ours)
+    is_coalesced: bool = False  # was the prior commit itself an ×N coalesced archive?
+    coalesce_count: int = 1  # the ×N already folded into the prior commit (≥1)
+
+
+@dataclass(frozen=True)
+class ChurnState:
+    """Everything the coalesce decision needs — the current event + the prior commit.
+
+    `event` is the SAME `EventState` the write step already built for the push
+    gate (so severity is computed once, here, not re-derived). `cause_key` is the
+    current event's opaque cause (from `unstick_audit.classify_cause` over the
+    Outcome cell, or "" when the host did not classify one — an unkeyed no-op
+    never coalesces, since we cannot prove it is the *same* cause as the prior).
+    `prior` is the parsed prior commit (None when there is no prior commit, e.g.
+    the very first archive on a fresh branch).
+    """
+
+    event: EventState
+    cause_key: str
+    prior: PriorCommit | None
+    min_coalesce_run: int = DEFAULT_MIN_COALESCE_RUN
+
+
+@dataclass(frozen=True)
+class CoalesceVerdict:
+    """Whether — and how — to coalesce. PURE given the `ChurnState`.
+
+    `coalesce` is the load-bearing field the write step branches on: True →
+    `git commit --amend` (fold this run's pathspec into the prior commit), False →
+    a normal new `git commit`. `recurrence` is the ×N to stamp into the amended
+    subject (the count INCLUDING this occurrence). `subject_suffix` is the ready
+    `×N (recurring, coalesced)` tail the write step appends to the family-prefixed
+    subject so the rendered headline is mechanical (no model retype, no ordinal —
+    the `subject_lead_token` discipline). `reason` is operator-facing telemetry.
+    """
+
+    coalesce: bool
+    recurrence: int
+    subject_suffix: str
+    reason: str
+
+
+def _is_noop_dispatch_archive(ev: EventState) -> bool:
+    """True iff `ev` is a dispatch-family archive that classifies NOOP — the only
+    event eligible to coalesce. A SHIPPED pick or a first-seen BLOCKED-NEW blocker
+    is operator-relevant and must keep its own standalone commit."""
+    fam = (ev.family or "").strip().lower()
+    if fam not in _COALESCING_FAMILIES:
+        return False
+    return classify_event(ev) is Severity.NOOP
+
+
+def decide_coalesce(state: ChurnState) -> CoalesceVerdict:
+    """Decide whether the current archive should fold into the prior commit.
+
+    The rule, in order:
+
+      1. The current event must be a NOOP dispatch archive (a 0-pick
+         blocker/drain). A SHIPPED or first-seen BLOCKED-NEW event never
+         coalesces — it is what the operator wants to SEE in the log.
+      2. It must carry a cause_key. An unkeyed no-op cannot be proven to be the
+         *same* cause as the prior commit, so it stands alone (fail-safe: when in
+         doubt, do not merge — a separate commit is always correct, just noisier).
+      3. The prior commit must be a SAME-family, SAME-cause NOOP archive. Same
+         family AND same opaque cause_key is the "this is the same cycle
+         repeating" signal. (A different cause, or a SHIPPED/replan/next-up
+         commit in between, breaks the run — the new no-op starts fresh.)
+      4. The recurrence (prior's folded count + 1) must reach `min_coalesce_run`.
+         The default 2 means the first no-op stands alone and the second folds
+         into it (→ ×2); a third extends the already-coalesced commit (→ ×3).
+
+    PURE — no I/O. `Severity` is computed via the shared `classify_event`, so the
+    coalesce decision and the push gate can never disagree about NOOP-ness.
+    """
+    ev = state.event
+    cause = (state.cause_key or "").strip()
+
+    if not _is_noop_dispatch_archive(ev):
+        return CoalesceVerdict(
+            coalesce=False, recurrence=1, subject_suffix="",
+            reason="not a no-op dispatch archive — stands alone (operator-relevant)",
+        )
+    if not cause:
+        return CoalesceVerdict(
+            coalesce=False, recurrence=1, subject_suffix="",
+            reason="no-op carries no cause_key — cannot prove same-cause, stands alone",
+        )
+
+    prior = state.prior
+    if prior is None:
+        return CoalesceVerdict(
+            coalesce=False, recurrence=1, subject_suffix="",
+            reason="no prior commit to coalesce into — first archive stands alone",
+        )
+
+    prior_fam = (prior.family or "").strip().lower()
+    prior_cause = (prior.cause_key or "").strip()
+    prior_sev = normalize_token(prior.severity) or ""
+
+    same_family = prior_fam in _COALESCING_FAMILIES
+    same_cause = bool(prior_cause) and prior_cause == cause
+    prior_is_noop = prior_sev == Severity.NOOP.value
+
+    if not (same_family and prior_is_noop and same_cause):
+        return CoalesceVerdict(
+            coalesce=False, recurrence=1, subject_suffix="",
+            reason=(
+                "prior commit is not a same-family same-cause no-op archive "
+                f"(prior family={prior_fam or 'none'} sev={prior_sev or 'none'} "
+                f"cause={prior_cause or 'none'} vs this cause={cause}) - stands alone"
+            ),
+        )
+
+    # The run continues: this is the (prior.coalesce_count + 1)-th consecutive
+    # same-cause no-op. The prior count is ≥1 (a plain prior no-op counts as 1).
+    recurrence = max(1, prior.coalesce_count) + 1
+    if recurrence < state.min_coalesce_run:
+        return CoalesceVerdict(
+            coalesce=False, recurrence=recurrence, subject_suffix="",
+            reason=(
+                f"recurrence {recurrence} < min_coalesce_run "
+                f"{state.min_coalesce_run} — stands alone"
+            ),
+        )
+
+    return CoalesceVerdict(
+        coalesce=True,
+        recurrence=recurrence,
+        # The `[cause:<key>]` token makes the coalesced subject SELF-DESCRIBING:
+        # the next no-op's prior-commit parse recovers the cause from this token
+        # (the original Outcome prose is gone once the subject collapses to the
+        # `blocked ×N` headline, so prose-classifying the coalesced subject would
+        # lose the cause and break the run at ×N+1). The host renders the suffix
+        # verbatim into the amended subject; the bridge parses `[cause:…]` back.
+        subject_suffix=f"×{recurrence} (recurring, coalesced) [cause:{cause}]",
+        reason=(
+            f"same-cause no-op '{cause}' repeats (×{recurrence}) — "
+            "amend prior commit instead of adding a new one"
+        ),
+    )