dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/marker_gate.py

@@ -0,0 +1,254 @@
+"""marker-gate — the PURE arming decision for the wait-marker budget (docs/274).
+
+> **`marker_sensor` is the boundary I/O (the per-session no-op tally) and
+> `noop_streak.classify` / `loop_decide.wait_marker_budget` is the pure
+> count-vs-cap BUDGET verdict. This module is the third piece they were missing:
+> the pure ARMING decision — "should this `Stop` event be subject to the budget at
+> ALL?" — extracted out of `cli.cmd_hook_marker` so the docs/274 fix is one named,
+> unit-tested function instead of two inline `if` blocks, and so its inputs are
+> declarable per-workspace in `dos.toml [marker]`.**
+
+The problem this closes (docs/274, the inversion it fixed)
+==========================================================
+
+A Claude Code `Stop` hook fires when Claude finishes **any** turn — interactive
+included — not only on a keep-alive *poll* turn, and a `{"decision":"block"}`
+FORCES the agent to keep working. The wait-marker budget's polarity assumes a
+`Stop` means "the loop chose not to stop, i.e. it is about to poll again"; on a
+bare/global Stop binding that premise is FALSE, so an unscoped budget blocks every
+ordinary turn and MANUFACTURES the very keep-alive cache-replay waste it exists to
+cap (docs/274: 44 sessions, 35 walled at the 4/4 cap, 0 actual polls). The fix is
+to ARM the budget only when there is positive evidence this `Stop` is a poll inside
+a loop, and to honor Claude Code's own infinite-loop backstop (`stop_hook_active`).
+
+This module is the *policy* half of that fix: the two guards, made a pure function
+of an injected environment + a declared `MarkerPolicy`. The CLI (`cmd_hook_marker`)
+gathers the impure inputs (the Stop event JSON, the process `os.environ`, the
+`--loop` flag) and calls `decide()`; the budget arithmetic stays in `noop_streak`.
+
+The arming signal IS the missing evidence (the load-bearing idea)
+================================================================
+
+The budget's flaw was that its trigger ("this `Stop` is a poll") was an *assumption
+about the moment*, not *evidence read from it* — which is exactly why it was the one
+DOS hook that inverted (`dos hook stop` blocks only on a claim-vs-git contradiction;
+`dos hook pretool` denies only on a real lease collision). The arming signal
+(`--loop`, or a loop-scoping env var the dispatch loop sets) is the evidence the bare
+event lacks — supplied from OUTSIDE the event, it proves the assumption holds. So
+`decide()` is the discipline "an intervention is a safe default only if its trigger is
+evidence" turned into code: no arming evidence → not armed → allow the stop.
+
+Why the env-var NAMES are config, not hardcoded
+===============================================
+
+A dispatch loop signals "I am a loop" by exporting a sentinel env var. The two
+built-in defaults (`DOS_LOOP`, the correlation-spine `CID_RUN_ID` the marker record
+already rides) cover the in-tree `/loop` and the reference userland app — but a
+different host runs a different loop with a different sentinel. So the arming env-var
+names are a declared `MarkerPolicy.arm_on_env` tuple, the same "closed-set-as-data"
+pattern as `reasons`/`stamp`/`noop_streak`'s `max_streak`: mechanism (the arming
+decision) is the kernel; policy (which signals arm it, what the cap is, whether to
+honor `stop_hook_active`) is config a workspace declares in `dos.toml [marker]`.
+
+Kernel discipline (the litmus)
+==============================
+
+A PURE policy leaf — imports only stdlib (+ the declarative-config `tomllib` at
+load time). Names no host and no vendor (the `stop_hook_active` field is a
+DIALECT-NEUTRAL concept the Stop event carries; this module never branches on which
+runtime is acting). `decide()` makes NO I/O at all — the caller injects the
+environment as a plain mapping, so the arming truth table is replay-testable away
+from `os.environ`. Passes `test_vendor_agnostic_kernel.py`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+
+# The two built-in loop-sentinel env-var names (docs/274). `DOS_LOOP` is the generic
+# opt-in a host exports on a keep-alive loop; `CID_RUN_ID` is the correlation-spine
+# run-id the dispatch loop already sets (and the marker record already stamps), so a
+# loop driven through the spine arms the budget with no extra wiring. A workspace
+# REPLACES/extends this via `dos.toml [marker] arm_on_env` (a host with its own loop
+# sentinel names it there).
+DEFAULT_ARM_ON_ENV: tuple[str, ...] = ("DOS_LOOP", "CID_RUN_ID")
+
+
+@dataclass(frozen=True)
+class MarkerPolicy:
+    """The declared knobs for the wait-marker budget — policy, not mechanism.
+
+    The "mechanism is kernel, policy is config" split (the `noop_streak.NoOpStreakPolicy`
+    / `tool_stream.StreamPolicy` posture). A workspace declares its own in
+    `dos.toml [marker]`; the generic default is interactive-safe (armed only by an
+    explicit loop signal, never on an ordinary turn).
+
+      max_streak — the **no-op-turn budget** handed to `noop_streak.classify`: the most
+                   consecutive keep-alive/poll turns a loop may take before the next is
+                   refused. Default 4 (`wait_marker_budget`'s cap, one below the
+                   `keepalive_poll` telemetry flag at >=5, so the runtime refusal lands
+                   one turn before the post-hoc alarm). Must be non-negative.
+
+      arm_on_env — the env-var NAMES whose presence (any one, non-empty) ARMS the budget.
+                   The evidence that this `Stop` is a poll inside a loop. Default
+                   `("DOS_LOOP", "CID_RUN_ID")`; a host names its own loop sentinel here.
+                   Empty () means "no env arms it" — only the explicit `--loop` flag does.
+
+      respect_stop_hook_active — honor Claude Code's own infinite-loop backstop
+                   (docs/274 Case C): when the Stop event carries `stop_hook_active:true`
+                   (this stop is ALREADY being continued by a prior hook block), do NOT
+                   re-block it. Default True. A host that deliberately wants to keep
+                   escalating an already-continued stop sets this False (rarely correct —
+                   it is how a budget becomes a forced march).
+    """
+
+    max_streak: int = 4
+    arm_on_env: tuple[str, ...] = DEFAULT_ARM_ON_ENV
+    respect_stop_hook_active: bool = True
+
+    def __post_init__(self) -> None:
+        if self.max_streak < 0:
+            raise ValueError("max_streak must be non-negative")
+        # Normalize arm_on_env to a tuple of non-empty strings (a list from TOML, a
+        # stray empty/blank name) so `decide`'s `env.get(name)` walk is well-defined.
+        names = tuple(
+            n.strip() for n in self.arm_on_env if isinstance(n, str) and n.strip()
+        )
+        # frozen dataclass — set through object.__setattr__ (the canonical idiom).
+        object.__setattr__(self, "arm_on_env", names)
+
+
+DEFAULT_POLICY = MarkerPolicy()
+
+
+@dataclass(frozen=True)
+class ArmDecision:
+    """Whether the budget arms for this `Stop`, with the operator-facing why.
+
+    `armed` is the load-bearing bit: True → the caller proceeds to the budget verdict
+    (and may block the Stop); False → the caller emits nothing (allow the stop), the
+    fail-safe direction. `reason` is for `--debug` — it names WHICH guard decided, so an
+    operator can see "not armed: no loop signal" vs "not armed: stop_hook_active" vs
+    "armed: DOS_LOOP set" without reading the code.
+    """
+
+    armed: bool
+    reason: str
+
+
+def decide(
+    *,
+    stop_hook_active: bool,
+    loop_flag: bool,
+    env: Mapping[str, str],
+    policy: MarkerPolicy = DEFAULT_POLICY,
+) -> ArmDecision:
+    """Decide whether the wait-marker budget arms for this `Stop`. PURE — no I/O.
+
+    The two docs/274 guards, in order, as a function of injected inputs:
+
+      1. `respect_stop_hook_active and stop_hook_active` → NOT armed. Claude Code's own
+         infinite-loop backstop: this stop is already being continued by a prior hook
+         block, so escalating it with another block is how a budget becomes a forced
+         march. Allow the stop. (Checked FIRST so an already-continued stop is never
+         re-blocked even inside a loop.)
+
+      2. else armed ⟺ `loop_flag OR any(env.get(name) for name in policy.arm_on_env)`.
+         The TRIGGER guard: a `Stop` hook fires on every finished turn, so the budget
+         arms only with positive evidence this one is a keep-alive poll inside a loop —
+         an explicit `--loop`, or a loop-sentinel env var the dispatch loop set. No
+         such evidence → an ordinary interactive turn → NOT armed → allow the stop.
+
+    `env` is injected (a `Mapping`, typically `os.environ`) so the truth table is
+    replay-testable without mutating the process environment. A name maps to "present"
+    when `env.get(name)` is truthy (a set, non-empty value) — an empty string does NOT
+    arm (a host that exports `DOS_LOOP=""` to UNSET it is honored).
+    """
+    if policy.respect_stop_hook_active and stop_hook_active:
+        return ArmDecision(
+            armed=False,
+            reason=(
+                "stop_hook_active — stop already hook-continued; do not re-block; "
+                "allow stop"
+            ),
+        )
+    if loop_flag:
+        return ArmDecision(armed=True, reason="armed by --loop")
+    for name in policy.arm_on_env:
+        if env.get(name):
+            return ArmDecision(armed=True, reason=f"armed by env {name}")
+    arm_names = ", ".join(policy.arm_on_env) if policy.arm_on_env else "(none)"
+    return ArmDecision(
+        armed=False,
+        reason=(
+            f"no loop signal (--loop / env {arm_names}) — ordinary turn, not a "
+            f"keep-alive poll; allow stop (wait-marker budget arms only inside a loop)"
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# The declarative on-ramp — read a policy out of dos.toml [marker]
+# (mirror noop_streak/tool_stream/stamp: policy_from_table + load_from_toml).
+# ---------------------------------------------------------------------------
+def policy_from_table(table: dict, *, base: MarkerPolicy = DEFAULT_POLICY) -> MarkerPolicy:
+    """Turn a parsed `[marker]` TOML table into a `MarkerPolicy`. PURE (no I/O).
+
+    `table` is `{max_streak?, arm_on_env?, respect_stop_hook_active?}` — the shape
+    `tomllib.load(...)["marker"]` yields. A missing key falls back to `base` (default the
+    generic), so a partial table tunes only what it names. A malformed value (a negative
+    `max_streak`, a non-list `arm_on_env`) raises at construction
+    (`MarkerPolicy.__post_init__`), so a bad declaration fails loudly at load (the
+    `noop_streak.policy_from_table` posture).
+    """
+    if not table:
+        return base
+    arm = table.get("arm_on_env", base.arm_on_env)
+    # A scalar string is accepted as a single name (the common one-sentinel case);
+    # a list is the general case. Anything else falls back to base (fail-soft on shape,
+    # since the value is advisory config, not a verdict input).
+    if isinstance(arm, str):
+        arm_tuple: tuple[str, ...] = (arm,)
+    elif isinstance(arm, (list, tuple)):
+        arm_tuple = tuple(arm)
+    else:
+        arm_tuple = base.arm_on_env
+    return MarkerPolicy(
+        max_streak=int(table.get("max_streak", base.max_streak)),
+        arm_on_env=arm_tuple,
+        respect_stop_hook_active=bool(
+            table.get("respect_stop_hook_active", base.respect_stop_hook_active)
+        ),
+    )
+
+
+def load_from_toml(
+    path: "Path | str", *, base: MarkerPolicy = DEFAULT_POLICY
+) -> MarkerPolicy:
+    """Build a `MarkerPolicy` from a `dos.toml`'s `[marker]` table.
+
+    Returns `base` unchanged when the file is absent, has no `[marker]` table, or
+    `tomllib` is unavailable — the declarative path is purely additive, so a
+    missing/empty config degrades to the generic default, never an error (the
+    `noop_streak.load_from_toml` contract). A *present but malformed* table raises
+    (`MarkerPolicy.__post_init__`). Reads with `utf-8-sig` to strip a PowerShell-written
+    BOM (the `reasons`/`tool_stream`/`noop_streak` `load_from_toml` fix).
+    """
+    p = Path(path)
+    if not p.exists():
+        return base
+    try:
+        import tomllib  # py3.11+
+    except ModuleNotFoundError:  # pragma: no cover - py<3.11 fallback
+        try:
+            import tomli as tomllib  # type: ignore
+        except ModuleNotFoundError:
+            return base
+    data = tomllib.loads(p.read_text(encoding="utf-8-sig"))
+    table = data.get("marker")
+    if not isinstance(table, dict) or not table:
+        return base
+    return policy_from_table(table, base=base)

dos/marker_sensor.py

@@ -0,0 +1,396 @@
+"""marker-sensor — the boundary I/O for the wait-marker budget (loop_decide §wait-marker).
+
+> **`loop_decide.wait_marker_budget(markers_emitted, max_markers)` is a PURE
+> verdict over an integer count. SOMETHING has to remember, across the many
+> short-lived hook invocations of one session, HOW MANY keep-alive markers this
+> loop has already emitted — the Stop event the host hands us carries no such
+> count. That is this module: the wait-marker axis's `posttool_sensor` — boundary
+> I/O (the per-session `.dos/markers/<sid>.jsonl` tally) feeding the pure core,
+> never inside the verdict.**
+
+The problem this closes (docs: [[project-dos-poll-loop-antipattern]], the
+`wait_marker_budget` docstring's "session 4b4ff97c burned 252 markers / ~$7.80"):
+a `/loop`-style dispatch loop holds its turn open by emitting `claude -p`
+keep-alive markers (or by re-reading a `.output` file in a tight tick), and each
+marker is a FULL assistant turn that replays the whole system+skill+context out of
+prompt cache for zero forward work. The pure `wait_marker_budget` can refuse a
+marker once a budget is reached — but only if it is told the running count, and a
+count threaded through a CLI flag (`--emitted N`) is exactly the "prose the model
+must remember" the budget docstring criticizes. So we make the count
+GROUND-TRUTH DURABLE STATE the model cannot forget: one append-only record per
+marker, under the session's `.dos/markers/<sid>.jsonl`, replayed back to a count.
+
+Why this is the EXACT sibling of `posttool_sensor`
+==================================================
+
+`posttool_sensor` is the in-flight boundary for `tool_stream`: append one
+`StreamStep` per PostToolUse fire, replay the session's steps into a `ToolStream`
+the pure `classify_stream` folds. This module is the SAME shape for the wait-marker
+budget, but the fold is the simplest possible one — a COUNT:
+
+  * **the accumulator** (`record_marker` / `marker_count`) — the one impure part:
+    an append-only, `fsync`'d, schema-tagged, torn-tail-tolerant session tally,
+    byte-mirroring `intent_ledger`'s ARIES discipline (the same idiom
+    `posttool_sensor.append_step` / `read_stream` copy) so the count survives across
+    the many separate hook processes of one session. A record is one tagged
+    `{"op":"MARKER"}` line; the COUNT is the number of valid records replayed back.
+  * the verdict itself is `loop_decide.wait_marker_budget` — PURE, already shipped,
+    already green. This module never re-implements the allow/refuse arithmetic; it
+    only supplies the count and persists the increment.
+
+The polarity, stated sharply (the load-bearing correctness fact)
+================================================================
+
+This binds to a **Stop** hook, and its polarity is the INVERSE of `cmd_hook_stop`.
+A keep-alive wait-marker is the loop CHOOSING NOT TO STOP — blocking its own Stop
+to keep waiting. So:
+
+  * budget REMAINS  (`wait_marker_budget(...).allow is True`)  → the loop MAY emit
+    another marker → **block the Stop** (`{"decision":"block", "reason": …}`),
+    holding the turn open one more marker.
+  * budget EXHAUSTED (`.allow is False`)                       → stop polling →
+    **allow the Stop** (emit NOTHING — an empty Stop output is CC's "allow stop") →
+    the loop ends its turn and waits on the real Bash `<task-notification>`, which
+    fires on the child's true exit regardless ([[project-dos-poll-loop-antipattern]]).
+
+`cmd_hook_stop` BLOCKS a *false done* (the agent claimed ship, git disagrees);
+this BLOCKS a *premature give-up only while the marker budget is unspent*, then
+gets out of the way. Two Stop hooks, opposite triggers — keep them apart.
+
+Why it is ADVISORY and fail-safe
+================================
+
+The kernel stays a PDP, not a PEP (docs/99): the block is a PROPOSAL the runtime
+consumes. Every failure mode degrades to "emit nothing, exit 0" = let the agent
+stop — a missing stdin, unparseable JSON, an unusable session_id, an accumulator
+I/O error. The hook can refuse to keep a loop polling past its budget; it never
+traps a loop open on its own inability to read or write, and it never blocks a
+loop that has a real reason to keep working (the budget only counts MARKERS the
+loop itself declared by firing this hook on a keep-alive turn).
+
+⚓ Kernel discipline (the litmus): a PURE verdict-adapter — imports only sibling
+kernel modules (`loop_decide`, `config`, `durable_schema`), names no host /
+driver, resolves every path via `SubstrateConfig.paths` (never `__file__`), and
+carries no policy of its own (the threshold is `wait_marker_budget`'s
+`max_markers`, handed in at the CLI).
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+except Exception:
+    pass
+
+from dos import config as _config
+from dos import durable_schema as _schema
+
+# The durable-schema family + version every marker record carries (the §6 schema
+# gate, byte-mirroring `posttool_sensor`). Bumped ONLY on a NON-additive shape
+# change. A record tagged a non-additively-newer version is REFUSED at read (never
+# best-effort-parsed into a forged count).
+SCHEMA_FAMILY = "wait-marker"
+WAIT_MARKER_SCHEMA = 1
+
+# The directory the per-session marker tallies live under, beneath `.dos/`. A
+# sibling of `posttool_sensor`'s `.dos/streams/` — keyed by the host-authored
+# `session_id` (the Stop event carries a `session_id`, not a DOS run-id), exactly
+# as the stream accumulator is.
+MARKERS_DIRNAME = "markers"
+
+# The closed op vocabulary the tally records. `MARKER` is one no-op (keep-alive) turn;
+# `RESET` is a forward-delta / session-boundary marker that ZEROES the running count
+# (docs/259 §Follow-up 2 — the `tool_stream` ADVANCING analogue: progress earns the
+# loop a fresh budget). A new op is ADDITIVE in a closed vocabulary, so adding `RESET`
+# does NOT bump `WAIT_MARKER_SCHEMA` (the `durable_schema` additive contract): an old
+# reader simply skips an op it does not count, a new reader gives it meaning.
+MARKER_OP = "MARKER"
+RESET_OP = "RESET"
+
+
+def _now_iso() -> str:
+    """Second-resolution UTC stamp for a marker record (the `intent_ledger` idiom)."""
+    return dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+# ---------------------------------------------------------------------------
+# Boundary I/O — the ONE impure part: the session-scoped marker tally.
+# Byte-mirrors `posttool_sensor`'s accumulator (which itself mirrors
+# `intent_ledger`): fsync, O_APPEND, torn-tail tolerance, the §6 schema gate.
+# A marker record is one append-only line; the COUNT is the number of valid lines.
+# ---------------------------------------------------------------------------
+def _safe_session_name(session_id: str) -> Optional[str]:
+    """The sanitized filename stem for a host-authored `session_id`, or None to skip.
+
+    Byte-identical to `posttool_sensor._safe_session_name`: `session_id` is a
+    distrusted host-authored token, so strip any path separators / `..` / drive
+    components (a path-traversal surface) and keep only the safe characters of a
+    normal session uuid. An empty/whitespace token (or one that sanitizes to empty)
+    returns None — no identity, no accumulator (the caller emits nothing rather than
+    writing to a junk path).
+    """
+    if not isinstance(session_id, str):
+        return None
+    safe = "".join(c for c in session_id if c.isalnum() or c in "-_")
+    return safe or None
+
+
+def markers_dir_for(cfg: "_config.SubstrateConfig | None" = None) -> Path:
+    """The `.dos/markers/` directory under the active workspace. PURE path arithmetic.
+
+    Rides `cfg.paths.dot_dos` (the per-project `.dos/` home), the sibling of
+    `posttool_sensor`'s `.dos/streams/`. Never creates the dir — `record_marker` is
+    the only creator (the read-only-path discipline)."""
+    cfg = _config.ensure(cfg)
+    return cfg.paths.dot_dos / MARKERS_DIRNAME
+
+
+def marker_path_for(
+    session_id: str, cfg: "_config.SubstrateConfig | None" = None
+) -> Optional[Path]:
+    """The `.dos/markers/<session_id>.jsonl` path for a session, or None if unusable.
+
+    Pure path arithmetic (the `posttool_sensor.stream_path_for` idiom): never creates
+    anything. Returns None when `session_id` sanitizes to empty (no safe filename) —
+    the caller treats that as "no accumulator," emitting nothing.
+    """
+    safe = _safe_session_name(session_id)
+    if safe is None:
+        return None
+    return markers_dir_for(cfg) / f"{safe}.jsonl"
+
+
+def _marker_entry(*, reason: str | None = None, run_id: str | None = None) -> dict:
+    """The durable record for one emitted marker — schema-tagged, canonical. PURE.
+
+    Carries the §6 schema tag so a record written directly is self-declaring (the
+    `posttool_sensor._step_entry` posture). `reason` (the budget verdict's
+    operator-facing line) and `run_id` (the correlation-spine join key, when the
+    active env carries one) are ADDITIVE optional fields — present only when known —
+    so a record without them reads back identically and the schema version does NOT
+    bump (the `durable_schema` additive contract).
+    """
+    e: dict = {
+        **_schema.tag(SCHEMA_FAMILY, WAIT_MARKER_SCHEMA),
+        "op": MARKER_OP,
+    }
+    if reason:
+        e["reason"] = reason
+    if run_id:
+        e["run_id"] = run_id
+    return e
+
+
+def _reset_entry(*, reason: str | None = None, run_id: str | None = None) -> dict:
+    """The durable record for one forward-delta / session-boundary RESET. PURE.
+
+    Identical shape to `_marker_entry` but `op:"RESET"` — a record that, on replay,
+    ZEROES the running no-op count (the `tool_stream` ADVANCING analogue, docs/259
+    §Follow-up 2). Carries the same §6 schema tag (so it is self-declaring) and the
+    same ADDITIVE optional `reason`/`run_id` fields; an additive new op never bumps the
+    schema version (the `durable_schema` contract).
+    """
+    e: dict = {
+        **_schema.tag(SCHEMA_FAMILY, WAIT_MARKER_SCHEMA),
+        "op": RESET_OP,
+    }
+    if reason:
+        e["reason"] = reason
+    if run_id:
+        e["run_id"] = run_id
+    return e
+
+
+def record_marker(
+    session_id: str,
+    cfg: "_config.SubstrateConfig | None" = None,
+    *,
+    path: Path | None = None,
+    reason: str | None = None,
+    run_id: str | None = None,
+) -> None:
+    """Append ONE marker record to the session's tally and `fsync` it.
+
+    Copies `posttool_sensor.append_step`'s durability idiom EXACTLY (itself a copy of
+    `intent_ledger.append`): stamp the record (the §6 schema tag + a `ts`), write one
+    canonical-JSON line + newline through `os.open(O_WRONLY|O_APPEND|O_CREAT)` +
+    `os.write` + `os.fsync` + `os.close`, so the record is durable before this
+    returns and the append is atomic w.r.t. any other appender at the OS level.
+    `mkdir(parents=True)` the markers dir lazily (the only creator). `path` overrides
+    the resolved location (tests).
+
+    Raises on an unusable `session_id` (no `path` and the session sanitizes to
+    empty) — the CLI wraps this whole call in a fail-safe try/except (advisory: never
+    block a real workflow on the sensor's own write failure), so a raise here degrades
+    to "emit nothing," never a crashed turn.
+    """
+    _append_record(
+        _marker_entry(reason=reason, run_id=run_id),
+        session_id,
+        cfg,
+        path=path,
+        what="record_marker",
+    )
+
+
+def record_reset(
+    session_id: str,
+    cfg: "_config.SubstrateConfig | None" = None,
+    *,
+    path: Path | None = None,
+    reason: str | None = None,
+    run_id: str | None = None,
+) -> None:
+    """Append ONE forward-delta RESET record to the session's tally and `fsync` it.
+
+    The §Follow-up 2 zeroing event: a forward delta (a commit, a real tool result, or
+    a host re-entering a fresh wait phase) appends a `RESET` record, and `marker_count`
+    replays the count as markers-AFTER-the-last-reset — so progress earns the loop a
+    fresh budget (the `tool_stream` ADVANCING analogue). Same durability idiom as
+    `record_marker` (the `intent_ledger`/`posttool_sensor` `O_APPEND`+`fsync` append):
+    the reset is durable and atomic at the OS level before this returns, never a
+    truncation of the append-only log.
+
+    Raises on an unusable `session_id` (no `path` and the session sanitizes to empty);
+    the CLI wraps the call in a fail-safe try/except (advisory: a reset we could not
+    persist must not crash the turn — it degrades to "no reset," which leaves the count
+    HIGHER, the conservative refuse-more direction for a cost guard).
+    """
+    _append_record(
+        _reset_entry(reason=reason, run_id=run_id),
+        session_id,
+        cfg,
+        path=path,
+        what="record_reset",
+    )
+
+
+def _append_record(
+    entry: dict,
+    session_id: str,
+    cfg: "_config.SubstrateConfig | None" = None,
+    *,
+    path: Path | None = None,
+    what: str = "record",
+) -> None:
+    """The shared durable-append both `record_marker` and `record_reset` ride. Impure.
+
+    Stamp the (already schema-tagged) record with a `ts`, write one canonical-JSON line
+    + newline through `os.open(O_WRONLY|O_APPEND|O_CREAT)` + `os.write` + `os.fsync` +
+    `os.close` (the `posttool_sensor.append_step` / `intent_ledger.append` idiom), so
+    the record is durable before this returns and the append is atomic w.r.t. any other
+    appender at the OS level. `mkdir(parents=True)` the markers dir lazily (the only
+    creator). `path` overrides the resolved location (tests). Raises (with `what` named)
+    on an unusable `session_id` and no explicit `path`.
+    """
+    p = path or marker_path_for(session_id, cfg)
+    if p is None:
+        raise ValueError(f"{what} needs a usable session_id or an explicit path")
+    entry.setdefault("ts", _now_iso())
+    line = json.dumps(entry, sort_keys=True, default=str, ensure_ascii=False) + "\n"
+    p.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(str(p), os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o644)
+    try:
+        os.write(fd, line.encode("utf-8"))
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def marker_count(
+    session_id: str,
+    cfg: "_config.SubstrateConfig | None" = None,
+    *,
+    path: Path | None = None,
+    understands: int = WAIT_MARKER_SCHEMA,
+) -> int:
+    """Replay the session's tally into the no-op COUNT SINCE THE LAST RESET. The read-side.
+
+    The count is "the number of readable MARKER records that appear AFTER the last
+    readable RESET record" (docs/259 §Follow-up 1+2): a single forward pass where a
+    MARKER increments and a RESET zeroes. With NO RESET in the file (every host today),
+    this is byte-identical to the old "count all MARKERs" — so the shipped `dos hook
+    marker` behavior is unchanged for any current tally; the reset only bites once a
+    forward-delta RESET is written.
+
+    Two distrust postures layered, byte-mirroring `posttool_sensor.read_stream` /
+    `intent_ledger.read_all`:
+
+      * **Torn-tail tolerance** — an unparseable line (a crash mid-append, or a
+        mid-file corrupt line) is skipped: a half-written record is "didn't happen."
+        For a MARKER this UNDER-counts (admit one more marker than strictly emitted);
+        for a RESET this means the reset "didn't happen" so the count stays HIGHER —
+        BOTH are the same conservative direction (refuse one MORE no-op turn, never one
+        fewer), the right bias for an advisory cost guard. A torn RESET can never erase
+        a real marker count it failed to fully write.
+      * **Schema gate** (§6) — a record whose `schema` tag is a non-additively-newer
+        version than `understands` is SKIPPED (a record this kernel is too old to
+        read can never fabricate OR erase a count — a too-new RESET does not zero). An
+        UNTAGGED (legacy) record is read permissively (the `durable_schema.UNTAGGED`
+        tolerant side); a WRONG_FAMILY record (a foreign line) is skipped. An unknown
+        op (neither MARKER nor RESET) is ignored, count unchanged.
+
+    Returns 0 when the file is absent (no markers emitted yet — the budget's fresh
+    floor). `understands` is injectable so a test can simulate an OLD reader meeting a
+    NEW record.
+    """
+    p = path or marker_path_for(session_id, cfg)
+    if p is None or not p.exists():
+        return 0
+    try:
+        raw = p.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return 0
+    count = 0
+    for line in raw.splitlines():
+        s = line.strip()
+        if not s:
+            continue
+        try:
+            obj = json.loads(s)
+        except json.JSONDecodeError:
+            # Torn final / corrupt mid-file line → "didn't happen". For a MARKER this
+            # under-counts; for a RESET the zeroing is skipped so the count stays
+            # higher — both the safe (refuse-more) direction for a cost guard.
+            continue
+        if not isinstance(obj, dict):
+            continue
+        # The §6 schema gate. READABLE/UNTAGGED proceed; UNREADABLE_NEWER and
+        # WRONG_FAMILY are skipped (a too-new/foreign record never forges a count and
+        # — critically for a RESET — never erases one).
+        v = _schema.classify(obj, family=SCHEMA_FAMILY, understands=understands)
+        if v.readability not in (
+            _schema.Readability.READABLE,
+            _schema.Readability.UNTAGGED,
+        ):
+            continue
+        op = obj.get("op")
+        if op == MARKER_OP:
+            count += 1
+        elif op == RESET_OP:
+            # A forward-delta reset zeroes the running no-op count — progress earns the
+            # loop a fresh budget (the `tool_stream` ADVANCING analogue).
+            count = 0
+        # else: an unknown/absent op is not a counted no-op turn and not a reset.
+    return count
+
+
+# The session-boundary RESET (docs/259 §Follow-up 2) is now LIVE: `record_reset`
+# appends an `op:"RESET"` record and `marker_count` replays the count as
+# markers-after-the-last-reset, so a forward delta (or a host re-entering a fresh wait
+# phase) zeroes the tally — the `tool_stream` ADVANCING analogue. The pure verdict over
+# the resulting count is `noop_streak.classify` (the generalization of
+# `wait_marker_budget` off "markers emitted" onto "no-op turns since the last forward
+# delta"). What is STILL explicit (not auto-derived) is the reset TRIGGER: a host fires
+# `dos hook marker --reset` on a forward-progress hook (SessionStart/UserPromptSubmit)
+# or after a commit. Auto-deriving a RESET from a live git/journal delta (pulling
+# `git_delta` into the marker boundary, the `liveness` evidence reader) is the remaining
+# future step — it would close the loop fully but is a larger change than this cut.