chad-code 2.1.0__tar.gz → 2.3.0__tar.gz

chad_code-2.3.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: chad-code
+Version: 2.3.0
+Summary: Claude-Code-style coding agent that runs entirely on a 24 GB Apple Silicon Mac (MLX, Qwen3.8-27B)
+License-Expression: MIT
+Project-URL: Repository, https://github.com/nathansutton/chad
+Project-URL: Issues, https://github.com/nathansutton/chad/issues
+Keywords: mlx,coding-agent,apple-silicon,local-llm,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mlx!=0.32.1,<=0.32.2,>=0.32.0; sys_platform == "darwin"
+Requires-Dist: mlx-lm<0.32,>=0.31.3; sys_platform == "darwin"
+Requires-Dist: transformers<5.13,>=5.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: huggingface-hub>=1.22.0
+Requires-Dist: prompt_toolkit>=3.0.43
+Requires-Dist: tree-sitter>=0.26.0
+Requires-Dist: tree-sitter-language-pack>=1.12.2
+Requires-Dist: mcp<3,>=2
+Requires-Dist: gguf<0.20,>=0.19.0
+Provides-Extra: highlight
+Requires-Dist: pygments>=2.17; extra == "highlight"
+Provides-Extra: speech
+Requires-Dist: sounddevice>=0.5; extra == "speech"
+Dynamic: license-file
+
+# chad: a coding agent for your macbook pro
+
+[![tests](https://github.com/nathansutton/chad/actions/workflows/tests.yml/badge.svg)](https://github.com/nathansutton/chad/actions/workflows/tests.yml)
+
+<img src="docs/claude-vs-chad.jpg" width="50%" alt="Two staircase newel posts side by side: Claude is a hand-carved wooden horse head, chad is a scuffed plastic toy horse tied on with twine">
+
+> Claude can do anything, for anyone, anywhere. chad does one thing. 🗿
+> *Coding under supervision.*
+
+chad is a coding agent that runs entirely on an Apple Silicon Mac via
+[MLX](https://github.com/ml-explore/mlx). One 27B model and no API key.
+(Not affiliated with Anthropic.)
+
+```bash
+uvx chad-code          # runs anywhere; the command is still `chad`
+uvx chad-code prove    # offline smoke test: 4 tiny fix-it tasks, verified, timed 🗿
+```
+
+The first run asks, then downloads the model once (~14 GB). The PyPI package is `chad-code`.
+
+![chad fixing a failing test end to end: reason, read, edit, run pytest, confirm green, all on a local model](docs/demo.gif)
+
+> Real session, unedited.
+
+## Why chad
+
+Plenty of harnesses run local models now, and [pi](https://pi.dev) is a fantastic default
+for the same reason llama.cpp is: it works with everything. chad is moving the opposite direction.
+
+**1 set of silicon**.  This project is focused on making the macbook pro you already have usable.  Not a $10K GPU.
+
+**1 capable model**. `Qwen 3.8 27B`.  This isn't the frontier, but you probably aren't solving frontier problems.  Focus on 1 model buys _speed_.  You'll experience ~ 20 tokens/second generation in a real session instead of ~ 10 tokens/second for stock llama.cpp implementations.  This speed comes from MLX, a couple of targeted custom kernels for this model, and a bundled dflash2 drafter.  The weights are Unsloth's `UD-Q3_K_XL` GGUF, read natively in MLX.  We shipped a smaller ternary build first and it was measurably worse; [here's why we switched](docs/design.md#the-weights).
+
+**1 tightly-coupled agent loop**.  Instead of a standard /completions endpoint, the agent loop in chad owns the backend process.  This comes with nice advantages that make the KV cache more stable and the coding experience measurably better (no long prefills!).  
+
+## Why not
+
+You do not have an Apple Silicon with 24 GB RAM.  You want to pick your local model.  You need a frontier model in a data center.  The list goes on. 
+
+## Documentation
+
+- [Installing & using chad](docs/usage.md) covers install, extras and upgrades, the
+  terminal UI, and the command-line flags.
+- [Throughput & performance](docs/benchmarks.md) has every number above, the stock-engine
+  comparison, the model, and how to reproduce them with `chad-bench`.
+- [Design](docs/design.md) is the argument: why the agent owns the engine, why there are
+  five tools, and what 1.x got wrong.
+- [Architecture](docs/architecture.md) is the module map, the session file format and the
+  tool-call wire format.
+- [Configuration reference](docs/configuration.md) documents project instructions, Agent
+  Skills, MCP servers, plan mode, the slash commands, the context window, every environment
+  variable, and the safety opt-outs.
+- [Troubleshooting](docs/troubleshooting.md) maps symptoms to knobs for when a session
+  rambles, loops, or slows.
+- [Contributing](CONTRIBUTING.md) says what lands easily and what needs a conversation
+  first.

chad_code-2.3.0/README.md

@@ -0,0 +1,56 @@
+# chad: a coding agent for your macbook pro
+
+[![tests](https://github.com/nathansutton/chad/actions/workflows/tests.yml/badge.svg)](https://github.com/nathansutton/chad/actions/workflows/tests.yml)
+
+<img src="docs/claude-vs-chad.jpg" width="50%" alt="Two staircase newel posts side by side: Claude is a hand-carved wooden horse head, chad is a scuffed plastic toy horse tied on with twine">
+
+> Claude can do anything, for anyone, anywhere. chad does one thing. 🗿
+> *Coding under supervision.*
+
+chad is a coding agent that runs entirely on an Apple Silicon Mac via
+[MLX](https://github.com/ml-explore/mlx). One 27B model and no API key.
+(Not affiliated with Anthropic.)
+
+```bash
+uvx chad-code          # runs anywhere; the command is still `chad`
+uvx chad-code prove    # offline smoke test: 4 tiny fix-it tasks, verified, timed 🗿
+```
+
+The first run asks, then downloads the model once (~14 GB). The PyPI package is `chad-code`.
+
+![chad fixing a failing test end to end: reason, read, edit, run pytest, confirm green, all on a local model](docs/demo.gif)
+
+> Real session, unedited.
+
+## Why chad
+
+Plenty of harnesses run local models now, and [pi](https://pi.dev) is a fantastic default
+for the same reason llama.cpp is: it works with everything. chad is moving the opposite direction.
+
+**1 set of silicon**.  This project is focused on making the macbook pro you already have usable.  Not a $10K GPU.
+
+**1 capable model**. `Qwen 3.8 27B`.  This isn't the frontier, but you probably aren't solving frontier problems.  Focus on 1 model buys _speed_.  You'll experience ~ 20 tokens/second generation in a real session instead of ~ 10 tokens/second for stock llama.cpp implementations.  This speed comes from MLX, a couple of targeted custom kernels for this model, and a bundled dflash2 drafter.  The weights are Unsloth's `UD-Q3_K_XL` GGUF, read natively in MLX.  We shipped a smaller ternary build first and it was measurably worse; [here's why we switched](docs/design.md#the-weights).
+
+**1 tightly-coupled agent loop**.  Instead of a standard /completions endpoint, the agent loop in chad owns the backend process.  This comes with nice advantages that make the KV cache more stable and the coding experience measurably better (no long prefills!).  
+
+## Why not
+
+You do not have an Apple Silicon with 24 GB RAM.  You want to pick your local model.  You need a frontier model in a data center.  The list goes on. 
+
+## Documentation
+
+- [Installing & using chad](docs/usage.md) covers install, extras and upgrades, the
+  terminal UI, and the command-line flags.
+- [Throughput & performance](docs/benchmarks.md) has every number above, the stock-engine
+  comparison, the model, and how to reproduce them with `chad-bench`.
+- [Design](docs/design.md) is the argument: why the agent owns the engine, why there are
+  five tools, and what 1.x got wrong.
+- [Architecture](docs/architecture.md) is the module map, the session file format and the
+  tool-call wire format.
+- [Configuration reference](docs/configuration.md) documents project instructions, Agent
+  Skills, MCP servers, plan mode, the slash commands, the context window, every environment
+  variable, and the safety opt-outs.
+- [Troubleshooting](docs/troubleshooting.md) maps symptoms to knobs for when a session
+  rambles, loops, or slows.
+- [Contributing](CONTRIBUTING.md) says what lands easily and what needs a conversation
+  first.

{chad_code-2.1.0 → chad_code-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@
 # import name, and command name are independent. `uvx chad-code` runs the alias
 # script added under [project.scripts].
 name = "chad-code"
-version = "2.1.0"
+version = "2.3.0"
 description = "Claude-Code-style coding agent that runs entirely on a 24 GB Apple Silicon Mac (MLX, Qwen3.8-27B)"
 readme = "README.md"
 license = "MIT"
@@ -75,6 +75,11 @@ dependencies = [
     # negotiates protocol 2026-07-28; the 1.x line tops out at 2025-11-25. Capped <3:
     # the same class of break will happen again.
     "mcp>=2,<3",
+    # GGUF checkpoints (gguf_pack.py): the header reader and the numpy block decoders the
+    # Metal kernels are tested against. Capped <0.20: the reader's field layout and the
+    # quant-type enum are what the loader routes on, and 0.19.0 is the line it was
+    # written and checked against.
+    "gguf>=0.19.0,<0.20",
 ]
 
 # Extras ride on the INSTALL SPEC, so the command depends on how chad was installed:
@@ -143,8 +148,7 @@ testpaths = ["tests"]
 
 [tool.ruff]
 line-length = 100
-# Vendored Exercism exercises (benchmarks/matrix/tasks/) are upstream files, kept byte-identical.
-extend-exclude = ["benchmarks/matrix/tasks", "tools/anti_slop"]  # vendored linter: not chad's style
+extend-exclude = ["tools/anti_slop"]  # vendored linter: not chad's style
 src = ["src", "tests"]
 
 [tool.ruff.lint]
@@ -169,7 +173,9 @@ ignore = ["E741"]  # ambiguous var names (l/I) appear in existing math code
 
 [tool.mypy]
 python_version = "3.11"
-files = ["src/chad"]
+files = ["src/chad", "benchmarks/polyglot"]
+# The kit's underscore dirs hold fetched exercises, trial workspaces and model output.
+exclude = ['^benchmarks/polyglot/_']
 ignore_missing_imports = true   # mlx/tree_sitter/mcp ship partial or no stubs
 warn_unused_ignores = true
 implicit_optional = true        # `x: T = None` defaults are idiomatic throughout; this
@@ -215,7 +221,7 @@ exclude = [
     ".agents/**",
     ".claude/**",
     "src/chad/parakeet/**",          # vendored upstream, not held to chad's gate (see ruff/mypy)
-    "benchmarks/matrix/tasks/**",    # vendored Exercism exercises, kept byte-identical
+    "benchmarks/polyglot/_*/**",     # fetched exercises, trial workspaces, model output
     "tools/anti_slop/**",
 ]
 # Pre-existing findings live in the baseline (regenerate: `make slop-baseline`). A run

{chad_code-2.1.0 → chad_code-2.3.0}/src/chad/__init__.py

@@ -4,7 +4,7 @@ A flat collection of cooperating modules behind one console script (``chad``):
 the inference engine, the tool layer, the agent loop, and the terminal UI.
 """
 
-__version__ = "2.1.0"
+__version__ = "2.3.0"
 
 # chad sets no MLX_* runtime vars. MLX_METAL_FAST_SYNCH, MLX_MAX_OPS_PER_BUFFER
 # and MLX_MAX_MB_PER_BUFFER were each measured end-to-end on the 35B and every

{chad_code-2.1.0 → chad_code-2.3.0}/src/chad/agent.py

@@ -584,7 +584,7 @@ class Agent:
         # ATIF trajectory capture, off unless CHAD_TRAJECTORY_JSON is set.
         self._atif = atif.recorder()
         self._atif_seg = self._atif.new_segment() if self._atif else None
-        self._atif_stats: list = []   # one entry per successful generate, in step order
+        self._atif_stats: list[atif.StepStat] = []   # one per stored assistant turn, in order
         if self._atif and self._atif.model_name is None:
             self._atif.model_name = engine.model_id
         self.interrupted = False
@@ -753,6 +753,12 @@ class Agent:
         self._split_ok = ok
         return ok
 
+    def _template_extra(self) -> dict:
+        """The template kwargs beyond messages/tools/thinking: the reasoning effort,
+        when one is set (the user's, else the engine's loader-carried default)."""
+        effort = self.reasoning_effort or self.engine.reasoning_effort_default
+        return {"reasoning_effort": effort} if effort else {}
+
     def _render(self, thinking: bool = None):
         # `thinking` overrides self.thinking for THIS render only (no-think
         # escalation renders one step with <think> off, then restores). None => self.thinking.
@@ -772,13 +778,14 @@ class Agent:
         # malformed TypeScript it cannot repair. `low` keeps the reasoning block and
         # shrinks it. Passed only when set, and via **kwargs, so templates that do not
         # accept the argument (q3_s6's, which has no reasoning_effort at all) render
-        # byte-identically to before.
-        extra = {}
-        if self.reasoning_effort:
-            extra["reasoning_effort"] = self.reasoning_effort
+        # byte-identically to before. A loader may carry a default of its own
+        # (engine.reasoning_effort_default) for a template whose default it disagrees
+        # with; the user's setting still wins. `_prefix_ids` renders with the same
+        # kwargs: the effort lands in the system block, so a prefix priced without
+        # it would not be a prefix of the prompt.
         ids = self._template_ids(self.engine.tok.apply_chat_template(
             messages, tools=self._active_schemas(), add_generation_prompt=True,
-            enable_thinking=thinking, **extra,
+            enable_thinking=thinking, **self._template_extra(),
         ))
         # Debug hook (env-gated, off by default): dump the first decoded render so a
         # rendered-prompt difference across environments can be diffed. Best-effort.
@@ -808,7 +815,8 @@ class Agent:
         def render1(u):
             return self._template_ids(self.engine.tok.apply_chat_template(
                 [sysm, {"role": "user", "content": u}], tools=schemas,
-                add_generation_prompt=True, enable_thinking=self.thinking))
+                add_generation_prompt=True, enable_thinking=self.thinking,
+                **self._template_extra()))
         a, b = render1("a"), render1("the quick brown fox jumps")
         n = 0
         for x, y in zip(a, b):
@@ -835,7 +843,8 @@ class Agent:
         def render1(m):
             return self._template_ids(self.engine.tok.apply_chat_template(
                 [m, {"role": "user", "content": "a"}], tools=schemas,
-                add_generation_prompt=True, enable_thinking=self.thinking))
+                add_generation_prompt=True, enable_thinking=self.thinking,
+                **self._template_extra()))
         a, b = render1({"role": "system", "content": static}), render1(sysm)
         n = 0
         for x, y in zip(a, b):
@@ -905,6 +914,7 @@ class Agent:
         if self._atif is None or self._atif_seg is None:
             return
         try:
+            self._atif.set_pending(self._atif_seg, None)   # its message has landed by now
             self._atif.set_segment(
                 self._atif_seg,
                 atif.steps_from_messages(self.messages, self._atif.model_name,
@@ -913,6 +923,18 @@ class Agent:
         except Exception as e:      # never let telemetry break a turn
             log.warning("atif: sync failed: %s", e)
 
+    def _atif_pending(self, text: str, thinking: bool, generated: int, started: str) -> None:
+        """Show the step still being generated: the one a runaway `<think>` never finishes,
+        and so the one a rebuild from `messages` can never contain."""
+        if self._atif is None or self._atif_seg is None:
+            return
+        try:
+            self._atif.set_pending(self._atif_seg, atif.pending_step(
+                text, thinking, self._atif.model_name, generated, started))
+            self._atif.dump()
+        except Exception as e:      # never let telemetry break a turn
+            log.warning("atif: pending dump failed: %s", e)
+
     def run_turn(self, user_text: str, stream=True):
         """Thin wrapper so the trajectory is flushed on EVERY exit from the turn —
         normal return, interrupt, or an exception escaping the loop. Harbor SIGKILLs chad
@@ -1176,11 +1198,18 @@ class Agent:
 
             view = _StreamView(self._emit, started_in_think=step_thinking) if stream else None
             gen_count = [0]  # decoded chunks this step (~tokens); fed to the live ↓ counter
+            atif_parts: list[str] = []      # this step's text so far, kept only when recording
+            atif_started = atif.now() if self._atif else ""
 
             def on_token(t):
                 if view:
                     view.feed(t)
                 gen_count[0] += 1
+                if self._atif:
+                    atif_parts.append(t)
+                    if gen_count[0] % atif.PENDING_EVERY == 0:
+                        self._atif_pending("".join(atif_parts), step_thinking,
+                                           gen_count[0], atif_started)
                 # Throttle: a status emit per ~16 tokens keeps the queue cheap while the
                 # bottom-line ↓ counter still climbs visibly (the refresher renders ~20 Hz).
                 if gen_count[0] % 16 == 0:
@@ -1224,12 +1253,6 @@ class Agent:
             # non-trimmable cache its decoded text won't re-tokenize identically, so it
             # also forces the next-step re-prefill). Tracked so the no-call branch can
             # tell "truncated mid-thought" apart from "deliberately answered."
-            if self._atif:   # one entry per SUCCESSFUL generate — a retried step appends
-                             # nothing, keeping this list aligned with assistant messages
-                self._atif_stats.append(
-                    {"prompt_tokens": stats.prompt_tokens,
-                     "cached_tokens": stats.cached_tokens,
-                     "generated_tokens": stats.generated_tokens})
             hit_cap = stats.generated_tokens >= self.max_gen_tokens
             # Close-and-continue fired: the engine force-closed a runaway <think>
             # and decoded the action in the same step. Counted for autopsy (a salvaged step
@@ -1259,6 +1282,40 @@ class Agent:
             # content.
             text = _SPECIAL_TOKEN_RE.sub("", text).rstrip()
 
+            # Estimate reasoning overhead: the generation opens inside <think> (the
+            # template emits the opening tag), so everything up to </think> is thinking,
+            # and a thinking step that never closed the block — cut by a soft cap, the
+            # token cap or an interrupt — is reasoning end to end. Counted before the
+            # interrupt return below: the step a wall clock cuts is the runaway think,
+            # and dropping it made the longest reasoning in a run read as none at all.
+            # (A repetition stop that fired after </think> takes the fraction path.)
+            if "</think>" in text:
+                frac = len(text.split("</think>", 1)[0]) / len(text)
+                _think_delta = int(stats.generated_tokens * frac)
+            elif step_thinking or stats.stop_condition_fired:
+                _think_delta = stats.generated_tokens
+            else:
+                _think_delta = 0
+            self.think_tokens += _think_delta
+            if self._atif and text:   # one entry per STORED assistant turn — an interrupt
+                                      # with no text stores none, and the list stays aligned
+                finish = ("interrupted" if self._should_stop() else
+                          "max_tokens" if hit_cap else
+                          "repeat_stop" if rep_fired[0] else
+                          "think_cap" if stats.stop_condition_fired else "eos")
+                self._atif_stats.append(atif.StepStat(
+                    prompt_tokens=stats.prompt_tokens, cached_tokens=stats.cached_tokens,
+                    generated_tokens=stats.generated_tokens, think_tokens=_think_delta,
+                    prefill_s=stats.prefill_s, gen_s=stats.gen_s, forwards=stats.forwards,
+                    draft_proposed=stats.draft_proposed,
+                    draft_accepted=stats.draft_accepted, finish=finish,
+                    salvaged=stats.salvaged, compacted=compacted,
+                    # "before </think>" is reasoning only when the step opened in a
+                    # think block; a no-think step drafted its whole turn as action.
+                    draft_hist_think=stats.draft_hist if step_thinking else {},
+                    draft_hist_act=stats.draft_hist_acting if step_thinking
+                    else stats.draft_hist))
+
             # Interrupted (often mid-prefill, so text is empty): stop cleanly without
             # appending an empty assistant turn.
             if self._should_stop():
@@ -1275,22 +1332,6 @@ class Agent:
             self.messages.append({"role": "assistant",
                                   "content": close_unclosed_think(text, step_thinking)})
 
-            # Estimate reasoning overhead: the generation opens inside <think> (the
-            # template emits the opening tag), so everything up to </think> is thinking.
-            # A soft-cap stop fires only while still inside <think>, so ALL of
-            # this step's tokens are reasoning — count them so think-token telemetry (the
-            # metric the budget is measured against) doesn't under-report the capped runs.
-            # (A repetition stop can also land inside think — same accounting; one that
-            # fired after </think> falls to the fraction path below like any other turn.)
-            if stats.stop_condition_fired and "</think>" not in text:
-                _think_delta = stats.generated_tokens
-            elif "</think>" in text and len(text):
-                frac = len(text.split("</think>", 1)[0]) / len(text)
-                _think_delta = int(stats.generated_tokens * frac)
-            else:
-                _think_delta = 0
-            self.think_tokens += _think_delta
-
             # Per-step first, turn-cumulative second. The cumulative ratio alone can't
             # show a step where drafting actually paid: a run of span-heavy tool-call
             # args is a few hundred tokens against a whole turn's proposals, so it moves

{chad_code-2.1.0 → chad_code-2.3.0}/src/chad/atif.py

@@ -1,13 +1,13 @@
 """ATIF (Agent Trajectory Interchange Format) v1.7 trajectory emitter.
 
-The Terminal-Bench leaderboard requires an ATIF trajectory for **every passing trial**
-(the Apr-2026 "Leaderboard Integrity Update"). Harbor's built-in agents get this for free
-by subclassing its agent base; chad is driven as a CLI, so it has to emit the document
-itself or a submission is rejected.
+A trial's row says whether it passed; its trajectory says where the tokens and the seconds
+went, step by step, and `benchmarks/polyglot/trace.py` reads one back as a table — even
+while the trial is still running. The document is ATIF, Harbor's published schema, rather
+than a private format, so a trajectory another harness wrote reads the same way.
 
-Set `CHAD_TRAJECTORY_JSON=/path/trajectory.json` to turn this on. It is a pure observer:
-nothing here changes agent behavior, and any failure is swallowed (a benchmark harness
-must never lose a trial because telemetry broke).
+Set `CHAD_TRAJECTORY_JSON=/path/trajectory.json`, or call `start()`, to turn this on. It
+is a pure observer: nothing here changes agent behavior, and any failure is swallowed (a
+benchmark harness must never lose a trial because telemetry broke).
 
 **Why derive from `agent.messages` rather than instrument the tool dispatch.**
 `run_turn` appends `{"role": "tool", ...}` from ~9 different sites (validation rejects,
@@ -26,6 +26,17 @@ reasoning_content, tool_calls[], observation, metrics, model_name}`. Every model
 `extra: "forbid"`, and a validator requires each `observation.results[].source_call_id`
 to name a `tool_call_id` **in the same step** — hence one step carries both a turn's tool
 calls and their results.
+
+**What a step cost.** The schema's three token counts cannot tell a step that reasoned for
+twenty minutes from one that decoded a long file, so each agent step's `metrics.extra`
+carries the rest of what the engine measured (`StepStat`): the reasoning slice, prefill and
+decode seconds, speculative yield, and why the generation ended.
+
+**The step in flight.** A rebuild from `messages` only ever shows finished steps, and the
+step worth seeing is the one that never finishes — a runaway `<think>` a harness kills at
+its timeout leaves no message behind. So the agent hands over the partial text every
+`PENDING_EVERY` tokens and the document ends in one step marked `extra.in_flight`, replaced
+by the real step once its message lands.
 """
 
 import json
@@ -35,6 +46,8 @@ import re
 import tempfile
 import threading
 import uuid
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Callable, Optional
 
@@ -48,7 +61,7 @@ SCHEMA_VERSION = "ATIF-v1.7"
 _THINK_BLOCK = re.compile(r"<think>(.*?)</think>", re.S)
 
 
-def _now() -> str:
+def now() -> str:
     return datetime.now(timezone.utc).isoformat()
 
 
@@ -64,14 +77,66 @@ def split_think(text: str) -> tuple[str, str]:
     return reasoning, strip_think(text)
 
 
-def _metrics(stat: dict) -> dict:
+PENDING_EVERY = 256     # tokens between rewrites of the in-flight step (~10 s of decode)
+
+
+@dataclass(frozen=True)
+class StepStat:
+    """What one generation cost, as the engine measured it. `finish` names why it ended:
+    `eos`, `max_tokens`, `think_cap`, `repeat_stop` or `interrupted`."""
+    prompt_tokens: int = 0          # newly prefilled — excludes the cached prefix
+    cached_tokens: int = 0
+    generated_tokens: int = 0
+    think_tokens: int = 0
+    prefill_s: float = 0.0
+    gen_s: float = 0.0
+    forwards: int = 0
+    draft_proposed: int = 0
+    draft_accepted: int = 0
+    finish: str = "eos"
+    salvaged: bool = False
+    compacted: bool = False         # compaction shrank the render, so this step's prefill
+                                    # is a re-prefill of kept context, not new content
+    # Drafted rounds by proposed width k: entry i counts the rounds that accepted exactly
+    # i of the k. Split by phase, because reasoning and a tool call accept differently.
+    draft_hist_think: Mapping[int, Sequence[int]] = field(default_factory=dict)
+    draft_hist_act: Mapping[int, Sequence[int]] = field(default_factory=dict)
+
+
+def _draft_phase(hist: Mapping[int, Sequence[int]]) -> dict[str, JsonValue]:
+    """One phase's drafting: totals, the per-verify yield, and the histogram itself.
+    JSON keys are strings, so the width is spelled out."""
+    rounds = sum(sum(row) for row in hist.values())
+    proposed = sum(k * sum(row) for k, row in hist.items())
+    accepted = sum(i * n for row in hist.values() for i, n in enumerate(row))
+    return {"rounds": rounds, "proposed": proposed, "accepted": accepted,
+            "accepted_per_round": round(accepted / rounds, 2) if rounds else 0.0,
+            "first_token_miss": round(sum(row[0] for row in hist.values()) / rounds, 3)
+            if rounds else 0.0,
+            "by_width": {str(k): list(row) for k, row in sorted(hist.items())}}
+
+
+def _metrics(stat: StepStat) -> dict[str, JsonValue]:
     """chad's GenStats counts `prompt_tokens` as tokens *actually prefilled*, excluding the
     prefix served from cache. ATIF's `prompt_tokens` is documented as including cached
     tokens, so add them back — otherwise a warm KV cache reads as a shrinking prompt."""
-    prompt = stat.get("prompt_tokens", 0) + stat.get("cached_tokens", 0)
-    return {"prompt_tokens": prompt,
-            "completion_tokens": stat.get("generated_tokens", 0),
-            "cached_tokens": stat.get("cached_tokens", 0)}
+    extra: dict[str, JsonValue] = {
+        "think_tokens": stat.think_tokens, "prefill_s": round(stat.prefill_s, 2),
+        "gen_s": round(stat.gen_s, 2),
+        "tok_per_s": round(stat.generated_tokens / stat.gen_s, 1) if stat.gen_s > 0 else 0.0,
+        "forwards": stat.forwards,
+        "draft_proposed": stat.draft_proposed, "draft_accepted": stat.draft_accepted,
+        "finish": stat.finish}
+    if stat.salvaged:
+        extra["salvaged"] = True
+    if stat.compacted:
+        extra["compacted"] = True
+    if stat.draft_hist_think or stat.draft_hist_act:
+        extra["draft"] = {"think": _draft_phase(stat.draft_hist_think),
+                          "act": _draft_phase(stat.draft_hist_act)}
+    return {"prompt_tokens": stat.prompt_tokens + stat.cached_tokens,
+            "completion_tokens": stat.generated_tokens,
+            "cached_tokens": stat.cached_tokens, "extra": extra}
 
 
 # First-seen timestamps, keyed by the identity of the message each step describes.
@@ -90,7 +155,7 @@ def _metrics(stat: dict) -> dict:
 _STAMPS: dict[int, tuple[dict, str]] = {}
 
 
-def _stamp(m: dict, clock: Callable[[], str] = _now) -> str:
+def _stamp(m: dict, clock: Callable[[], str] = now) -> str:
     """The time `m` was first seen in a rebuild, minted on first sight."""
     hit = _STAMPS.get(id(m))
     if hit is not None and hit[0] is m:
@@ -100,8 +165,27 @@ def _stamp(m: dict, clock: Callable[[], str] = _now) -> str:
     return ts
 
 
+def pending_step(text: str, thinking: bool, model_name: Optional[str], generated: int,
+                 started: str) -> dict[str, JsonValue]:
+    """The step still being generated, from the text decoded so far.
+
+    On a thinking step the template opened `<think>`, so text with no close tag yet is all
+    reasoning — `split_think` alone would file it as the visible message."""
+    if thinking and "</think>" not in text:
+        reasoning, visible = text, ""
+    else:
+        reasoning, visible = split_think(text)
+    step: dict[str, JsonValue] = {"source": "agent", "message": visible, "timestamp": started,
+                                  "extra": {"in_flight": True, "generated_tokens": generated}}
+    if model_name:
+        step["model_name"] = model_name
+    if reasoning.strip():
+        step["reasoning_content"] = reasoning
+    return step
+
+
 def steps_from_messages(messages: list, model_name: Optional[str],
-                        stats: list, clock: Callable[[], str] = _now) -> list[dict]:
+                        stats: list[StepStat], clock: Callable[[], str] = now) -> list[dict]:
     """Convert one Agent's `messages` into ATIF steps (without global `step_id`s).
 
     A `role: "tool"` message is not a step — it is an *observation* attached to the
@@ -167,6 +251,33 @@ def steps_from_messages(messages: list, model_name: Optional[str],
     return steps
 
 
+def _totals(mets: list[dict]) -> dict[str, JsonValue]:
+    """The trial in one row: what a score table needs without re-reading every step."""
+    prompt = sum(m["prompt_tokens"] for m in mets)
+    gen_s = sum(m["extra"]["gen_s"] for m in mets)
+    out: dict[str, JsonValue] = {
+        "total_think_tokens": sum(m["extra"]["think_tokens"] for m in mets),
+        "total_gen_s": round(gen_s, 2),
+        "total_prefill_s": round(sum(m["extra"]["prefill_s"] for m in mets), 2),
+        "tok_per_s": round(sum(m["completion_tokens"] for m in mets) / gen_s, 1)
+        if gen_s > 0 else 0.0,
+        "cache_hit_rate": round(sum(m["cached_tokens"] for m in mets) / prompt, 3)
+        if prompt else 0.0,
+        "compactions": sum(1 for m in mets if m["extra"].get("compacted")),
+        "finishes": {f: sum(1 for m in mets if m["extra"]["finish"] == f)
+                     for f in sorted({m["extra"]["finish"] for m in mets})}}
+    for phase in ("think", "act"):
+        blocks = [m["extra"]["draft"][phase] for m in mets if "draft" in m["extra"]]
+        rounds = sum(b["rounds"] for b in blocks)
+        if rounds:
+            proposed = sum(b["proposed"] for b in blocks)
+            accepted = sum(b["accepted"] for b in blocks)
+            out[f"draft_{phase}"] = {
+                "rounds": rounds, "accept_rate": round(accepted / proposed, 3),
+                "accepted_per_round": round(accepted / rounds, 2)}
+    return out
+
+
 def _pkg_version() -> str:
     """The installed chad-code version, for the trajectory's agent.version field.
     Was a hardcoded literal, which silently rots on every release — a leaderboard
@@ -191,6 +302,7 @@ class TrajectoryRecorder:
         self.session_id = str(uuid.uuid4())
         self.model_name: Optional[str] = None
         self._segments: list[list[dict]] = []
+        self._pending: dict[int, dict[str, JsonValue]] = {}
         self._lock = threading.Lock()
 
     def new_segment(self) -> int:
@@ -208,9 +320,21 @@ class TrajectoryRecorder:
             if 0 <= idx < len(self._segments):
                 self._segments[idx] = steps
 
+    def set_pending(self, idx: int, step: Optional[dict[str, JsonValue]]) -> None:
+        """Set or clear (None) the in-flight step that trails segment `idx`."""
+        with self._lock:
+            if step is None:
+                self._pending.pop(idx, None)
+            else:
+                self._pending[idx] = step
+
     def to_dict(self) -> dict:
         with self._lock:
-            steps = [s for seg in self._segments for s in seg]
+            steps = []
+            for idx, seg in enumerate(self._segments):
+                steps.extend(seg)
+                if idx in self._pending:
+                    steps.append(dict(self._pending[idx]))
         for n, s in enumerate(steps, 1):     # ATIF: sequential from 1, document-wide
             s["step_id"] = n
         agent: dict[str, JsonValue] = {"name": self.agent_name, "version": self.agent_version}
@@ -227,7 +351,8 @@ class TrajectoryRecorder:
                 "total_prompt_tokens": sum(m["prompt_tokens"] for m in mets),
                 "total_completion_tokens": sum(m["completion_tokens"] for m in mets),
                 "total_cached_tokens": sum(m["cached_tokens"] for m in mets),
-                "total_steps": len(steps)}
+                "total_steps": len(steps),
+                "extra": _totals(mets)}
         return doc
 
     def dump(self) -> None:
@@ -264,6 +389,15 @@ def recorder() -> Optional[TrajectoryRecorder]:
     return _RECORDER
 
 
+def start(path: str) -> TrajectoryRecorder:
+    """Install a fresh process recorder writing to `path`, for a driver that runs many
+    trials in one process and wants a document per trial. Agents built afterwards record
+    into it; one built earlier keeps the recorder it was constructed with."""
+    global _RECORDER, _INIT
+    _RECORDER, _INIT = TrajectoryRecorder(path), True
+    return _RECORDER
+
+
 def _reset_for_tests() -> None:
     global _RECORDER, _INIT
     _RECORDER, _INIT = None, False