@aiiware/aii 0.23.3 → 0.23.4

package/README.md

@@ -481,6 +481,7 @@ Run `aii help` for the full command list.
 | `--bare` | Result to stdout only; all chrome to stderr (one-shot) |
 | `--append-system-prompt <text>` | Append additive instructions to the run |
 | `--append-system-prompt-file <path>` | Append a workspace file of additive instructions |
+| `--reconnect-window <secs>` | One-shot runs: retry dropped connections for up to N seconds (default 0 = fail fast; env twin `AII_RECONNECT_WINDOW`) |
 
 ### Headless / CI Automation
 
@@ -494,6 +495,26 @@ aii "review the staged diff for correctness bugs" \
 
 `--max-turns` bounds cost server-side; `--bare` keeps stdout pipe-clean for `RESULT=$(aii "…" --bare)`; on a single one-shot turn, `--max-budget-usd` adds an advisory `over_budget` flag (pair with `--max-turns` to hard-bound cost). Ready-to-use **GitHub Actions** recipes live in [`examples/github-actions/`](examples/github-actions/) — they use the `pull_request` trigger (never `pull_request_target` with a PR checkout), reference `AII_API_KEY` via `secrets.`, and consume Aii output as data (never `eval`).
 
+### Connection drops
+
+Each execution lane has a deliberate, documented answer to "the network dropped mid-turn":
+
+| Lane | Transport-failure behavior |
+| --- | --- |
+| Interactive session | 60s reconnect window — Esc to stop, `continue` resumes the same turn |
+| Auto / goal (in-session) | retries until success (Ctrl+C exits) |
+| Loop (`aii loop`, `/loop`) | 10 transient retries per iteration + a circuit breaker |
+| One-shot / scripts | **fail fast by default**; opt into a bounded window with `--reconnect-window <secs>` or `AII_RECONNECT_WINDOW` |
+| Cloud dispatch (web-originated) | deliberately no retry — a re-run would re-feed the conversation mirror |
+
+```bash
+# Ride out a wifi handoff in an unattended one-shot (retries transport drops
+# for up to 60s; permanent errors still fail instantly; chatter goes to stderr):
+aii "run the full test suite and summarize failures" --reconnect-window 60
+```
+
+Only *transport* failures retry — provider/server errors classified permanent exit immediately, window or not. Retry chatter is stderr-only, so `--bare`/`--output-format` stdout stays pipe-clean; with `--output-format json`, a multi-attempt run adds an `attempts` field and `tokens`/`cost` report the completed turn's server totals (the session trace's `usage` events carry the full spend record). With `--bare`, an active window buffers stdout and writes the result once on completion (live token streaming resumes when the window is 0/off) — so a dead attempt's partial output never duplicates into `RESULT=$(…)`. Exit code on an exhausted window stays `1`.
+
 ---
 
 ## Troubleshooting