feat(flush): add auto mode with self-injected /clear for unattended runs

Long autonomous sessions bloat or hit auto-compaction because /clear is a prompt keystroke no tool call can execute. Auto mode closes that gap: after the write-verified checkpoint, the agent derives its own tmux pane, arms self-inject.sh through tmux run-shell -b, and ends the turn so /clear and a resume line land at an idle prompt. The server-owned arm is load-bearing: a detached child of a tool call dies at the turn boundary. The pane must be derived before arming because ancestry detection can't work under the tmux server.

self-inject.sh joins the synced scripts with a six-test bats suite, tmux stubbed at the boundary. work-the-backlog now auto-flushes between tasks when context grows heavy, and its speedrun preset gained the per-item disposition rule: feature-level work gets a spec, unguessable decisions get a VERIFY, well-defined tasks get implemented. The mechanism was proven live in another project's session and its design note is preserved under docs/design/.

1 files changed, 78 insertions, 0 deletions

diff --git a/.ai/scripts/tests/self-inject.bats b/.ai/scripts/tests/self-inject.bats
new file mode 100644
index 0000000..482f61d
--- /dev/null
+++ b/.ai/scripts/tests/self-inject.bats
@@ -0,0 +1,78 @@
+#!/usr/bin/env bats
+# Tests for self-inject.sh — tmux is the external boundary, stubbed with a
+# recording fake so no real server is needed.
+
+setup() {
+    SCRIPT="$BATS_TEST_DIRNAME/../self-inject.sh"
+    STUB_DIR="$BATS_TEST_TMPDIR/bin"
+    LOG="$BATS_TEST_TMPDIR/tmux.log"
+    mkdir -p "$STUB_DIR"
+}
+
+# A tmux stub that records every invocation and answers list-panes from
+# $STUB_PANES (empty by default, so pane derivation fails unless a test
+# provides ancestry-matching output).
+make_stub() {
+    cat > "$STUB_DIR/tmux" <<'EOF'
+#!/bin/sh
+echo "$@" >> "$LOG"
+case "$1" in
+    list-panes) printf '%s\n' "$STUB_PANES" ;;
+esac
+EOF
+    chmod +x "$STUB_DIR/tmux"
+}
+
+@test "self-inject: -t pane with no pairs echoes the pane and exits 0" {
+    make_stub
+    run env PATH="$STUB_DIR:$PATH" LOG="$LOG" STUB_PANES="" sh "$SCRIPT" -t %42
+    [ "$status" -eq 0 ]
+    [ "$output" = "%42" ]
+    # Pane was supplied, nothing sent: tmux must not have been called.
+    [ ! -e "$LOG" ]
+}
+
+@test "self-inject: no pane derivable and no -t exits 1 with an error" {
+    make_stub
+    run env PATH="$STUB_DIR:$PATH" LOG="$LOG" STUB_PANES="" sh "$SCRIPT" 0 "hello"
+    [ "$status" -eq 1 ]
+    case "$output" in *"no owning pane"*) : ;; *) false ;; esac
+}
+
+@test "self-inject: derives the pane from process ancestry via list-panes" {
+    make_stub
+    # The stub reports the bats test process itself as a pane's pane_pid;
+    # the script runs as our child, so that pid is in its ancestry.
+    run env PATH="$STUB_DIR:$PATH" LOG="$LOG" STUB_PANES="$$ %7" sh "$SCRIPT"
+    [ "$status" -eq 0 ]
+    [ "$output" = "%7" ]
+}
+
+@test "self-inject: one delay/text pair sends literal text then Enter" {
+    make_stub
+    run env PATH="$STUB_DIR:$PATH" LOG="$LOG" STUB_PANES="" sh "$SCRIPT" -t %3 0 "/clear"
+    [ "$status" -eq 0 ]
+    run cat "$LOG"
+    [ "${lines[0]}" = "send-keys -t %3 -l /clear" ]
+    [ "${lines[1]}" = "send-keys -t %3 Enter" ]
+}
+
+@test "self-inject: multiple pairs send in order" {
+    make_stub
+    run env PATH="$STUB_DIR:$PATH" LOG="$LOG" STUB_PANES="" \
+        sh "$SCRIPT" -t %3 0 "/clear" 0 "go — resume"
+    [ "$status" -eq 0 ]
+    run cat "$LOG"
+    [ "${lines[0]}" = "send-keys -t %3 -l /clear" ]
+    [ "${lines[1]}" = "send-keys -t %3 Enter" ]
+    [ "${lines[2]}" = "send-keys -t %3 -l go — resume" ]
+    [ "${lines[3]}" = "send-keys -t %3 Enter" ]
+}
+
+@test "self-inject: dangling odd argument after pairs is ignored" {
+    make_stub
+    run env PATH="$STUB_DIR:$PATH" LOG="$LOG" STUB_PANES="" sh "$SCRIPT" -t %3 0 "one" 99
+    [ "$status" -eq 0 ]
+    run cat "$LOG"
+    [ "${#lines[@]}" -eq 2 ]
+}