timefork 0.1.0__tar.gz → 0.2.0__tar.gz

{timefork-0.1.0 → timefork-0.2.0}/.gitignore

@@ -7,3 +7,5 @@ dist/
 build/
 .DS_Store
 .timefork/
+.env
+.env.*

{timefork-0.1.0 → timefork-0.2.0}/CHANGELOG.md

@@ -2,6 +2,74 @@
 
 Plain words about what changed and why. Newest first.
 
+## 0.2.0 - 2026-09-27
+
+- Twelve framework runs recorded and replayed on real providers with no code
+  that knows about the proxy: Strands, Pydantic AI, LangGraph, Google ADK,
+  CrewAI, AutoGen and the OpenAI Agents SDK on Claude; LangGraph, CrewAI,
+  AutoGen and the Agents SDK on OpenAI; Google ADK on Gemini through Vertex
+  AI, the Gemini adapter's first real traffic. `docs/real_frameworks.py`
+  writes `docs/FRAMEWORKS.md`; the README's table claims only what is in it.
+- The proxy environment points the google-genai client's Vertex base URL at
+  the proxy, so Vertex AI express mode records like the Gemini API.
+- `timefork replay --pace` hands a streamed reply back at the rhythm it was
+  recorded, chunk by chunk, so an agent's streaming code and timeouts are
+  tested too; the arrival time of every chunk is now kept on the step.
+- `timefork rehash` reports the actors it renamed.
+- A turn whose first message was re-sent as one string instead of a list
+  of text blocks, which the Claude Agent SDK does, is read as the same
+  conversation; the SDK's session-naming call is named `claude code title`.
+- The Claude Agent SDK, driving Claude Code with one subagent, recorded
+  through the proxy by `docs/subagents.py --sdk` and pictured.
+- `timefork suspects`: across many recordings of one workflow, the step
+  whose words predict failure, scored by how much more often the failed
+  runs said them than the passing ones.
+- OpenAI's `content_filter` finish and `refusal` field, and Gemini's safety
+  finish reasons and blocked prompts, read as refusals: on the reel line, on
+  the frame, and in the Answer pane.
+- `take.transport()` hands an async client's requests to the recorder
+  in-process, with no socket and no environment variable.
+- The Wiring view folds a parent's helpers into one lane once there are
+  more than twelve lanes, every wire still drawn; a click opens them. The
+  gallery's new `swarm` scenario is sixteen helpers under one supervisor.
+- `timefork bisect --ancestors` probes only the steps the graph says reached
+  the final one, plus one probe outside them that catches a graph that
+  missed an edge; the same through `Timefork.bisect(ancestors=True)`.
+- Streamed tool calls on the OpenAI shape have met traffic: a test streams a
+  call in fragments the way the wire does and checks the page's description,
+  the replay and an edited call in the same shape.
+- A conversation continued under another agent, which is how the OpenAI
+  Agents SDK hands off, is drawn as a handoff into a nested lane, named by
+  the transfer tool. The OpenAI shape's leading system message is read as
+  the prompt, not as part of the conversation.
+- Two gallery scenarios run real frameworks against the scripted model with
+  no key: a LangGraph of three ChatOpenAI nodes, and the OpenAI Agents SDK
+  with a handoff and a function tool. Both recorded through the proxy with
+  no code that knows about it, both replayed free, both in the Wiring view.
+- The scripted model speaks the OpenAI chat-completions shape, tool calls
+  and one-chunk streams included.
+- `timefork redact --hash` replaces a value with a stable token derived from
+  it, so two steps that carried one account still read as one account.
+- `timefork ci --judge "requirement"` scores each replayed run's final answer
+  with the same model judge `bisect` uses.
+- Claude Code's main, subagent and title calls are named `claude code`,
+  `claude code subagent` and `claude code title` from markers only they
+  carry; `rehash` gives old tapes the same names.
+- Commands started from the page run in their own process group, so
+  stopping one stops the agent it ran; no `pgrep`, so nothing Windows lacks.
+- `rehash` says what a missing request path costs on Google and Bedrock
+  tapes from before 2026-09-12.
+
+## 0.1.1 - 2026-09-26
+
+- The source distribution holds the package, the README, the licence, the
+  notice and this changelog, and nothing else. The 0.1.0 sdist carried the
+  whole repository.
+- The README opens with one line, git bisect for agent runs, and the install
+  section leads with the `uvx` path and the times it measured.
+- Pictures are plain markdown images and the architecture diagrams are
+  rendered to PNG, so the GitHub mobile app and PyPI show them.
+
 ## 0.1.0 - 2026-09-26
 
 The first version. Everything below was built and measured between the 7th and
@@ -69,9 +137,9 @@ pipeline, and real Claude Code sessions.
   Claude Code. `python docs/real.py` runs every scenario and writes
   `docs/REAL.md` with the numbers read back off the tape. A refusal, a
   thinking-only reply, a parallel delegation and a wrapped error status
-  were all found this way and are written up in the paper.
-- `bench/report.py` renders the paper's tables from the benches' own output
-  and writes them into the paper between markers, so a number there is
+  were all found this way.
+- `bench/report.py` renders the benches' tables from their own output and
+  writes them into any document between markers, so a number there is
   something a script wrote.
 - Python 3.11 is supported; the whole suite passes on it.
 
@@ -99,4 +167,4 @@ pipeline, and real Claude Code sessions.
 - `timefork grep` searches every recording's text.
 - A scenario gallery, `docs/SCENARIOS.md`, rebuilt by `docs/scenarios.py`, from
   which the README's pictures come.
-- A paper, `PAPER.md`, with every number reproducible from `bench/`.
+- Benchmarks under `bench/`, every number reproducible by a script.

timefork-0.1.0/README.md → timefork-0.2.0/PKG-INFO

@@ -1,30 +1,67 @@
+Metadata-Version: 2.5
+Name: timefork
+Version: 0.2.0
+Summary: git bisect for agent runs. Record once through a proxy, replay for free, change one thing, find the step that broke it.
+Author: Arun Shankar
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agents,debugging,llm,mcp,observability,replay
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.9
+Requires-Dist: starlette>=0.41
+Requires-Dist: uvicorn>=0.32
+Provides-Extra: aws
+Requires-Dist: botocore>=1.34; extra == 'aws'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Provides-Extra: frameworks
+Requires-Dist: google-adk>=1.0; extra == 'frameworks'
+Requires-Dist: langchain-anthropic>=0.3; extra == 'frameworks'
+Requires-Dist: langchain-openai>=0.2; extra == 'frameworks'
+Requires-Dist: langgraph>=0.2; extra == 'frameworks'
+Requires-Dist: litellm>=1.40; extra == 'frameworks'
+Requires-Dist: openai-agents>=0.1; extra == 'frameworks'
+Requires-Dist: openai>=1.40; extra == 'frameworks'
+Requires-Dist: pydantic-ai>=1.0; extra == 'frameworks'
+Requires-Dist: strands-agents>=1.0; extra == 'frameworks'
+Description-Content-Type: text/markdown
+
 <h1 align="center">Timefork</h1>
 
 <p align="center">
-  <b>Time-travel debugging for LLM agents.</b><br>
-  Record a run. Change one thing. Replay it without paying for the steps that did not change.
+  <b>git bisect for agent runs.</b><br>
+  Record a run once, through a proxy. Replay it for free. Change one thing. Find the step that broke it.
 </p>
 
 <p align="center">
   <a href="#install"><img alt="python" src="https://img.shields.io/badge/python-3.11%2B-1E2838?style=flat-square&labelColor=0F1520"></a>
   <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-Apache--2.0-2DD4A7?style=flat-square&labelColor=0F1520"></a>
   <a href="#it-works-with-your-framework-because-it-has-never-heard-of-it"><img alt="frameworks" src="https://img.shields.io/badge/frameworks-all%20of%20them-8AB4FF?style=flat-square&labelColor=0F1520"></a>
-  <a href="#status"><img alt="tests" src="https://img.shields.io/badge/tests-199%20over%20real%20HTTP-2DD4A7?style=flat-square&labelColor=0F1520"></a>
+  <a href="#status"><img alt="tests" src="https://img.shields.io/badge/tests-real%20HTTP%20over%20TCP-2DD4A7?style=flat-square&labelColor=0F1520"></a>
   <a href="docs/REAL.md"><img alt="real api" src="https://img.shields.io/badge/proven%20on-the%20real%20API-FFA94D?style=flat-square&labelColor=0F1520"></a>
 </p>
 
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/images/investigation-dark.png">
-    <img alt="A bisected agent run: the step that broke it, the probes that found it, and the answer that would have worked" src="docs/images/investigation-light.png" width="100%">
-  </picture>
-</p>
+![A bisected agent run: the step that broke it, the probes that found it, and the answer that would have worked](docs/images/investigation-light.png)
 
 <p align="center"><sub>A finished investigation. Five steps, three agents, one worker answered badly once. The search was told nothing and named the step in four probes.</sub></p>
 
 <details>
 <summary><b>Ten seconds of the timeline</b> - the investigation, the wiring, a what-if, and a real Claude Code session with a subagent</summary>
-<p align="center"><img alt="Four frames: a bisected run, the wiring of a fan-out, a what-if edit forking at the critic, and a real Claude Code subagent session" src="docs/images/tour.gif" width="100%"></p>
+
+![Four frames: a bisected run, the wiring of a fan-out, a what-if edit forking at the critic, and a real Claude Code subagent session](docs/images/tour.gif)
+
 </details>
 
 ---
@@ -62,6 +99,19 @@ Every observability tool on the market will show you the trace.
 
 ## Install
 
+Nothing to install first if you have [uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx timefork record -- claude -p "what does this repo do"
+uvx timefork serve
+uvx timefork replay last -- claude -p "what does this repo do"    # free
+```
+
+Measured cold on a laptop with a one-line prompt: the first command was
+running 1.2 s after being typed, the Claude Code run recorded in 9 s, the
+page was up 1.5 s later, and the replay finished in 2.5 s without touching
+the provider. For keeps:
+
 ```bash
 pip install timefork        # or: uv tool install timefork
 cd your-project && timefork init
@@ -135,17 +185,12 @@ intermittent failures, `-r 4` combines draws by disjunction rather than
 majority, which takes exact localisation from 0.12 to 0.84 where resampling
 rescues the run half the time. All three verdicts have been confirmed on real
 Claude Code sessions, and a real refusal on the real API was called
-*deterministic* correctly. [PAPER.md](PAPER.md) has the numbers and the false
-starts.
+*deterministic* correctly. `bench/faults.py` measures it against ground
+truth.
 
 ### 3. Change what the model said, and replay from there
 
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/images/scenario-what-if-dark.jpg">
-    <img alt="A worker's answer changed from 66 to 999 on the timeline; three steps replayed free, the critic re-ran live" src="docs/images/scenario-what-if-light.jpg" width="100%">
-  </picture>
-</p>
+![A worker's answer changed from 66 to 999 on the timeline; three steps replayed free, the critic re-ran live](docs/images/scenario-what-if-light.jpg)
 
 Pick a step, edit its answer - or the tool it called - and replay. The edit is
 served to the agent in the vendor's own wire shape; every step that did not
@@ -166,21 +211,35 @@ its model provider. There is nothing to import, subclass, wrap or configure.
 
 | | |
 |:--|:--|
-| Google ADK | ✓ |
-| LangChain · LangGraph | ✓ |
-| CrewAI · AutoGen · Pydantic AI · Strands | ✓ |
-| Claude Code · Cursor · Cline | ✓ |
-| forty lines of `httpx` | ✓ |
-| the thing you wrote this morning | ✓ |
+| Google ADK | ✓ [on Claude and on Gemini](docs/FRAMEWORKS.md) |
+| LangChain · LangGraph | ✓ [on Claude and on OpenAI](docs/FRAMEWORKS.md) · [pictured](docs/SCENARIOS.md) |
+| OpenAI Agents SDK, handoffs and tools | ✓ [on OpenAI and on Claude](docs/FRAMEWORKS.md) · [pictured](docs/SCENARIOS.md) |
+| CrewAI | ✓ [on Claude and on OpenAI](docs/FRAMEWORKS.md) |
+| AutoGen | ✓ [on Claude and on OpenAI](docs/FRAMEWORKS.md) |
+| Pydantic AI | ✓ [on Claude](docs/FRAMEWORKS.md) |
+| Strands Agents (AWS) | ✓ [on Claude](docs/FRAMEWORKS.md) |
+| Claude Code | ✓ real sessions, [pictured](docs/images/subagents-light.jpg) |
+| Claude Agent SDK, subagent and all | ✓ real session, [pictured](docs/images/agent-sdk-light.jpg) |
+| forty lines of `httpx` | ✓ most of the test suite |
+| Cursor · Cline | the same wire shape, not run here: they are desktop programs |
+| the thing you wrote this morning | ✓ if it speaks HTTP to a provider |
+
+Every mark above is a program in this repository that was run through the
+proxy against a real model, recorded, and then replayed with every step from
+the tape and the provider never contacted. The numbers are in
+[docs/FRAMEWORKS.md](docs/FRAMEWORKS.md), rebuilt by `python docs/real_frameworks.py`.
 
 If it speaks HTTP to Anthropic, OpenAI, Gemini, Vertex or Bedrock - or to any of
 the many APIs that copied the OpenAI shape, including Azure, Groq, Together,
-vLLM and Ollama - it is recorded.
+vLLM and Ollama - it is recorded the same way. Anthropic, OpenAI and Gemini on
+Vertex AI have each met real traffic here; Bedrock and the OpenAI-shaped clones
+are handled by the same adapters and have been run only against fakes.
 
 Bedrock is the one that needs something extra. SigV4 covers the host header, so
 the signature your agent produced is for the proxy and AWS rejects it; the proxy
 strips it and signs again, which means **the proxy needs its own AWS
-credentials**. Install with `pip install 'timefork[aws]'`.
+credentials**. Install with `pip install 'timefork[aws]'`. The re-signing is
+tested against a fake; a real Bedrock run has not been made here.
 
 **Wrap a command:**
 
@@ -212,7 +271,7 @@ have produced: a mid-stream safety refusal on a ledger-adding tool call, which
 `bisect` correctly called deterministic; a worker that thought for sixteen
 tokens and said nothing; a model delegating to two helpers in one turn; and a
 proxy that wrapped an upstream 400 in a 200 event stream. All four are handled
-and written up in [PAPER.md](PAPER.md), section 6.7.
+and written up in [docs/REAL.md](docs/REAL.md).
 
 <br>
 
@@ -248,12 +307,7 @@ indented under the one that started it, a curve for every handoff, and after a
 bisect, the path the blamed answer took in rose. This is a real Claude Code
 session that was asked to spawn a subagent; nothing was declared:
 
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/images/subagents-dark.jpg">
-    <img alt="A real Claude Code session with a subagent, drawn as lanes: the main agent, the subagent nested under it, the brief going down and the report coming back" src="docs/images/subagents-light.jpg" width="100%">
-  </picture>
-</p>
+![A real Claude Code session with a subagent, drawn as lanes: the main agent, the subagent nested under it, the brief going down and the report coming back](docs/images/subagents-light.jpg)
 
 Measured against runs with a known graph (`bench/lineage.py`): no errors on
 verbatim or paraphrased quotes, 0.99 precision on one-word answers, and an
@@ -304,7 +358,9 @@ A recording becomes a test with one line: `timefork expect checkout-flow
 "order 4471 confirmed"`. Then a drift whose final answer still says that is a
 *drift* - the prompts moved, the outcome did not - and one whose answer no
 longer says it is a *fail*, which is the thing a regression suite is for. Run
-`ci --on-diverge live` to let a drifted run reach its answer and be scored.
+`ci --on-diverge live` to let a drifted run reach its answer and be scored, and
+`ci --judge "the order was confirmed"` to have a model score it instead of a
+substring.
 
 <br>
 
@@ -336,6 +392,11 @@ result = deck.bisect("nightly", play=lambda env: my_agent(env=env) == 0)
 Every take is a run on the tape, exactly as the command line would have made
 it: the timeline shows it, `share` exports it, `bisect` can search it.
 
+
+An async client that cannot be pointed at a base URL by its environment can
+be handed the recorder directly: `httpx.AsyncClient(transport=take.transport())`
+reaches it in-process, with no socket. Sync clients take `base_url=take.base_url`.
+
 <br>
 
 ## Send someone the recording
@@ -436,19 +497,20 @@ which is the right default in CI.
 | `timefork init` | create a tape here |
 | `timefork doctor` | check this machine before the first recording |
 | `timefork record -- CMD` | run CMD with recording on |
-| `timefork replay REF -- CMD` | replay a run as a new branch; `--edit`, `--call`, `--from`, `--on-diverge block` |
-| `timefork bisect REF --check CMD` | find the step that caused a failure; `--judge "…"` lets a model decide |
+| `timefork replay REF -- CMD` | replay a run as a new branch; `--edit`, `--call`, `--from`, `--on-diverge block`, `--pace` |
+| `timefork bisect REF --check CMD` | find the step that caused a failure; `--judge "…"` lets a model decide; `--ancestors` probes only the steps that reached the last one |
 | `timefork serve` | open the timeline |
 | `timefork graph REF` | draw who handed what to whom |
 | `timefork mcp -- SERVER` | record an MCP server's tool calls |
 | `timefork share REF` | export a run as one shareable file |
-| `timefork ci` | replay every recording and report what changed |
+| `timefork ci` | replay every recording and report what changed; `--judge "…"` lets a model score the answers |
 | `timefork expect REF TEXT` | what a recording's final answer must say, for `ci` to score |
+| `timefork suspects` | across many recordings, the step whose words predict failure |
 | `timefork sweep REF --vary F --variants D` | try many versions of a prompt |
 | `timefork calibrate -- CMD` | run twice, find what varies on its own |
 | `timefork ignore PATH` | stop a varying field counting as a change |
 | `timefork rehash` | re-file the tape after editing its ignore list by hand |
-| `timefork redact -p REGEX --path PATH` | never store these values; scrubbed before hashing, so replay still matches |
+| `timefork redact -p REGEX --path PATH` | never store these values; scrubbed before hashing, so replay still matches; `--hash` keeps a stable token per value |
 | `timefork log` · `show REF` · `grep TEXT` · `stat` | list runs, list steps, search, size |
 | `timefork up` · `timefork env` | standalone proxy |
 
@@ -477,7 +539,7 @@ diagrams.
 
 ## Status
 
-`v0.1` - alpha, and honest about it. What is in it: [CHANGELOG.md](CHANGELOG.md).
+`v0.2` - alpha, and honest about it. What is in it: [CHANGELOG.md](CHANGELOG.md).
 What is left, and where it is going: [TODO.md](TODO.md).
 
 | | |
@@ -494,9 +556,10 @@ What is left, and where it is going: [TODO.md](TODO.md).
 | shareable single-file export, redacted | ✓ |
 | `ci` regression replay over a whole corpus | ✓ |
 | Python API, sync and async, with callbacks | ✓ |
+| twelve framework runs on Claude, OpenAI and Gemini, none of them knowing | ✓ [docs/FRAMEWORKS.md](docs/FRAMEWORKS.md) |
 | cost in dollars rather than tokens | ✗ |
 
-199 tests run a real upstream, a real proxy and real HTTP over TCP. The
+Every test runs a real upstream, a real proxy and real HTTP over TCP. The
 assertion that matters most is that a replay leaves the provider's call count
 untouched.
 
@@ -506,10 +569,9 @@ untouched.
 
 - [docs/SCENARIOS.md](docs/SCENARIOS.md) - every scenario the tool is built for, as a real tape with a picture, in both themes, rebuilt by a script.
 - [docs/REAL.md](docs/REAL.md) - the same scenarios on the real API, with numbers.
+- [docs/FRAMEWORKS.md](docs/FRAMEWORKS.md) - seven agent frameworks recorded and replayed on the real API, none of them knowing.
+- [docs/LAUNCH.md](docs/LAUNCH.md) and [docs/VIDEO.md](docs/VIDEO.md) - the launch post and the sixty-second video's script, both built from the numbers above.
 - [ARCHITECTURE.md](ARCHITECTURE.md) - how it works, in plain English and diagrams.
-- [PAPER.md](PAPER.md) - the technical write-up: design, the intervention search, measured numbers, and what has not been evaluated.
-- [LAYMAN.md](LAYMAN.md) - the idea without jargon, and why anyone would pay for it.
-- [PATENT.md](PATENT.md) - the invention disclosure, with the weak points named.
 - [SECURITY.md](SECURITY.md) - what the tape holds, what `share` scrubs, what the page can run, and `timefork redact` for values a tape must never hold.
 
 ## License

timefork-0.1.0/PKG-INFO → timefork-0.2.0/README.md

@@ -1,64 +1,27 @@
-Metadata-Version: 2.5
-Name: timefork
-Version: 0.1.0
-Summary: Time-travel debugging for LLM agents. Record a run, rewind to any step, change one thing, replay.
-Author: Arun Shankar
-License: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Keywords: agents,debugging,llm,mcp,observability,replay
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development :: Debuggers
-Requires-Python: >=3.11
-Requires-Dist: click>=8.1
-Requires-Dist: httpx>=0.27
-Requires-Dist: rich>=13.9
-Requires-Dist: starlette>=0.41
-Requires-Dist: uvicorn>=0.32
-Provides-Extra: aws
-Requires-Dist: botocore>=1.34; extra == 'aws'
-Provides-Extra: dev
-Requires-Dist: mypy>=1.13; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
-Requires-Dist: pytest>=8.3; extra == 'dev'
-Requires-Dist: ruff>=0.7; extra == 'dev'
-Provides-Extra: frameworks
-Requires-Dist: langchain-openai>=0.2; extra == 'frameworks'
-Requires-Dist: litellm>=1.40; extra == 'frameworks'
-Requires-Dist: openai>=1.40; extra == 'frameworks'
-Description-Content-Type: text/markdown
-
 <h1 align="center">Timefork</h1>
 
 <p align="center">
-  <b>Time-travel debugging for LLM agents.</b><br>
-  Record a run. Change one thing. Replay it without paying for the steps that did not change.
+  <b>git bisect for agent runs.</b><br>
+  Record a run once, through a proxy. Replay it for free. Change one thing. Find the step that broke it.
 </p>
 
 <p align="center">
   <a href="#install"><img alt="python" src="https://img.shields.io/badge/python-3.11%2B-1E2838?style=flat-square&labelColor=0F1520"></a>
   <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-Apache--2.0-2DD4A7?style=flat-square&labelColor=0F1520"></a>
   <a href="#it-works-with-your-framework-because-it-has-never-heard-of-it"><img alt="frameworks" src="https://img.shields.io/badge/frameworks-all%20of%20them-8AB4FF?style=flat-square&labelColor=0F1520"></a>
-  <a href="#status"><img alt="tests" src="https://img.shields.io/badge/tests-199%20over%20real%20HTTP-2DD4A7?style=flat-square&labelColor=0F1520"></a>
+  <a href="#status"><img alt="tests" src="https://img.shields.io/badge/tests-real%20HTTP%20over%20TCP-2DD4A7?style=flat-square&labelColor=0F1520"></a>
   <a href="docs/REAL.md"><img alt="real api" src="https://img.shields.io/badge/proven%20on-the%20real%20API-FFA94D?style=flat-square&labelColor=0F1520"></a>
 </p>
 
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/images/investigation-dark.png">
-    <img alt="A bisected agent run: the step that broke it, the probes that found it, and the answer that would have worked" src="docs/images/investigation-light.png" width="100%">
-  </picture>
-</p>
+![A bisected agent run: the step that broke it, the probes that found it, and the answer that would have worked](docs/images/investigation-light.png)
 
 <p align="center"><sub>A finished investigation. Five steps, three agents, one worker answered badly once. The search was told nothing and named the step in four probes.</sub></p>
 
 <details>
 <summary><b>Ten seconds of the timeline</b> - the investigation, the wiring, a what-if, and a real Claude Code session with a subagent</summary>
-<p align="center"><img alt="Four frames: a bisected run, the wiring of a fan-out, a what-if edit forking at the critic, and a real Claude Code subagent session" src="docs/images/tour.gif" width="100%"></p>
+
+![Four frames: a bisected run, the wiring of a fan-out, a what-if edit forking at the critic, and a real Claude Code subagent session](docs/images/tour.gif)
+
 </details>
 
 ---
@@ -96,6 +59,19 @@ Every observability tool on the market will show you the trace.
 
 ## Install
 
+Nothing to install first if you have [uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx timefork record -- claude -p "what does this repo do"
+uvx timefork serve
+uvx timefork replay last -- claude -p "what does this repo do"    # free
+```
+
+Measured cold on a laptop with a one-line prompt: the first command was
+running 1.2 s after being typed, the Claude Code run recorded in 9 s, the
+page was up 1.5 s later, and the replay finished in 2.5 s without touching
+the provider. For keeps:
+
 ```bash
 pip install timefork        # or: uv tool install timefork
 cd your-project && timefork init
@@ -169,17 +145,12 @@ intermittent failures, `-r 4` combines draws by disjunction rather than
 majority, which takes exact localisation from 0.12 to 0.84 where resampling
 rescues the run half the time. All three verdicts have been confirmed on real
 Claude Code sessions, and a real refusal on the real API was called
-*deterministic* correctly. [PAPER.md](PAPER.md) has the numbers and the false
-starts.
+*deterministic* correctly. `bench/faults.py` measures it against ground
+truth.
 
 ### 3. Change what the model said, and replay from there
 
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/images/scenario-what-if-dark.jpg">
-    <img alt="A worker's answer changed from 66 to 999 on the timeline; three steps replayed free, the critic re-ran live" src="docs/images/scenario-what-if-light.jpg" width="100%">
-  </picture>
-</p>
+![A worker's answer changed from 66 to 999 on the timeline; three steps replayed free, the critic re-ran live](docs/images/scenario-what-if-light.jpg)
 
 Pick a step, edit its answer - or the tool it called - and replay. The edit is
 served to the agent in the vendor's own wire shape; every step that did not
@@ -200,21 +171,35 @@ its model provider. There is nothing to import, subclass, wrap or configure.
 
 | | |
 |:--|:--|
-| Google ADK | ✓ |
-| LangChain · LangGraph | ✓ |
-| CrewAI · AutoGen · Pydantic AI · Strands | ✓ |
-| Claude Code · Cursor · Cline | ✓ |
-| forty lines of `httpx` | ✓ |
-| the thing you wrote this morning | ✓ |
+| Google ADK | ✓ [on Claude and on Gemini](docs/FRAMEWORKS.md) |
+| LangChain · LangGraph | ✓ [on Claude and on OpenAI](docs/FRAMEWORKS.md) · [pictured](docs/SCENARIOS.md) |
+| OpenAI Agents SDK, handoffs and tools | ✓ [on OpenAI and on Claude](docs/FRAMEWORKS.md) · [pictured](docs/SCENARIOS.md) |
+| CrewAI | ✓ [on Claude and on OpenAI](docs/FRAMEWORKS.md) |
+| AutoGen | ✓ [on Claude and on OpenAI](docs/FRAMEWORKS.md) |
+| Pydantic AI | ✓ [on Claude](docs/FRAMEWORKS.md) |
+| Strands Agents (AWS) | ✓ [on Claude](docs/FRAMEWORKS.md) |
+| Claude Code | ✓ real sessions, [pictured](docs/images/subagents-light.jpg) |
+| Claude Agent SDK, subagent and all | ✓ real session, [pictured](docs/images/agent-sdk-light.jpg) |
+| forty lines of `httpx` | ✓ most of the test suite |
+| Cursor · Cline | the same wire shape, not run here: they are desktop programs |
+| the thing you wrote this morning | ✓ if it speaks HTTP to a provider |
+
+Every mark above is a program in this repository that was run through the
+proxy against a real model, recorded, and then replayed with every step from
+the tape and the provider never contacted. The numbers are in
+[docs/FRAMEWORKS.md](docs/FRAMEWORKS.md), rebuilt by `python docs/real_frameworks.py`.
 
 If it speaks HTTP to Anthropic, OpenAI, Gemini, Vertex or Bedrock - or to any of
 the many APIs that copied the OpenAI shape, including Azure, Groq, Together,
-vLLM and Ollama - it is recorded.
+vLLM and Ollama - it is recorded the same way. Anthropic, OpenAI and Gemini on
+Vertex AI have each met real traffic here; Bedrock and the OpenAI-shaped clones
+are handled by the same adapters and have been run only against fakes.
 
 Bedrock is the one that needs something extra. SigV4 covers the host header, so
 the signature your agent produced is for the proxy and AWS rejects it; the proxy
 strips it and signs again, which means **the proxy needs its own AWS
-credentials**. Install with `pip install 'timefork[aws]'`.
+credentials**. Install with `pip install 'timefork[aws]'`. The re-signing is
+tested against a fake; a real Bedrock run has not been made here.
 
 **Wrap a command:**
 
@@ -246,7 +231,7 @@ have produced: a mid-stream safety refusal on a ledger-adding tool call, which
 `bisect` correctly called deterministic; a worker that thought for sixteen
 tokens and said nothing; a model delegating to two helpers in one turn; and a
 proxy that wrapped an upstream 400 in a 200 event stream. All four are handled
-and written up in [PAPER.md](PAPER.md), section 6.7.
+and written up in [docs/REAL.md](docs/REAL.md).
 
 <br>
 
@@ -282,12 +267,7 @@ indented under the one that started it, a curve for every handoff, and after a
 bisect, the path the blamed answer took in rose. This is a real Claude Code
 session that was asked to spawn a subagent; nothing was declared:
 
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/images/subagents-dark.jpg">
-    <img alt="A real Claude Code session with a subagent, drawn as lanes: the main agent, the subagent nested under it, the brief going down and the report coming back" src="docs/images/subagents-light.jpg" width="100%">
-  </picture>
-</p>
+![A real Claude Code session with a subagent, drawn as lanes: the main agent, the subagent nested under it, the brief going down and the report coming back](docs/images/subagents-light.jpg)
 
 Measured against runs with a known graph (`bench/lineage.py`): no errors on
 verbatim or paraphrased quotes, 0.99 precision on one-word answers, and an
@@ -338,7 +318,9 @@ A recording becomes a test with one line: `timefork expect checkout-flow
 "order 4471 confirmed"`. Then a drift whose final answer still says that is a
 *drift* - the prompts moved, the outcome did not - and one whose answer no
 longer says it is a *fail*, which is the thing a regression suite is for. Run
-`ci --on-diverge live` to let a drifted run reach its answer and be scored.
+`ci --on-diverge live` to let a drifted run reach its answer and be scored, and
+`ci --judge "the order was confirmed"` to have a model score it instead of a
+substring.
 
 <br>
 
@@ -370,6 +352,11 @@ result = deck.bisect("nightly", play=lambda env: my_agent(env=env) == 0)
 Every take is a run on the tape, exactly as the command line would have made
 it: the timeline shows it, `share` exports it, `bisect` can search it.
 
+
+An async client that cannot be pointed at a base URL by its environment can
+be handed the recorder directly: `httpx.AsyncClient(transport=take.transport())`
+reaches it in-process, with no socket. Sync clients take `base_url=take.base_url`.
+
 <br>
 
 ## Send someone the recording
@@ -470,19 +457,20 @@ which is the right default in CI.
 | `timefork init` | create a tape here |
 | `timefork doctor` | check this machine before the first recording |
 | `timefork record -- CMD` | run CMD with recording on |
-| `timefork replay REF -- CMD` | replay a run as a new branch; `--edit`, `--call`, `--from`, `--on-diverge block` |
-| `timefork bisect REF --check CMD` | find the step that caused a failure; `--judge "…"` lets a model decide |
+| `timefork replay REF -- CMD` | replay a run as a new branch; `--edit`, `--call`, `--from`, `--on-diverge block`, `--pace` |
+| `timefork bisect REF --check CMD` | find the step that caused a failure; `--judge "…"` lets a model decide; `--ancestors` probes only the steps that reached the last one |
 | `timefork serve` | open the timeline |
 | `timefork graph REF` | draw who handed what to whom |
 | `timefork mcp -- SERVER` | record an MCP server's tool calls |
 | `timefork share REF` | export a run as one shareable file |
-| `timefork ci` | replay every recording and report what changed |
+| `timefork ci` | replay every recording and report what changed; `--judge "…"` lets a model score the answers |
 | `timefork expect REF TEXT` | what a recording's final answer must say, for `ci` to score |
+| `timefork suspects` | across many recordings, the step whose words predict failure |
 | `timefork sweep REF --vary F --variants D` | try many versions of a prompt |
 | `timefork calibrate -- CMD` | run twice, find what varies on its own |
 | `timefork ignore PATH` | stop a varying field counting as a change |
 | `timefork rehash` | re-file the tape after editing its ignore list by hand |
-| `timefork redact -p REGEX --path PATH` | never store these values; scrubbed before hashing, so replay still matches |
+| `timefork redact -p REGEX --path PATH` | never store these values; scrubbed before hashing, so replay still matches; `--hash` keeps a stable token per value |
 | `timefork log` · `show REF` · `grep TEXT` · `stat` | list runs, list steps, search, size |
 | `timefork up` · `timefork env` | standalone proxy |
 
@@ -511,7 +499,7 @@ diagrams.
 
 ## Status
 
-`v0.1` - alpha, and honest about it. What is in it: [CHANGELOG.md](CHANGELOG.md).
+`v0.2` - alpha, and honest about it. What is in it: [CHANGELOG.md](CHANGELOG.md).
 What is left, and where it is going: [TODO.md](TODO.md).
 
 | | |
@@ -528,9 +516,10 @@ What is left, and where it is going: [TODO.md](TODO.md).
 | shareable single-file export, redacted | ✓ |
 | `ci` regression replay over a whole corpus | ✓ |
 | Python API, sync and async, with callbacks | ✓ |
+| twelve framework runs on Claude, OpenAI and Gemini, none of them knowing | ✓ [docs/FRAMEWORKS.md](docs/FRAMEWORKS.md) |
 | cost in dollars rather than tokens | ✗ |
 
-199 tests run a real upstream, a real proxy and real HTTP over TCP. The
+Every test runs a real upstream, a real proxy and real HTTP over TCP. The
 assertion that matters most is that a replay leaves the provider's call count
 untouched.
 
@@ -540,10 +529,9 @@ untouched.
 
 - [docs/SCENARIOS.md](docs/SCENARIOS.md) - every scenario the tool is built for, as a real tape with a picture, in both themes, rebuilt by a script.
 - [docs/REAL.md](docs/REAL.md) - the same scenarios on the real API, with numbers.
+- [docs/FRAMEWORKS.md](docs/FRAMEWORKS.md) - seven agent frameworks recorded and replayed on the real API, none of them knowing.
+- [docs/LAUNCH.md](docs/LAUNCH.md) and [docs/VIDEO.md](docs/VIDEO.md) - the launch post and the sixty-second video's script, both built from the numbers above.
 - [ARCHITECTURE.md](ARCHITECTURE.md) - how it works, in plain English and diagrams.
-- [PAPER.md](PAPER.md) - the technical write-up: design, the intervention search, measured numbers, and what has not been evaluated.
-- [LAYMAN.md](LAYMAN.md) - the idea without jargon, and why anyone would pay for it.
-- [PATENT.md](PATENT.md) - the invention disclosure, with the weak points named.
 - [SECURITY.md](SECURITY.md) - what the tape holds, what `share` scrubs, what the page can run, and `timefork redact` for values a tape must never hold.
 
 ## License