The Agent Inbox system manages human-AI interaction by treating control handoffs as a finite state machine rather than a simple message queue. Each task row in the SQLite database has a specific owner and version markers to prevent race conditions when multiple OS processes or MCP servers compete for updates.
The system uses a strict priority model for inputs. Updates from the inbox interface take precedence over chat-based responses. To ensure atomicity, the system performs conditional updates in a single operation, preventing data overwrites that could occur if a read-and-write sequence were split into separate steps.
To maintain consistency, the system implements a compare-and-swap mechanism via the board_advance operation. This ensures that state transitions only occur if the expected revision and board version match, preventing multiple agents from simultaneously modifying the same task board.
Testing involves real SQLite connections to simulate race conditions, specifically verifying that concurrent processes cannot corrupt the state. While SQLite in WAL mode with a 5000ms busy timeout handles high-frequency writes, the application-level logic remains the primary defense against logical race conditions.
Future development includes implementing remote mode for shared databases (issue #8) and enabling session resumption for local agents (issue #51). Recent updates have already improved synchronization, ensuring that human annotations are correctly captured and that clarification responses do not overwrite history.
