dos-kernel 0.23.4__tar.gz → 0.24.1__tar.gz

{dos_kernel-0.23.4 → dos_kernel-0.24.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dos-kernel
-Version: 0.23.4
+Version: 0.24.1
 Summary: Dispatch Operating System — the domain-free trust substrate for fleets of autonomous agents (verdict spine, ship oracle, structured refusal, lane arbiter, correlation spine).
 Author: Anthony Chaudhary
 License: MIT
@@ -96,7 +96,7 @@ zero config, and the only thing you ever install is one small Python package.
 > ⏱️ **Want to try it right now?** Jump to **[Try it in 60 seconds](#try-it-in-60-seconds)**
 > — one command, real output, then come back for the why.
 
-<sub>**v0.23.4** · 3900+ tests · CI: Python 3.11–3.13 on Linux + a Windows 3.13
+<sub>**v0.24.1** · 3900+ tests · CI: Python 3.11–3.13 on Linux + a Windows 3.13
 smoke run · the only runtime dependency is **PyYAML** · **MIT**.</sub>
 
 > 🧭 **Want it in plain words first?** What DOS is, what it catches, and what
@@ -111,6 +111,13 @@ smoke run · the only runtime dependency is **PyYAML** · **MIT**.</sub>
 > your work, the ~5 files actually worth reading, and the architecture rules a
 > change must satisfy.
 
+> 🔤 **Five words the rest of this page leans on.** A **plan** is a named goal
+> (`AUTH`); a **phase** is one shippable step of it (`AUTH1`); a **lane** is the
+> slice of the file tree one agent may touch; the **oracle** is the part of DOS
+> that reads the evidence and rules; a **stamp** is the mark a shipped phase
+> leaves in a commit subject (`AUTH1: …`) — the thing the oracle greps for.
+> That's the whole vocabulary.
+
 <a id="who-this-is-for"></a>
 
 ## Who this is for
@@ -209,8 +216,8 @@ echo 'def login(): ...' > login.py
 git add -A
 git commit -m "AUTH1: ship the login endpoint"   # stamp AUTH1 shipped: <PHASE-ID>: <message>
 
-dos verify --workspace . AUTH AUTH1   # → SHIPPED     AUTH AUTH1 e389e8b (via grep-subject)   exit 0
-dos verify --workspace . AUTH AUTH2   # → NOT_SHIPPED  AUTH AUTH2          (via none)          exit 1
+dos verify --workspace . AUTH AUTH1   # → SHIPPED     AUTH AUTH1 <your-sha> (via grep-subject)  exit 0
+dos verify --workspace . AUTH AUTH2   # → NOT_SHIPPED  AUTH AUTH2            (via none)          exit 1
 ```
 
 An agent can claim `AUTH2` is done all day long; `verify` just reports what the
@@ -593,12 +600,15 @@ reads (wire it in `cli-config.yaml`). A new host's dialect is a driver, never a
 kernel edit.
 
 The flip side of that honesty: a host with **no** hook seam gets **no** dialect.
-ByteDance's **Trae** was proved out and has no hook system at all (no lifecycle
-events, no deny/allow stdout contract), so DOS binds to it advisory-only — the
-MCP server in `.trae/mcp.json`, a verify-before-"done" rule in
-`.trae/rules/project_rules.md`, the generic skills in `.trae/skills/` — and
-`dos init --hooks trae` fails loud rather than writing config Trae would never
-read ([docs/294](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/294_trae-advisory-only-the-host-with-no-hook-seam.md)).
+ByteDance's **Trae** was proved out and ships no user-scriptable hook system in
+its personal/international editions (no lifecycle events, no deny/allow stdout
+contract; its CN-enterprise edition announced one on 2026-06-09 with no
+published grammar yet), so DOS binds to it advisory-only — the MCP server in
+`.trae/mcp.json` (read alike by IDE-mode Agent, SOLO mode, and TRAE CLI), a
+verify-before-"done" rule in `.trae/rules/project_rules.md`, the generic
+skills in `.trae/skills/` — and `dos init --hooks trae` fails loud rather than
+writing config Trae would never read
+([docs/294](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/294_trae-advisory-only-the-host-with-no-hook-seam.md)).
 An invented envelope would be fake enforcement, which is the exact failure the
 dialect seam exists to prevent.
 
@@ -688,14 +698,14 @@ channel, upgrade/uninstall, WSL, troubleshooting) is in
 **[docs/INSTALL.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/INSTALL.md)**:
 
 ```bash
-# uv — the modern, fast, isolated CLI install (recommended):
-uv tool install dos-kernel        # `dos` + `dos-mcp` on PATH
-uvx --from dos-kernel dos doctor  # or run it once, ephemerally
-
-# pip — the library-consumer path (a host pins dos-kernel in its own venv):
+# pip — the default (the line the 60-second demo ran; also how a host pins it):
 pip install dos-kernel            # core kernel (PyYAML only)
 pip install "dos-kernel[mcp]"     # + the MCP server (dos-mcp)
 
+# uv — the isolated CLI install (keeps `dos` + `dos-mcp` off your project venv):
+uv tool install dos-kernel        # `dos` + `dos-mcp` on PATH
+uvx --from dos-kernel dos doctor  # or run it once, ephemerally
+
 # from a clone — editable, the contributor path (tracking unreleased master:
 # pip install "dos-kernel @ git+https://github.com/anthony-chaudhary/dos-kernel", no clone needed):
 git clone https://github.com/anthony-chaudhary/dos-kernel.git && cd dos-kernel
@@ -709,10 +719,12 @@ pip install -e .                  # editable: your edits are live in the install
 > `[mcp]` extra adds the MCP framework; `[tui]` adds the live `dos top` screens).
 > See [SECURITY.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/SECURITY.md), "Supply chain."
 
-Prefer a package manager? **uv** is the 2026 default — faster than `pipx`,
-isolates the tool, and manages Python versions; `pipx install dos-kernel` works
-the same way if your team already uses it. Homebrew / WinGet / Scoop one-liners
-are next on the release runway (see [docs/INSTALL.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/INSTALL.md)).
+`pip install dos-kernel` is the whole install — if it worked in the demo,
+you're done here. The other rows exist for how *your* team works: **uv** if you
+want the CLI isolated from your project venv (faster than `pipx`, manages
+Python versions; `pipx install dos-kernel` works the same way), the clone if
+you're contributing. Homebrew / WinGet / Scoop one-liners are next on the
+release runway (see [docs/INSTALL.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/INSTALL.md)).
 
 A host repo adds DOS as a pinned dependency and points it at its own tree — never
 by vendoring the code in. DOS is stateless about which repo it serves: it
@@ -1095,3 +1107,8 @@ preparation. Until the arXiv ID lands, cite the repository:
 ## License
 
 MIT — see [LICENSE](https://github.com/anthony-chaudhary/dos-kernel/blob/master/LICENSE).
+
+<!-- The marker below is the official MCP Registry's PyPI ownership proof: the
+     registry only accepts a server.json naming the `dos-kernel` PyPI package if
+     this exact token appears in the published package README. Keep it intact. -->
+<!-- mcp-name: io.github.anthony-chaudhary/dos-kernel -->

{dos_kernel-0.23.4 → dos_kernel-0.24.1}/README.md

@@ -47,7 +47,7 @@ zero config, and the only thing you ever install is one small Python package.
 > ⏱️ **Want to try it right now?** Jump to **[Try it in 60 seconds](#try-it-in-60-seconds)**
 > — one command, real output, then come back for the why.
 
-<sub>**v0.23.4** · 3900+ tests · CI: Python 3.11–3.13 on Linux + a Windows 3.13
+<sub>**v0.24.1** · 3900+ tests · CI: Python 3.11–3.13 on Linux + a Windows 3.13
 smoke run · the only runtime dependency is **PyYAML** · **MIT**.</sub>
 
 > 🧭 **Want it in plain words first?** What DOS is, what it catches, and what
@@ -62,6 +62,13 @@ smoke run · the only runtime dependency is **PyYAML** · **MIT**.</sub>
 > your work, the ~5 files actually worth reading, and the architecture rules a
 > change must satisfy.
 
+> 🔤 **Five words the rest of this page leans on.** A **plan** is a named goal
+> (`AUTH`); a **phase** is one shippable step of it (`AUTH1`); a **lane** is the
+> slice of the file tree one agent may touch; the **oracle** is the part of DOS
+> that reads the evidence and rules; a **stamp** is the mark a shipped phase
+> leaves in a commit subject (`AUTH1: …`) — the thing the oracle greps for.
+> That's the whole vocabulary.
+
 <a id="who-this-is-for"></a>
 
 ## Who this is for
@@ -160,8 +167,8 @@ echo 'def login(): ...' > login.py
 git add -A
 git commit -m "AUTH1: ship the login endpoint"   # stamp AUTH1 shipped: <PHASE-ID>: <message>
 
-dos verify --workspace . AUTH AUTH1   # → SHIPPED     AUTH AUTH1 e389e8b (via grep-subject)   exit 0
-dos verify --workspace . AUTH AUTH2   # → NOT_SHIPPED  AUTH AUTH2          (via none)          exit 1
+dos verify --workspace . AUTH AUTH1   # → SHIPPED     AUTH AUTH1 <your-sha> (via grep-subject)  exit 0
+dos verify --workspace . AUTH AUTH2   # → NOT_SHIPPED  AUTH AUTH2            (via none)          exit 1
 ```
 
 An agent can claim `AUTH2` is done all day long; `verify` just reports what the
@@ -544,12 +551,15 @@ reads (wire it in `cli-config.yaml`). A new host's dialect is a driver, never a
 kernel edit.
 
 The flip side of that honesty: a host with **no** hook seam gets **no** dialect.
-ByteDance's **Trae** was proved out and has no hook system at all (no lifecycle
-events, no deny/allow stdout contract), so DOS binds to it advisory-only — the
-MCP server in `.trae/mcp.json`, a verify-before-"done" rule in
-`.trae/rules/project_rules.md`, the generic skills in `.trae/skills/` — and
-`dos init --hooks trae` fails loud rather than writing config Trae would never
-read ([docs/294](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/294_trae-advisory-only-the-host-with-no-hook-seam.md)).
+ByteDance's **Trae** was proved out and ships no user-scriptable hook system in
+its personal/international editions (no lifecycle events, no deny/allow stdout
+contract; its CN-enterprise edition announced one on 2026-06-09 with no
+published grammar yet), so DOS binds to it advisory-only — the MCP server in
+`.trae/mcp.json` (read alike by IDE-mode Agent, SOLO mode, and TRAE CLI), a
+verify-before-"done" rule in `.trae/rules/project_rules.md`, the generic
+skills in `.trae/skills/` — and `dos init --hooks trae` fails loud rather than
+writing config Trae would never read
+([docs/294](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/294_trae-advisory-only-the-host-with-no-hook-seam.md)).
 An invented envelope would be fake enforcement, which is the exact failure the
 dialect seam exists to prevent.
 
@@ -639,14 +649,14 @@ channel, upgrade/uninstall, WSL, troubleshooting) is in
 **[docs/INSTALL.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/INSTALL.md)**:
 
 ```bash
-# uv — the modern, fast, isolated CLI install (recommended):
-uv tool install dos-kernel        # `dos` + `dos-mcp` on PATH
-uvx --from dos-kernel dos doctor  # or run it once, ephemerally
-
-# pip — the library-consumer path (a host pins dos-kernel in its own venv):
+# pip — the default (the line the 60-second demo ran; also how a host pins it):
 pip install dos-kernel            # core kernel (PyYAML only)
 pip install "dos-kernel[mcp]"     # + the MCP server (dos-mcp)
 
+# uv — the isolated CLI install (keeps `dos` + `dos-mcp` off your project venv):
+uv tool install dos-kernel        # `dos` + `dos-mcp` on PATH
+uvx --from dos-kernel dos doctor  # or run it once, ephemerally
+
 # from a clone — editable, the contributor path (tracking unreleased master:
 # pip install "dos-kernel @ git+https://github.com/anthony-chaudhary/dos-kernel", no clone needed):
 git clone https://github.com/anthony-chaudhary/dos-kernel.git && cd dos-kernel
@@ -660,10 +670,12 @@ pip install -e .                  # editable: your edits are live in the install
 > `[mcp]` extra adds the MCP framework; `[tui]` adds the live `dos top` screens).
 > See [SECURITY.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/SECURITY.md), "Supply chain."
 
-Prefer a package manager? **uv** is the 2026 default — faster than `pipx`,
-isolates the tool, and manages Python versions; `pipx install dos-kernel` works
-the same way if your team already uses it. Homebrew / WinGet / Scoop one-liners
-are next on the release runway (see [docs/INSTALL.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/INSTALL.md)).
+`pip install dos-kernel` is the whole install — if it worked in the demo,
+you're done here. The other rows exist for how *your* team works: **uv** if you
+want the CLI isolated from your project venv (faster than `pipx`, manages
+Python versions; `pipx install dos-kernel` works the same way), the clone if
+you're contributing. Homebrew / WinGet / Scoop one-liners are next on the
+release runway (see [docs/INSTALL.md](https://github.com/anthony-chaudhary/dos-kernel/blob/master/docs/INSTALL.md)).
 
 A host repo adds DOS as a pinned dependency and points it at its own tree — never
 by vendoring the code in. DOS is stateless about which repo it serves: it
@@ -1046,3 +1058,8 @@ preparation. Until the arXiv ID lands, cite the repository:
 ## License
 
 MIT — see [LICENSE](https://github.com/anthony-chaudhary/dos-kernel/blob/master/LICENSE).
+
+<!-- The marker below is the official MCP Registry's PyPI ownership proof: the
+     registry only accepts a server.json naming the `dos-kernel` PyPI package if
+     this exact token appears in the published package README. Keep it intact. -->
+<!-- mcp-name: io.github.anthony-chaudhary/dos-kernel -->

{dos_kernel-0.23.4 → dos_kernel-0.24.1}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 # src/), and the console scripts stay `dos` / `dos-mcp` — only the pip-install /
 # dependency-pin name is `dos-kernel`. See SECURITY.md "Supply chain".
 name = "dos-kernel"
-version = "0.23.4"
+version = "0.24.1"
 description = "Dispatch Operating System — the domain-free trust substrate for fleets of autonomous agents (verdict spine, ship oracle, structured refusal, lane arbiter, correlation spine)."
 # The PyPI project page renders this. Point it at the README so the page isn't
 # blank below the metadata (twine warns when it's missing). PyPI resolves
@@ -136,6 +136,12 @@ dos = "dos.cli:main"
 # launches. Requires the `mcp` extra (`pip install dos-kernel[mcp]`); the import
 # of `mcp.server.fastmcp` fails loudly with an install hint if the extra is absent.
 dos-mcp = "dos_mcp.server:main"
+# A dist-name alias for the SAME server, so the uvx convention works: `uvx
+# "dos-kernel[mcp]"` runs the script named after the package (and the MCP
+# Registry's `uvx --from "dos-kernel[mcp]==X.Y.Z" dos-kernel` launch composes to
+# a real command — see server.json). Without the [mcp] extra it fails loudly
+# with the same install hint as `dos-mcp`. The umbrella CLI stays `dos`.
+dos-kernel = "dos_mcp.server:main"
 
 # The shipped LLM judge — the reference occupant of the JUDGE rung (`dos.judges`,
 # Axis 6). Registered as a discoverable judge (NOT a built-in: only `abstain` is

{dos_kernel-0.23.4 → dos_kernel-0.24.1}/src/dos/__init__.py

@@ -46,7 +46,7 @@ try:
 
     __version__ = _pkg_version("dos-kernel")
 except Exception:  # pragma: no cover - source-tree / not-installed fallback
-    __version__ = "0.23.4"
+    __version__ = "0.24.1"
 
 from dos import config  # noqa: F401  (re-export the seam as the package entry)
 from dos.config import (  # noqa: F401

{dos_kernel-0.23.4 → dos_kernel-0.24.1}/src/dos/cli.py

@@ -59,6 +59,7 @@ import dataclasses
 import json
 import os
 import sys
+import time
 from pathlib import Path
 from typing import Any
 
@@ -3152,6 +3153,53 @@ def cmd_lease_lane(args: argparse.Namespace) -> int:
     return 0 if d.outcome == "acquire" else 1
 
 
+# ---------------------------------------------------------------------------
+# override  (docs/296 — the operator's SELF_MODIFY override window: report or
+# disarm, NEVER arm. Arming is the operator's hand on the arm file by design —
+# any verb an agent's shell can call is an arming path an agent can take, so
+# the asymmetry IS the security property: anyone may disarm, only the human
+# arms. `status` exit code is the state: 0 armed / 1 disarmed-or-expired.)
+# ---------------------------------------------------------------------------
+def cmd_override(args: argparse.Namespace) -> int:
+    _apply_workspace(args)
+    from dos import override_facts as _ovr
+    import datetime as _dt
+    cfg = _config.active()
+    p = _ovr.arm_path(cfg.paths.root)
+
+    if args.override_cmd == "disarm":
+        # Always safe, for anyone — lowering the window can only restore the deny.
+        existed = p.exists()
+        if existed:
+            try:
+                p.unlink()
+            except OSError as e:
+                print(f"error: could not remove the arm file ({e})", file=sys.stderr)
+                return 2
+        print(json.dumps({"disarmed": existed, "path": str(p)}, sort_keys=True))
+        return 0
+
+    # status
+    facts = _ovr.read_override(cfg.paths.root)
+    now = _dt.datetime.now(_dt.timezone.utc)
+    if facts is None:
+        print(json.dumps({"armed": False, "path": str(p),
+                          "note": "no valid arm file — the SELF_MODIFY deny "
+                                  "stands (docs/296; arming is by hand)"},
+                         sort_keys=True))
+        return 1
+    armed = now <= facts.until
+    print(json.dumps({
+        "armed": armed,
+        "expired": not armed,
+        "until": facts.until.isoformat(),
+        "reason": facts.reason,
+        "scope": list(facts.scope),
+        "path": str(p),
+    }, sort_keys=True))
+    return 0 if armed else 1
+
+
 # ---------------------------------------------------------------------------
 # halt  (docs/99 — record a STOP DECISION for an in-flight run + propose the
 #   (full prose: docs/CLI.md § "halt  (docs/99 — record a STOP DECISION for an in-flight run")
@@ -3290,6 +3338,33 @@ def cmd_guard(args: argparse.Namespace) -> int:
 # ---------------------------------------------------------------------------
 # hook stop  (the verify-on-stop binding — docs/134 §2/§2.2)
 # ---------------------------------------------------------------------------
+def _record_hook_observation(cfg, *, verb: str, outcome: str, started: float,
+                             debug: bool = False, **fields) -> None:
+    """Append one `hook-observation` record for a DECIDED hook call (docs/297 P3).
+
+    The Python hook verbs' half of the kernel-owned observation contract
+    (`dos.hook_observation`) — the second conforming writer beside the native
+    binary. Called only AFTER a verb has decided + emitted, with the
+    `time.monotonic()` the verb captured at entry, so telemetry stays strictly
+    downstream of the decision (docs/99). The native-served path never reaches
+    this (the binary already recorded its own observation); a DELEGATED call
+    does — its record is the call's real verdict, which is exactly what the
+    docs/297 denominator rule pairs with the binary's `delegate` handoff row.
+    Fail-soft by construction: any fault is swallowed, so a telemetry write can
+    never change a verdict, a dialect, or an exit code.
+    """
+    try:
+        from dos import hook_observation as _hobs
+        entry = _hobs.observation_entry(
+            verb, outcome,
+            latency_ms=round((time.monotonic() - started) * 1000.0, 3),
+            run_id=os.environ.get("CID_RUN_ID", "") or "",
+            **fields)
+        _hobs.append(entry, cfg=cfg, debug=debug)
+    except Exception:  # noqa: BLE001 — telemetry is advisory, never load-bearing
+        return
+
+
 def cmd_hook_stop(args: argparse.Namespace) -> int:
     """A `Stop`/`SubagentStop` hook: refuse to let an agent stop on a false done.
 
@@ -3297,6 +3372,8 @@ def cmd_hook_stop(args: argparse.Namespace) -> int:
     """
     from dos import claim_extract
 
+    started = time.monotonic()
+
     # 1. Read the hook event from stdin (the host's contract). Any failure → let
     #    the agent stop (we never block on our own inability to read).
     event: dict = {}
@@ -3380,6 +3457,8 @@ def cmd_hook_stop(args: argparse.Namespace) -> int:
         # Nothing the agent confidently claimed → nothing to check. Let it stop.
         _emit_help_digest(event, cfg=_config.active(), args=args)
         _emit(blocked=False, results=[], checked=0)
+        _record_hook_observation(_config.active(), verb="stop", outcome="no-claims",
+                                 started=started, debug=bool(getattr(args, "debug", False)))
         return 0
 
     # 5. Verify each claim against git (the truth syscall). Block on a NOT_SHIPPED
@@ -3410,11 +3489,20 @@ def cmd_hook_stop(args: argparse.Namespace) -> int:
             f"(with the ship-stamp grammar) or correct the claim before stopping."
         )
         _emit(blocked=True, reason=reason, results=results)
+        _record_hook_observation(cfg, verb="stop", outcome="block", started=started,
+                                 debug=bool(getattr(args, "debug", False)),
+                                 claims_seen=len(claims),
+                                 verify_source=str(failures[0].get("source") or ""),
+                                 blocked_plan=str(failures[0].get("plan") or ""),
+                                 blocked_phase=str(failures[0].get("phase") or ""))
         return 0  # exit 0 + {"decision":"block"} is CC's "keep working" signal
 
     # Every actionable claim verified. Let the agent stop.
     _emit_help_digest(event, cfg=cfg, args=args)
     _emit(blocked=False, results=results, checked=len(results))
+    _record_hook_observation(cfg, verb="stop", outcome="all-verified", started=started,
+                             debug=bool(getattr(args, "debug", False)),
+                             claims_seen=len(claims))
     return 0
 
 
@@ -3462,6 +3550,7 @@ def cmd_hook_marker(args: argparse.Namespace) -> int:
     from dos import marker_gate as _mg
     from dos import marker_sensor as _ms
 
+    started = time.monotonic()
     debug = bool(getattr(args, "debug", False))
 
     def _dbg(msg: str) -> None:
@@ -3549,6 +3638,14 @@ def cmd_hook_marker(args: argparse.Namespace) -> int:
     _dbg(f"emitted={emitted} max={cap} allow={decision.allow} "
          f"reason={budget_reason} ({arm.reason})")
 
+    # docs/297 P3: one observation per ARMED budget decision (an unarmed ordinary
+    # turn reached no verdict — nothing to record). Downstream of the classify;
+    # the emission below follows deterministically from `decision.allow`.
+    _record_hook_observation(cfg, verb="marker",
+                             outcome="allow" if decision.allow else "refuse",
+                             started=started, debug=debug,
+                             marker_count=decision.noop_turns, max_markers=cap)
+
     if args.json:
         # A machine-readable surface for tooling / non-CC hosts — never the bytes CC
         # reads. Mirrors `cmd_hook_stop --json`.
@@ -3598,6 +3695,7 @@ def cmd_hook_posttool(args: argparse.Namespace) -> int:
     """
     from dos import posttool_sensor as _pts
 
+    started = time.monotonic()
     debug = bool(getattr(args, "debug", False))
 
     def _dbg(msg: str) -> None:
@@ -3688,6 +3786,7 @@ def cmd_hook_posttool(args: argparse.Namespace) -> int:
     _dbg(f"verdict={verdict.state} repeat_run={verdict.repeat_run} "
          f"step_index={step_index} run_id={firing_run_id or '-'} "
          f"warn={'yes' if payload else 'no'}")
+    warn_emitted = False
     if payload is not None:
         # The ONLY thing on stdout: the host's PostToolUse dialect. `warn_payload`
         #   (full prose: docs/CLI.md § "The ONLY thing on stdout: the host's PostToolUse dialect. `w")
@@ -3700,6 +3799,11 @@ def cmd_hook_posttool(args: argparse.Namespace) -> int:
             host_dialect = None
         if host_dialect is not None:
             print(json.dumps(host_dialect, sort_keys=True))
+            warn_emitted = True
+    _record_hook_observation(cfg, verb="posttool",
+                             outcome="warn" if warn_emitted else "passthrough",
+                             started=started, debug=debug,
+                             stream_state=verdict.state.value)
     return 0
 
 
@@ -3710,6 +3814,7 @@ def cmd_hook_pretool(args: argparse.Namespace) -> int:
     """
     from dos import pretool_sensor as _prt
 
+    started = time.monotonic()
     debug = bool(getattr(args, "debug", False))
 
     def _dbg(msg: str) -> None:
@@ -3810,6 +3915,20 @@ def cmd_hook_pretool(args: argparse.Namespace) -> int:
             host_dialect = None
         if host_dialect is not None:
             print(json.dumps(host_dialect, sort_keys=True))
+
+    # 7. docs/297 P3: one observation per decided call — THE denominator record
+    #    (one pretool record = one tool call adjudicated). On the native fast path
+    #    the binary recorded its own; this is the Python-decided record, including
+    #    the call a binary DELEGATED here (the docs/297 pairing). Fail-soft,
+    #    strictly downstream of the emitted dialect.
+    from dos.hook_dialect import DEFAULT_DIALECT as _default_dialect
+    _record_hook_observation(cfg, verb="pretool", outcome=str(decision),
+                             started=started, debug=debug,
+                             rung=str(outcome.get("rung") or ""),
+                             reason_class=str(outcome.get("reason_class") or ""),
+                             dialect=str(getattr(args, "dialect", None) or _default_dialect),
+                             tree_known=(bool(outcome["tree_known"])
+                                         if "tree_known" in outcome else None))
     return 0
 
 
@@ -4915,8 +5034,29 @@ def cmd_helped(args: argparse.Namespace) -> int:
     summary = _help.summarize(records, holder=holder, since=since,
                               with_examples=explain or bool(getattr(args, "json", False)))
 
+    # The denominator (docs/297 P2, issue #24): the per-call hook-observation log,
+    # read ONCE at this boundary. Like-for-like only — BOTH sides of the rate come
+    # from that one log; the lane-journal counts above never enter it. Graceful
+    # absence: no log / nothing adjudicated / an unreadable file → rate stays None
+    # and every output below is byte-identical to the rate-less form. A --session
+    # scope also suppresses it (observation records carry no session key, so a
+    # session-scoped rate would silently widen to the whole fleet — dishonest).
+    rate = None
+    if not holder:
+        from dos import hook_observation as _hobs
+        try:
+            folded = _hobs.intervention_rate(
+                _hobs.read_observations(cfg=cfg), since=since)
+            if folded.adjudicated > 0:
+                rate = folded
+        except Exception:  # noqa: BLE001 — a rate fold fault degrades to "no rate line"
+            rate = None
+
     if getattr(args, "json", False):
-        print(json.dumps(summary.to_dict(), indent=2, default=str))
+        payload = summary.to_dict()
+        if rate is not None:
+            payload["tool_calls"] = rate.to_dict()
+        print(json.dumps(payload, indent=2, default=str))
         return 0
 
     scope = ""
@@ -4927,7 +5067,7 @@ def cmd_helped(args: argparse.Namespace) -> int:
     if explain:
         print(_help.render_explain_text(summary, scope=scope))
     else:
-        print(_help.render_summary_text(summary, scope=scope))
+        print(_help.render_summary_text(summary, scope=scope, rate=rate))
     return 0
 
 
@@ -5364,6 +5504,21 @@ def cmd_doctor(args: argparse.Namespace) -> int:
         bound = ", ".join(wired_bits) if wired_bits else "none wired"
         print(f"runtime hooks       {bound}"
               + ("" if wired_bits else "   (run `dos init --hooks <runtime>` to bind)"))
+    # docs/296 — the operator's SELF_MODIFY override window, made visible: an
+    # armed window changes what the PRE hook will admit, so the report that
+    # answers "what am I configured as?" must show it. Read-only, fail-soft.
+    try:
+        from dos import override_facts as _ovr
+        import datetime as _dt
+        _facts = _ovr.read_override(cfg.paths.root)
+        if _facts is not None and _dt.datetime.now(_dt.timezone.utc) <= _facts.until:
+            _scope = ", ".join(_facts.scope) if _facts.scope else "the whole runtime set"
+            print(f"self-mod override   ARMED until {_facts.until.isoformat()} "
+                  f"({_facts.reason}) — scope: {_scope}")
+        else:
+            print("self-mod override   disarmed")
+    except Exception:  # noqa: BLE001 — a report row must never break doctor
+        print("self-mod override   disarmed")
     print(f"layout style        {cfg.paths.style}")
     # The environment print (docs/115): *under what* this kernel adjudicates. The
     #   (full prose: docs/CLI.md § "The environment print (docs/115): *under what* this kernel a")
@@ -7985,6 +8140,23 @@ def build_parser() -> argparse.ArgumentParser:
     lll.add_argument("--pretty", action="store_true")
     pll.set_defaults(func=cmd_lease_lane)
 
+    # override — the operator's SELF_MODIFY override window (docs/296): report
+    # or disarm. Deliberately NO `arm` subcommand — arming is the operator's
+    # hand on `.dos/override/self-modify.toml`, never a verb an agent can call.
+    pov = sub.add_parser(
+        "override",
+        help="the operator's SELF_MODIFY override window: status / disarm "
+             "(arming is by hand — docs/296)")
+    _add_workspace_flags(pov)
+    ovsub = pov.add_subparsers(dest="override_cmd", required=True)
+    ovsub.add_parser(
+        "status",
+        help="report the armed window (exit 0 armed / 1 disarmed-or-expired)")
+    ovsub.add_parser(
+        "disarm",
+        help="delete the arm file — always safe, for anyone (restores the deny)")
+    pov.set_defaults(func=cmd_override)
+
     # halt — record a STOP DECISION for an in-flight run + propose the command
     #   (full prose: docs/CLI.md § "halt — record a STOP DECISION for an in-flight run + propose")
     phl = sub.add_parser(

{dos_kernel-0.23.4 → dos_kernel-0.24.1}/src/dos/help_summary.py

@@ -433,12 +433,39 @@ def nudge_line(summary: HelpSummary) -> str:
     )
 
 
-def render_summary_text(summary: HelpSummary, *, scope: str = "") -> str:
+def _rate_lines(rate) -> list[str]:
+    """The "of N adjudicated calls" block for an `InterventionRate`, or []. Pure.
+
+    The docs/297 denominator line. `rate` is a `dos.hook_observation
+    .InterventionRate` (duck-typed: `adjudicated`/`passed`/`intervened` + the
+    `*_pct` properties) — every number in it came from ONE observation log, by
+    construction of that fold. None, or zero adjudicated calls, renders nothing
+    at all, so a workspace without an observation log keeps today's bytes. The
+    trailing note is the honesty caveat: the rate's log and the catch counts'
+    journal have different windows and scopes, so the two never share a number.
+    """
+    if rate is None or rate.adjudicated <= 0:
+        return []
+    return [
+        "",
+        (f"  of {rate.adjudicated} tool calls adjudicated by the hooks, "
+         f"{rate.passed} passed untouched ({rate.passed_pct:.1f}%) and "
+         f"{rate.intervened} were intervened on ({rate.intervened_pct:.1f}%)"),
+        ("    (from the per-call hook observation log — its window and scope "
+         "differ from the catch counts above)"),
+    ]
+
+
+def render_summary_text(summary: HelpSummary, *, scope: str = "",
+                        rate=None) -> str:
     """The full `dos helped` operator rollup — headline + breakdowns. Pure.
 
     Leads with the headline count, then the by-reason-class and by-tool tables (the
     "what kind of help, on which tool" an operator wants), and an honest footer
     noting how many firings were observe-only (recorded but not a behavior-change).
+    `rate` (docs/297) is an optional `hook_observation.InterventionRate` — when
+    present it adds the self-contained "of N adjudicated calls" block; when None
+    (no observation log) the output is byte-identical to the rate-less form.
     """
     out: list[str] = []
     title = "# dos helped"
@@ -465,7 +492,9 @@ def render_summary_text(summary: HelpSummary, *, scope: str = "") -> str:
         if summary.enforced:
             out.append(f"  ({summary.enforced} enforcement record(s) seen, "
                        f"all observe-only)")
+        out.extend(_rate_lines(rate))
         return "\n".join(out)
+    out.extend(_rate_lines(rate))
     if summary.by_reason:
         out.append("")
         out.append("  by reason")