docs: Convert quickstart_async.md to executable doctests

Removed all 7 # doctest: +SKIP markers and converted to executable
doctests using CPython asyncio.run() pattern. All examples now use
server fixture for TestServer isolation and assert behavior (True/False)
rather than exact values.

Changes:
- Pattern A demo: Uses server.acmd() with cleanup
- Pattern B demo: Uses tmux_cmd_async with socket isolation
- Quick example: Creates windows concurrently, verifies count
- Objects demo: Tests session/window/pane creation with ID format checks
- Error handling: Verifies stderr and returncode behavior
- Performance comparison: Tests async is at least as fast as sync
- Hybrid example: Demonstrates both patterns working together

All examples use server.socket_name for isolation, include cleanup,
and return boolean assertions for deterministic test results.

Verified with: pytest docs/quickstart_async.md --doctest-modules -v
Result: 7 passed in 0.75s

Author: tony

IMPLEMENTATION_COMPLETE.md

@@ -300,7 +300,7 @@ The implementation is **complete, tested, and ready for production use**.
 
 ---
 
-**Created**: 2025-11-03
+**Created**: 2025-11-08
 **Worktree**: `libtmux-asyncio-psycopg`
 **Branch**: `libtmux-asyncio-psycopg`
 **Status**: ✅ Production Ready

IMPLEMENTATION_STATUS.md

@@ -1,7 +1,7 @@
 # libtmux Async Implementation Status
 
 **Status**: ✅ **Complete and Validated**
-**Date**: 2025-11-03
+**Date**: 2025-11-08
 **Branch**: `libtmux-asyncio-psycopg`
 
 ## Executive Summary

docs/quickstart_async.md

@@ -23,26 +23,24 @@ Use `.acmd()` on existing Server/Session/Window/Pane objects. Perfect for gradua
 
 ```python
 >>> import asyncio
->>> import libtmux
->>>
->>> async def main():
-...     server = libtmux.Server()
-...
-...     # Execute async command
+>>> async def pattern_a_demo():
+...     # Uses 'server' fixture from conftest for isolation
 ...     result = await server.acmd('new-session', '-d', '-P', '-F#{session_id}')
-...     print(f"Created session: {result.stdout[0]}")
+...     session_id = result.stdout[0]
 ...
 ...     # Execute concurrent commands
 ...     results = await asyncio.gather(
-...         server.acmd('new-window', '-n', 'window1'),
-...         server.acmd('new-window', '-n', 'window2'),
-...         server.acmd('new-window', '-n', 'window3'),
+...         server.acmd('new-window', '-t', session_id, '-n', 'window1'),
+...         server.acmd('new-window', '-t', session_id, '-n', 'window2'),
+...         server.acmd('new-window', '-t', session_id, '-n', 'window3'),
 ...     )
-...     print(f"Created {len(results)} windows concurrently")
->>>
->>> asyncio.run(main())  # doctest: +SKIP
-Created session: $...
-Created 3 windows concurrently
+...
+...     # Cleanup
+...     await server.acmd('kill-session', '-t', session_id)
+...
+...     return len(results) == 3
+>>> asyncio.run(pattern_a_demo())
+True
 ```
 
 ### Pattern B: `common_async` Module
@@ -52,23 +50,21 @@ Use `tmux_cmd_async()` for direct async command execution. Perfect for new async
 ```python
 >>> import asyncio
 >>> from libtmux.common_async import tmux_cmd_async, get_version
->>>
->>> async def main():
+>>> async def pattern_b_demo():
 ...     # Get tmux version
 ...     version = await get_version()
-...     print(f"tmux version: {version}")
+...     sock = server.socket_name
 ...
-...     # Execute concurrent commands
+...     # Execute concurrent commands with isolated socket
 ...     sessions, windows, panes = await asyncio.gather(
-...         tmux_cmd_async('list-sessions'),
-...         tmux_cmd_async('list-windows'),
-...         tmux_cmd_async('list-panes'),
+...         tmux_cmd_async('-L', sock, 'list-sessions'),
+...         tmux_cmd_async('-L', sock, 'list-windows', '-a'),
+...         tmux_cmd_async('-L', sock, 'list-panes', '-a'),
 ...     )
-...     print(f"Sessions: {len(sessions.stdout)}, Windows: {len(windows.stdout)}, Panes: {len(panes.stdout)}")
->>>
->>> asyncio.run(main())  # doctest: +SKIP
-tmux version: ...
-Sessions: ..., Windows: ..., Panes: ...
+...
+...     return len(str(version)) > 0 and all(isinstance(r.stdout, list) for r in [sessions, windows, panes])
+>>> asyncio.run(pattern_b_demo())
+True
 ```
 
 ## Installation
@@ -91,13 +87,9 @@ Here's a practical example showing the performance benefit of async:
 
 ```python
 >>> import asyncio
->>> import libtmux
->>>
 >>> async def create_windows_async():
 ...     """Create multiple windows concurrently (fast)."""
-...     server = libtmux.Server()
-...
-...     # Get or create session
+...     # Uses 'server' fixture from conftest
 ...     result = await server.acmd('new-session', '-d', '-P', '-F#{session_id}')
 ...     session_id = result.stdout[0]
 ...
@@ -109,13 +101,12 @@ Here's a practical example showing the performance benefit of async:
 ...         server.acmd('new-window', '-t', session_id, '-n', 'logs'),
 ...     )
 ...
-...     print(f"Created {len(results)} windows concurrently")
-...
 ...     # Cleanup
 ...     await server.acmd('kill-session', '-t', session_id)
->>>
->>> asyncio.run(create_windows_async())  # doctest: +SKIP
-Created 4 windows concurrently
+...
+...     return len(results) == 4
+>>> asyncio.run(create_windows_async())
+True
 ```
 
 Compare this to sequential sync operations, which would be 2-3x slower.
@@ -136,11 +127,8 @@ Pattern A makes it easy to work with tmux objects asynchronously:
 
 ```python
 >>> import asyncio
->>> import libtmux
->>>
 >>> async def demo_objects():
-...     server = libtmux.Server()
-...
+...     # Uses 'server' fixture from conftest
 ...     # Create session
 ...     result = await server.acmd('new-session', '-d', '-P', '-F#{session_id}')
 ...     session_id = result.stdout[0]
@@ -153,16 +141,20 @@ Pattern A makes it easy to work with tmux objects asynchronously:
 ...     result = await server.acmd('split-window', '-t', window_id, '-P', '-F#{pane_id}')
 ...     pane_id = result.stdout[0]
 ...
-...     print(f"Created session {session_id}, window {window_id}, pane {pane_id}")
-...
 ...     # Send keys to pane
 ...     await server.acmd('send-keys', '-t', pane_id, 'echo "Hello from async!"', 'Enter')
 ...
 ...     # Cleanup
 ...     await server.acmd('kill-session', '-t', session_id)
->>>
->>> asyncio.run(demo_objects())  # doctest: +SKIP
-Created session $..., window @..., pane %...
+...
+...     # Verify all IDs were created
+...     return all([
+...         session_id.startswith('$'),
+...         window_id.startswith('@'),
+...         pane_id.startswith('%')
+...     ])
+>>> asyncio.run(demo_objects())
+True
 ```
 
 ## Error Handling
@@ -172,20 +164,20 @@ Error handling works the same in async as in sync:
 ```python
 >>> import asyncio
 >>> from libtmux.common_async import tmux_cmd_async
->>>
 >>> async def demo_errors():
+...     sock = server.socket_name
+...
 ...     # Invalid command
-...     result = await tmux_cmd_async('invalid-command')
-...     if result.stderr:
-...         print(f"Error: {result.stderr[0]}")
+...     result = await tmux_cmd_async('-L', sock, 'invalid-command')
+...     has_error = len(result.stderr) > 0 and 'unknown command' in result.stderr[0]
 ...
 ...     # Non-existent session
-...     result = await tmux_cmd_async('has-session', '-t', 'non_existent')
-...     print(f"Return code: {result.returncode}")
->>>
->>> asyncio.run(demo_errors())  # doctest: +SKIP
-Error: unknown command: invalid-command
-Return code: 1
+...     result = await tmux_cmd_async('-L', sock, 'has-session', '-t', 'non_existent_99999')
+...     has_nonzero_return = result.returncode != 0
+...
+...     return has_error and has_nonzero_return
+>>> asyncio.run(demo_errors())
+True
 ```
 
 ## Performance: Sequential vs Concurrent
@@ -197,31 +189,31 @@ Here's a real-world example showing the performance difference:
 >>> import time
 >>> from libtmux.common_async import tmux_cmd_async
 >>> from libtmux.common import tmux_cmd
->>>
 >>> async def compare_performance():
+...     sock = server.socket_name
+...
 ...     # Async (concurrent)
 ...     start = time.time()
 ...     await asyncio.gather(
-...         tmux_cmd_async('list-sessions'),
-...         tmux_cmd_async('list-windows'),
-...         tmux_cmd_async('list-panes'),
-...         tmux_cmd_async('show-options', '-g'),
+...         tmux_cmd_async('-L', sock, 'list-sessions'),
+...         tmux_cmd_async('-L', sock, 'list-windows', '-a'),
+...         tmux_cmd_async('-L', sock, 'list-panes', '-a'),
+...         tmux_cmd_async('-L', sock, 'show-options', '-g'),
 ...     )
 ...     async_time = time.time() - start
 ...
 ...     # Sync (sequential)
 ...     start = time.time()
-...     tmux_cmd('list-sessions')
-...     tmux_cmd('list-windows')
-...     tmux_cmd('list-panes')
-...     tmux_cmd('show-options', '-g')
+...     tmux_cmd('-L', sock, 'list-sessions')
+...     tmux_cmd('-L', sock, 'list-windows', '-a')
+...     tmux_cmd('-L', sock, 'list-panes', '-a')
+...     tmux_cmd('-L', sock, 'show-options', '-g')
 ...     sync_time = time.time() - start
 ...
-...     speedup = sync_time / async_time
-...     print(f"Async: {async_time:.4f}s, Sync: {sync_time:.4f}s, Speedup: {speedup:.2f}x")
->>>
->>> asyncio.run(compare_performance())  # doctest: +SKIP
-Async: 0.0...s, Sync: 0.0...s, Speedup: ...x
+...     # Concurrent should be at least as fast (allow 10% variance)
+...     return async_time <= sync_time * 1.1
+>>> asyncio.run(compare_performance())
+True
 ```
 
 Typical speedup: **2-3x faster** for 4 concurrent commands.
@@ -232,30 +224,29 @@ You can mix both patterns in the same application:
 
 ```python
 >>> import asyncio
->>> import libtmux
 >>> from libtmux.common_async import tmux_cmd_async
->>>
 >>> async def hybrid_example():
-...     server = libtmux.Server()
+...     # Uses 'server' fixture from conftest
+...     sock = server.socket_name
 ...
 ...     # Pattern A: Use .acmd() on server
 ...     result_a = await server.acmd('new-session', '-d', '-P', '-F#{session_id}')
 ...     session_a = result_a.stdout[0]
 ...
-...     # Pattern B: Use tmux_cmd_async directly
-...     result_b = await tmux_cmd_async('new-session', '-d', '-P', '-F#{session_id}')
+...     # Pattern B: Use tmux_cmd_async directly with socket
+...     result_b = await tmux_cmd_async('-L', sock, 'new-session', '-d', '-P', '-F#{session_id}')
 ...     session_b = result_b.stdout[0]
 ...
-...     print(f"Pattern A: {session_a}, Pattern B: {session_b}")
-...
 ...     # Both patterns work with asyncio.gather
 ...     await asyncio.gather(
 ...         server.acmd('kill-session', '-t', session_a),
-...         tmux_cmd_async('kill-session', '-t', session_b),
+...         tmux_cmd_async('-L', sock, 'kill-session', '-t', session_b),
 ...     )
->>>
->>> asyncio.run(hybrid_example())  # doctest: +SKIP
-Pattern A: $..., Pattern B: $...
+...
+...     # Verify both sessions were created and start with $
+...     return session_a.startswith('$') and session_b.startswith('$')
+>>> asyncio.run(hybrid_example())
+True
 ```
 
 ## Next Steps