Update documentation for streaming dedup and live-validate workflow

- Add live-validate command documentation for verifying rendering
  pipeline changes with a live batch session
- Update AGENTS.md development workflow with live-validate step
- Update README.org features list: expand CI sub-features, add
  streaming dedup, DWIM context insertion, and runtime invariants

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: timvisher-dd

.agents/commands/live-validate.md

@@ -0,0 +1,68 @@
+# Live validation of agent-shell rendering
+
+Run a live agent-shell session in batch mode and verify the buffer output.
+This exercises the full rendering pipeline with real ACP traffic — the only
+way to catch ordering, marker, and streaming bugs that unit tests miss.
+
+## Prerequisites
+
+- `ANTHROPIC_API_KEY` must be available (via `op run` / 1Password)
+- `timvisher_emacs_agent_shell` must be on PATH
+- Dependencies (acp.el-plus, shell-maker) in sibling worktrees or
+  overridden via env vars
+
+## How to run
+
+```bash
+cd "$(git rev-parse --show-toplevel)"
+timvisher_agent_shell_checkout=. \
+  timvisher_emacs_agent_shell claude --batch \
+  1>/tmp/agent-shell-live-stdout.log \
+  2>/tmp/agent-shell-live-stderr.log
+```
+
+Stderr shows heartbeat lines every 30 seconds.  Stdout contains the
+full buffer dump once the agent turn completes.
+
+## What to check in the output
+
+1. **Fragment ordering**: tool call drawers should appear in
+   chronological order (the order the agent invoked them), not
+   reversed.  Look for `▶` lines — their sequence should match the
+   logical execution order.
+
+2. **No duplicate content**: each tool call output should appear
+   exactly once.  Watch for repeated blocks of identical text.
+
+3. **Prompt position**: the prompt line (`agent-shell>`) should
+   appear at the very end of the buffer, after all fragments.
+
+4. **Notices placement**: `[hook-trace]` and other notice lines
+   should appear in a `Notices` section, not interleaved with tool
+   call fragments.
+
+## Enabling invariant checking
+
+To run with runtime invariant assertions (catches corruption as it
+happens rather than after the fact):
+
+```elisp
+;; Add to your init or eval before the session starts:
+(setq agent-shell-invariants-enabled t)
+```
+
+When an invariant fires, a `*agent-shell invariant*` buffer pops up
+with a debug bundle and recommended analysis prompt.
+
+## Quick validation one-liner
+
+```bash
+cd "$(git rev-parse --show-toplevel)" && \
+  timvisher_agent_shell_checkout=. \
+  timvisher_emacs_agent_shell claude --batch \
+  1>/tmp/agent-shell-live.log 2>&1 && \
+  grep -n '▶' /tmp/agent-shell-live.log | head -20
+```
+
+If the `▶` lines are in logical order and the exit code is 0, the
+rendering pipeline is healthy.

AGENTS.md

@@ -31,3 +31,11 @@ When adding or changing features:
    changes land. Both `bin/test` and CI enforce this — changes to `.el`
    or `tests/` files without a corresponding `README.org` update will
    fail.
+3. **Live-validate rendering changes.** For changes to the rendering
+   pipeline (fragment insertion, streaming, markers, UI), run a live
+   batch session to verify fragment ordering and buffer integrity.
+   See `.agents/commands/live-validate.md` for details. The key command:
+   ```bash
+   timvisher_agent_shell_checkout=. timvisher_emacs_agent_shell claude --batch \
+     1>/tmp/agent-shell-live.log 2>&1
+   ```

README.org

@@ -6,11 +6,18 @@ A soft fork of [[https://github.com/xenodium/agent-shell][agent-shell]] with ext
 * Features on top of agent-shell
 
 - CI workflow and local test runner ([[https://github.com/timvisher-dd/agent-shell-plus/pull/1][#1]], [[https://github.com/timvisher-dd/agent-shell-plus/pull/6][#6]], [[https://github.com/timvisher-dd/agent-shell-plus/pull/8][#8]])
+  - Byte-compilation of all =.el= files ([[https://github.com/timvisher-dd/agent-shell-plus/pull/1][#1]])
+  - ERT test suite ([[https://github.com/timvisher-dd/agent-shell-plus/pull/1][#1]])
+  - README update check when code changes ([[https://github.com/timvisher-dd/agent-shell-plus/pull/4][#4]])
+  - Dependency DAG check (=require= graph must be acyclic) ([[https://github.com/timvisher-dd/agent-shell-plus/pull/7][#7]])
 - Desktop notifications when the prompt is idle and waiting for input ([[https://github.com/timvisher-dd/agent-shell-plus/pull/2][#2]], [[https://github.com/timvisher-dd/agent-shell-plus/pull/8][#8]])
 - Per-shell debug logging infrastructure ([[https://github.com/timvisher-dd/agent-shell-plus/pull/2][#2]])
 - Regression tests for shell buffer selection ordering ([[https://github.com/timvisher-dd/agent-shell-plus/pull/3][#3]])
 - CI check that README.org is updated when code changes ([[https://github.com/timvisher-dd/agent-shell-plus/pull/4][#4]])
 - Usage tests and defense against ACP =used > size= bug ([[https://github.com/timvisher-dd/agent-shell-plus/pull/5][#5]])
+- Streaming tool output with dedup: advertise =_meta.terminal_output= capability, handle incremental chunks from codex-acp and batch results from claude-agent-acp, strip =<persisted-output>= tags, fix O(n²) rendering, and partial-overlap thought dedup ([[https://github.com/timvisher-dd/agent-shell-plus/pull/7][#7]])
+- DWIM context insertion: inserted context lands at the prompt and fragment updates no longer drag process-mark past it ([[https://github.com/timvisher-dd/agent-shell-plus/pull/7][#7]])
+- Runtime buffer invariant checking with event tracing and violation debug bundles ([[https://github.com/timvisher-dd/agent-shell-plus/pull/7][#7]])
 
 -----