tmustier · tmustier · Aug 9, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Changed
+
+- Simplify dispatch around Pi's fire-and-forget message handoff and callback-based compaction APIs, while preserving restoration for prompt and Skill expansion failures.
+- Keep validation documentation focused on reproducible commands and generated evidence rather than stale run output.
+
 ## 0.2.0 - 2026-08-09
 
 ### Added

diff --git a/README.md b/README.md
@@ -82,7 +82,7 @@ Text-only rows whose text is exactly `/compact`, `/compact <instructions>` or `/
 - `Option+Enter` while the agent works queues the command in follow-up order
 - a command row executes only once the agent is idle; rows behind it wait — so `/compact` followed by `continue` compacts first and delivers `continue` after compaction completes
 - `/reload` runs Pi’s built-in reload; committed rows queued behind it retain their IDs, lanes, attachments and pause state across the runtime swap
-- idle `/compact` uses Pi’s public compaction API so queued rows resume when compaction finishes; a start failure restores and pauses the command row
+- idle `/compact` uses Pi’s public compaction API so queued rows resume when compaction completes or reports an error
 - `/reload` submitted while the agent works or tracked compaction runs stays queued instead of showing Pi’s built-in wait warning
 - `Enter` on `/compact` while the agent works uses Pi’s public compaction API and holds visible rows until compaction settles
 - ordinary messages submitted during compaction remain in Pi’s native queue and can run before extension-owned command rows after compaction finishes
@@ -109,13 +109,13 @@ A touched head row is pinned until you save or cancel. In `one-at-a-time` mode,
 
 Aborting a run pauses both visible lanes. This prevents a follow-up from starting immediately after the abort.
 
-Press `Enter` on the empty composer to resume. A synchronous handoff or preflight failure returns the affected batch to the front of its lane.
+Press `Enter` on the empty composer to resume. A prompt or Skill expansion failure returns the affected batch to the front of its lane.
 
 Queue state, pause state and edit drafts are session-local. They never enter the Pi transcript or persistent session data. A `/reload` runtime swap carries committed rows and pause state through a short in-process handoff; unsaved edit drafts do not cross the swap.
 
 ## Public API limits
 
-Pi’s public `sendUserMessage` API is fire-and-forget. The extension restores synchronous dispatch failures and preflight/expansion failures without reordering, but Pi does not expose later asynchronous input rejection to extensions. Inferring rejection from queue timing could duplicate a delayed successful handoff, so the extension does not do that.
+Pi’s public `sendUserMessage` API is fire-and-forget. The extension restores prompt and Skill expansion failures before handoff, but Pi does not expose asynchronous input rejection to extensions. Inferring rejection from queue timing could duplicate a delayed successful handoff, so the extension does not do that.
 
 Pi also exposes queued `/reload` only through the TUI editor’s `void` submit callback. The extension prevents known busy and compaction conflicts and restores trailing rows on a successful runtime swap, but Pi cannot acknowledge or reject that submit back to the extension.
 
@@ -140,7 +140,7 @@ pi -e ./index.ts
 
 The automated suite covers delivery, editing, command rows, resource expansion, recovery, images, editor composition, repeated reloads, real retry ordering, real manual compaction success/failure and real automatic overflow compaction. The tmux harness exercises the same paths through Pi's real TUI, including actual runtime reloads and native post-compaction input.
 
-The Pi package ranges are intentionally unpinned. The full suite and real-TUI harness are verified against the current resolved Pi release; see [the validation record](docs/validation.md) for exact commands and evidence.
+The Pi package ranges are intentionally unpinned. The full suite and real-TUI harness are verified against the current resolved Pi release; see [the validation guide](docs/validation.md) for the commands and generated evidence.
 
 ## Security
 

diff --git a/docs/validation.md b/docs/validation.md
@@ -1,6 +1,6 @@
 # Compaction and reload validation
 
-This document records the deterministic validation matrix for compaction-aware command rows. The implementation remains extension-only and uses public Pi extension APIs.
+This document records the deterministic validation workflow for compaction-aware command rows. The implementation remains extension-only and uses public Pi extension APIs.
 
 ## Automated suite
 
@@ -23,79 +23,24 @@ npm update --ignore-scripts \
 npm run ci
 ```
 
-The suite covers queue/edit invariants, command classification, images, one-at-a-time and all-mode delivery, synchronous partial handoff restoration, non-TUI pass-through, prompt and Skill expansion, manual compaction success/failure, automatic overflow compaction, retry ordering, repeated reload restoration, and compaction/native-input ordering.
-
-Latest result with Pi 0.84.1: 81 tests passed.
+The suite covers queue and edit invariants, command classification, images, one-at-a-time and all-mode delivery, preparation-failure restoration, non-TUI pass-through, prompt and Skill expansion, manual compaction success and failure, automatic overflow compaction, retry ordering, reload restoration, and compaction/native-input ordering.
 
 ## Real TUI evidence
 
-`test/tui-evidence.sh` starts the real Pi 0.84.1 TUI under tmux with a deterministic faux provider. It uses actual terminal key sequences, public compaction lifecycle events, public provider registration, actual runtime reloads, and Pi's real native compaction queue.
+`test/tui-evidence.sh` starts the real Pi TUI under tmux with a deterministic faux provider. It uses actual terminal key sequences, public compaction lifecycle events, public provider registration, runtime reloads, and Pi's native compaction queue.
 
 Run:
 
 ```bash
 ./test/tui-evidence.sh /tmp/pi-queue-tui-evidence
 ```
 
-The output directory contains plain terminal captures, provider-call logs, lifecycle-event logs, and runtime-initialization logs. Run it immediately before review so `summary.txt` records the exact Pi version, commit and working-tree state under test. A release evidence run should report `working tree: clean`.
-
-The latest complete run reported:
-
-```text
-pi: 0.84.1
-commit: 37fcd1433b8960f13c030d9ba1a5e8cc36535e05
-working tree: clean
-manual events: {"event":"session_before_compact","reason":"manual"} {"event":"session_before_compact","reason":"manual"}
-overflow events: {"event":"session_before_compact","reason":"overflow"} {"event":"session_before_compact","reason":"threshold"}
-runtime initializations across two queued reloads: 3
-captures: abort-paused, manual-reload-resources, native-before-command, automatic-overflow, all-mode
-```
-
-The three runtime initializations are the initial load plus two queued `/reload` rows. The final queued message ran after both reloads.
-
-The semantic capture excerpts were:
-
-```text
-[compaction]
-Compacted from 798 tokens
-FAUX RESPONSE: after manual compaction
-
-Error: Compaction failed: Summarization failed: synthetic TUI summary failure
-FAUX RESPONSE: after failed compaction
-
-Operation aborted
-follow-ups (1) · paused
-enter resume · option+up edit · escape keep paused
-FAUX RESPONSE: after abort resume
-
-Reloaded keybindings, extensions, skills, prompts, themes, and context files
-FAUX RESPONSE: after repeated reload
-
-PROMPT EXPANDED: first=alpha all=alpha beta default=fallback
-[skill] bro
-FAUX RESPONSE: <skill name="bro" ...>
-```
-
-The native post-compaction ordering capture showed the ordinary message submitted during manual `/compact` entering Pi's native queue, finishing before the extension-owned command row, and `/reload` never reaching the model:
-
-```text
-[compaction]
-Compacted from 785 tokens
-ordinary native during compaction
-FAUX RESPONSE: ordinary native during compaction
-Reloaded keybindings, extensions, skills, prompts, themes, and context files
-```
-
-The overflow event log recorded `reason: "overflow"`, the TUI rendered a compaction entry, and `overflow-provider-calls.jsonl` proved the queued follow-up completed exactly once. `all-mode-provider-calls.jsonl` proved all three rows reached Pi exactly once in FIFO order; the all-mode capture rendered them together before the final response.
-
-## Normal-Pi adversarial evidence
-
-PR [#9](https://github.com/tmustier/pi-queue-steer/pull/9) was also exercised at commit `37fcd1433b8960f13c030d9ba1a5e8cc36535e05` through normal `pi` execution under tmux, using the installed extension and Pi 0.84.1 rather than extension-selection or test-fixture flags. The three captures cover automatic compaction above 200k tokens followed by queued `/reload`, manual `/compact` with Pi-native queued input ahead of an extension-owned `/reload`, and abort recovery with repeated queued reloads.
+The output directory contains terminal captures, provider-call logs, lifecycle-event logs, and runtime-initialization logs. Run it immediately before review so `summary.txt` records the exact Pi version, commit, and working-tree state under test. A release evidence run should report `working tree: clean`.
 
-The [public evidence comment](https://github.com/tmustier/pi-queue-steer/pull/9#issuecomment-5231404721) embeds the replacement Menlo-rendered videos and screenshots. Its [reproducible evidence bundle](https://github.com/user-attachments/files/30873175/pi-queue-steer-normal-pi-evidence-37fcd14.zip) has SHA-256 `c6b1150f13fccc195eb5747aa6af63c4589b73df116e3d36d27e92fb85a45e98`. The archive contains machine-checked assertions, tapes, captures, deterministic-suite output and bounded sanitized session proof slices.
-
-This evidence confirms the public API boundary: ordinary input submitted while manual compaction is active belongs to Pi's native post-compaction queue and can execute before extension-owned command rows resume.
+The harness verifies manual compaction success and failure, abort pause and resume, queued reload restoration, resource expansion, native post-compaction ordering, overflow handling, and all-mode FIFO delivery.
 
 ## Public API boundary
 
-`ExtensionAPI.sendUserMessage` and the TUI editor submit callback return `void`. The extension can restore synchronous handoff failures and preflight/expansion failures, but it cannot prove every later asynchronous acceptance or rejection without risking duplicate delivery. Queued `/reload` likewise has no result channel. These limits are documented in the README and are not hidden by timing heuristics.
+`ExtensionAPI.sendUserMessage` and the TUI editor submit callback return `void`. The extension restores rows when prompt or Skill expansion fails before handoff, but it cannot observe later asynchronous acceptance or rejection without risking duplicate delivery. Queued `/reload` likewise has no result channel.
+
+`ExtensionContext.compact` reports completion and failure through `onComplete` and `onError`. Command rows remain blocked until one of those callbacks releases the queue.