Bootstrap tamq local tmux agent message queue

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a02f34-ead4-7a60-85cd-d7f08e22fa0e

README.md

@@ -1,3 +1,72 @@
 # tmux-amq
 
-A local tmux based agentic message queue for repository worker agent coordination.
+Tmux Agentic Message Queueing (`tamq`) is a local, durable message queue for
+agent workers running in gita-registered repositories.
+
+The initial implementation is being bootstrapped from the standalone queue and
+CLI contract. It will provide tmux endpoint lifecycle, local SQLite history and
+leases, direct `@repo:` routing, JSONL export/replay, and a Unix-socket attach
+protocol for a later coordination-engine adapter.
+
+## Development
+
+```bash
+uv run pytest
+uv run tamq --help
+uv run tamq --version
+uv run tamq start --cmd codex net-kingdom railiance-platform
+uv run tamq attach
+```
+
+The bootstrap currently includes the local SQLite queue and a tmux endpoint
+manager, strict gita target validation, and a control-mode client for tmux
+operations/injection, and the PTY tap for full-duplex input observation. The
+control-mode client alone does not expose arbitrary pane input; `tamq tap` is
+the supported input-broker hook. `tamq send` remains available as an explicit
+fallback. coordination-engine integration remains a later phase.
+
+## Terminal architecture
+
+`tamq` separates terminal coordination into three layers:
+
+1. tmux control mode is the topology and output/control stream;
+2. the local broker assigns endpoint/source identity and durably queues intent;
+3. `tamq tap` is a full-duplex PTY proxy around the agent process. It forwards
+   bytes unchanged while observing complete input lines for `@repo:` routing.
+
+This keeps tmux-specific topology concerns separate from reusable terminal I/O
+observation and message identity.
+
+Pending messages are delivered through the control-mode client as
+`#sender-repo: body`, then marked `injected` in SQLite. Delivery is
+endpoint-scoped and uses the same message ID for retry/deduplication.
+The visible endpoint label is `tmux-amq-<PID>`; each boot also receives an
+instance nonce so PID reuse cannot collide with prior leases or receipts.
+
+## Configuration
+
+Configuration is read from `${XDG_CONFIG_HOME:-~/.config}/tamq/config.toml` (or
+`$TAMQ_CONFIG`). Environment variables such as `TAMQ_SOCKET` and
+`TAMQ_STATE_DIR` take precedence. The purge and startup advisory defaults can
+be tuned without changing command lines:
+
+```toml
+[tamq]
+state_dir = "/run/user/1000/tamq"
+purge_before = "365d"
+purge_max_size = "100MB"
+history_max_size = "100MB"
+delivery_poll_interval = "0.5"
+
+[policy.profiles.diagnostics]
+safety_gated_max_attempts = 2
+delivery_ack_mode = "acknowledged"
+```
+
+Retries remain safety-gated and capped at nine attempts. Use `--policy-profile`
+to select a profile; `--orwell` enables explicitly unsafe local diagnostics.
+
+The Unix socket service now supports structured `ping`, `register`, `send`, and
+`history` operations. Endpoint registrations and messages are persisted in the
+same local SQLite database; delivery remains delegated to the control-mode
+adapter.