# tmux-amq

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.