tmux-amq/SCOPE.md

# SCOPE

## One-liner

Local durable message queue and tmux endpoint runtime for coordinating agent workers across gita-registered repositories.

## Core Idea

Keep tmux topology, terminal input observation, and durable local message state
behind a small CLI and Unix-socket protocol that agents can use without owning
a distributed coordination service.

## In Scope

- Local SQLite message history, leases, endpoint registrations, delivery state,
  acknowledgements, replay, export, and bounded purging.
- Managed tmux endpoint lifecycle, control-mode output/injection, and the
  full-duplex `tamq tap` PTY broker.
- Exact `gita` repository validation and direct `@repo: message` routing.
- Unix-socket operations for local clients and a future coordination-engine
  adapter.
- Policy profiles, safety-gated retries, local diagnostics, tests, packaging,
  shell completion, and operator documentation.

## Out of Scope

- Owning goal planning, workflow scheduling, or cross-host coordination; those
  belong to `coordination-engine` and its consumers.
- Acting as a network-accessible or multi-host message broker.
- Bypassing `gita` registration or injecting arbitrary pane input outside the
  supported tap/control-mode boundaries.
- Owning tmux, Codex, State Hub, or adjacent repositories' lifecycle.

## Current State

Version `0.1.0` is a usable local alpha for development and controlled
single-host experiments. It is not yet a dependable unattended coordination
transport.

| Intent capability | State | Evidence and remaining gap |
| --- | --- | --- |
| Direct repository addressing | Implemented | Exact `gita` validation and `@repo:` parsing are covered by tests. |
| Durable, inspectable local queue | Implemented | SQLite history, leases, endpoint records, inspect/history, JSONL export/replay, acknowledgement, and purge are present. |
| Local socket service | Implemented | Peer-credential checks and structured ping/register/send/history/ack/endpoints/disconnect operations are tested. |
| Tmux endpoint lifecycle and delivery | Implemented, integration confidence limited | The manager, control client, and delivery loop exist, but tests use fakes and CI does not exercise real tmux panes or agent processes. |
| Full-duplex input observation | Implemented, lightly proven | `tamq tap` preserves PTY traffic and observes complete address lines; PTY code coverage is 23%. |
| Bounded retry behavior | Not enforced | Failed injection remains pending and becomes claimable after lease expiry, but no attempt counter or terminal failure state applies the configured cap. |
| Acknowledgement policy | Partially implemented | Explicit acknowledgement and the configuration field exist; delivery always marks a successful tmux injection as `injected`, irrespective of `delivery_ack_mode`. |
| Coordination-engine interoperability | Not implemented | The adapter contract and implementation remain in `TAMQ-WP-0002`. |

## Practical Usability

The following operator path was exercised successfully on 2026-08-24 with an
isolated state directory: start the socket service, ping it, inspect status,
queue a message to registered repo `tmux-amq`, inspect history, export one JSONL
record, and stop the service.

Suitable today:

- Local queue, history, export/replay, and diagnostic use.
- Controlled experiments with gita-registered repositories and tmux endpoints.
- Developing and testing the future coordination-engine adapter against the
  local socket boundary.

Not yet suitable:

- Unattended or high-confidence delivery where bounded retries and positive
  recipient acknowledgement are required.
- Production-style operation without a real tmux/PTY integration test suite,
  crash-recovery evidence, and stronger process supervision evidence.
- Cross-host messaging or use as a general-purpose broker.

The suite currently has 50 passing tests and 73% statement coverage. Coverage
is strongest in durable storage and registry handling, and weakest in the PTY
tap, control-mode process handling, and CLI orchestration. The Forgejo CI job
runs unit tests and CLI help/version smoke checks on Python 3.11, but does not
install or exercise tmux and gita end to end.

## Next Usability Gates

- `TAMQ-WP-0003` owns bounded retry state, acknowledgement enforcement,
  lifecycle recovery, and real tmux/PTY integration evidence.
- `TAMQ-WP-0002` owns the coordination-engine adapter after the local delivery
  contract is sufficiently reliable.

## Getting Oriented

- Start with: INTENT.md
- Agent instructions: AGENTS.md
- Workplans: workplans/
- Developer workflow: `uv sync --extra dev`, `make test`, and `make check`