From 61863eb46d88a69e95c3f748a1e9df2d4b547f2a Mon Sep 17 00:00:00 2001
From: t <t@tjp.lol>
Date: Fri, 30 Oct 2026 01:58:33 -0600
Subject: Start warming turns with callback-form run_async

Drive the warm turn from the luv timer with callback run_async, caching
only its termination, and abandon with a nonjoining close. Removes native
job polling. Adds binding-check.lua, a real-binding check against local HTTP
fixtures, to mise run check.

Requires a Pantograph host with callback-form run_async.
---
 README.md | 26 +++++++++++++++++---------
 1 file changed, 17 insertions(+), 9 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 68876c4..d83def9 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,12 @@ For a local checkout, use `paths = ["/path/to/panto-warming"]` instead. A
 in panto's own rocks tree first (`mise run deps`, or the `luarocks` line it
 contains).
 
+## Host compatibility
+
+This source requires Pantograph's callback form
+`agent:run_async(request, callback)`; hosts exposing only the older no-callback
+job API are unsupported.
+
 ## Configuration
 
 Enable with defaults in any layered `config.toml` (the built-in base layer,
@@ -88,10 +94,10 @@ sequenceDiagram
     participant Provider
     Timer->>Store: replay transcript (same as /resume)
     Timer->>Warm: panto.agent { conversation, model, tools, null_store }
-    Timer->>Warm: run_async { transient prompt, dispatch_tools = false }
+    Timer->>Warm: run_async { transient prompt, dispatch_tools = false }, callback
     Warm->>Provider: [session prefix] + [transient user message]
     Provider-->>Warm: one response
-    Warm--)Timer: settled; response discarded
+    Warm--)Timer: callback caches termination; response discarded
 ```
 
 The warm request shares the session's prompt prefix and differs only by the
@@ -106,10 +112,11 @@ prefix again and keeps it hot. Then everything is dropped:
 - **Model** — `panto.ext.resolve_model` for the session's current
   model/reasoning label, inheriting the live credentialed transport.
 - **Tools** — the session agent's declarations, copied onto the warm agent.
-- **Turn** — one `run_async` on its own pump thread (the UI never blocks),
-  with `dispatch_tools = false`: a misbehaving model cannot run real tools
-  from a keep-alive prompt, and tool calls are handed back unresolved and
-  discarded with the rest.
+- **Turn** — one callback-form `run_async` on its own pump thread (the UI
+  never blocks), with `dispatch_tools = false`: a misbehaving model cannot run
+  real tools from a keep-alive prompt, and tool calls are handed back
+  unresolved and discarded with the rest. Progress deliveries are discarded;
+  only the terminal status/error is cached for the next timer tick.
 
 The warm turn's user message and response live only in the throwaway
 agent's conversation and a `null_store` — the live session, its transcript,
@@ -151,10 +158,11 @@ one uninterrupted 30-minute window sends at most seven warming requests.
 ```sh
 mise trust        # once
 mise run deps     # install toml2lua into panto's rocks tree (for `paths` use)
-mise run check    # panto lua _selfcheck.lua
+mise run check    # self-check plus real-binding HTTP integration
 ```
 
 `warming/policy.lua` and `warming/config.lua` are pure (durations, layer
 merging, the timing state machine) and fully covered by the self-check;
-`warming/warm.lua` is the binding glue. Release plumbing: `mise run version
-<x.y.z>`, commit, `mise run release`.
+`warming/warm.lua` is the binding glue. `mise run check` also runs
+`binding-check.lua` against the real callback binding and local HTTP fixtures.
+Release plumbing: `mise run version <x.y.z>`, commit, `mise run release`.
-- 
cgit v1.3