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