feat: deliver installable local alpha sessions

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a03397-4d51-7fd1-8ff2-946eb22ea2bc

README.md

@@ -3,10 +3,62 @@
 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.
+The local alpha provides tmux endpoint lifecycle, local SQLite history and
+leases, direct `@repo:` routing, JSONL export/replay, and a Unix-socket protocol
+for a later coordination-engine adapter.
+
+## Install and start a local session
+
+Prerequisites must be available on `PATH`: Python 3.11+, [uv](https://docs.astral.sh/uv/),
+tmux, gita, and the agent command you want to run (`codex` by default). Each
+repository must already have an exact gita slug and path.
+
+Install or upgrade `tamq` as an isolated user tool:
+
+```bash
+make install
+command -v tamq
+tamq --version
+```
+
+Start an attached two-repository Codex session:
+
+```bash
+tamq start --command codex railiance-platform activity-core
+```
+
+This creates or reuses the managed `tamq` session, opens same-named windows in
+the exact gita paths for `railiance-platform` and `activity-core`, launches Codex
+behind `tamq tap` in each new window, and attaches to the first window. Codex is
+the default, so this is equivalent:
+
+```bash
+tamq start railiance-platform activity-core
+```
+
+Set up the session without attaching, then attach later:
+
+```bash
+tamq start --detach --command codex railiance-platform activity-core
+tamq status
+tamq attach
+```
+
+Repeated starts reuse existing windows and do not launch a second agent in
+them. `--cmd` remains an alias for `--command`. A quoted command may include
+arguments, for example `--command 'codex --profile local'`.
+
+For degraded tmux-only use, `tamq start --no-service ...` skips socket endpoint
+registration and message delivery. Stop the broker and remove the managed tmux
+session explicitly when finished:
+
+```bash
+tamq stop
+tmux kill-session -t tamq
+```
+
+Uninstall the user tool from the checkout with `make uninstall`, or from
+anywhere with `uv tool uninstall tmux-amq`.
 
 ## Development
 
@@ -18,7 +70,7 @@ 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
+The alpha 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
@@ -63,10 +115,13 @@ 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.
+Policy profiles accept a safety-gated retry cap of at most nine attempts, but
+the alpha delivery path does not enforce attempt counting yet. Explicit
+acknowledgement exists, while `delivery_ack_mode` enforcement and bounded retry
+state are tracked in `TAMQ-WP-0003`. 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.
+The Unix socket service supports structured `ping`, `register`, `send`,
+`history`, `ack`, `endpoints`, and `disconnect` operations. Endpoint
+registrations and messages are persisted in the same local SQLite database;
+delivery remains delegated to the control-mode adapter.