Decide: should standalone `wait` exit non-zero on timeout (currently exits 0 with `timedOut: true`)?

[ThomasK33]

Current behavior

A standalone wait that times out exits 0, reporting the timeout only in the JSON envelope:

agent-tty wait "$SID" --text 'never-appears' --timeout 1500 --json
# → {"ok": true, "result": {"matched": false, "timedOut": true, "capturedAtSeq": 0}}
# → exit code 0

Exit code 11 (WAIT_TIMEOUT) is currently only raised by a timed-out wait step inside a fail-fast batch (src/batch/executor.ts, asserted by test/integration/batch.test.ts). The exit-code map in src/cli/exitCodes.ts defines WAIT_TIMEOUT → 11, but the standalone wait command path never produces that error — it resolves successfully with timedOut: true.

This was discovered while documenting the exit-code contract in #150 and verified empirically against a live session. The behavior is now documented as-is in docs/USAGE.md (Exit Codes table and the wait section).

Why this may be worth changing

The natural shell idiom fails open:

agent-tty wait "$SID" --text 'ready' --timeout 30000 && next-step

next-step runs even when the condition was never met. Scripts and agents must remember to parse result.timedOut from the envelope instead — easy to get wrong, and inconsistent with batch, where the same timeout is a step failure with exit 11.

Considerations

• Making standalone wait exit 11 on timeout is a breaking change to the public CLI contract (callers may rely on exit 0 + envelope inspection).
• If changed, docs/USAGE.md (Exit Codes table, wait section), README.md's command-surface note, and the wait integration tests need updating in the same change.
• An alternative is to keep current behavior and close this as wontfix, leaving the documented envelope-first contract as the deliberate design.

Acceptance criteria (if actioned)

• Standalone wait exits 11 when the condition is not met within --timeout, for all condition types (--text, --regex, --screen-stable-ms, --idle-ms, --exit, cursor waits).
• JSON envelope shape for the timeout case is decided explicitly (error envelope vs. current ok: true result) and schemas/messages/tests are updated together.
• batch semantics remain unchanged.
• Docs updated: docs/USAGE.md Exit Codes + wait sections, README command-surface note.

---

Generated with mux • Model: anthropic:claude-fable-5 • Thinking: xhigh