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 for local alpha	Real isolated-tmux and installed-package tests prove exact repository windows, stable reuse, control-mode injection, durable history transition, service stop, and bounded cleanup.
Full-duplex input observation	Implemented for local alpha	tamq tap uses raw outer-terminal mode, copies and propagates window dimensions, forwards lifecycle signals, preserves mouse/control bytes, and observes CR/LF address lines. A real tmux fixture covers geometry, resize, and raw mouse input.
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 installable alpha path was exercised successfully on 2026-08-24 with both isolated fixtures and the operator's registered repositories. make install produced a user-level tamq command; tamq start --detach --command codex railiance-platform activity-core created two same-named live panes rooted at their exact gita paths. Repeating the command retained the same session instance and pane PIDs. The automated installed-package path also proved message injection, history, status, service stop, and cleanup.

Suitable today:

• Local queue, history, export/replay, and diagnostic use.
• Interactive local Codex sessions over one or more gita-registered repositories.
• Controlled message-routing experiments between managed 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 longer-running crash/terminal soak tests and stronger process-supervision evidence.
• Cross-host messaging or use as a general-purpose broker.

The suite currently has 69 passing tests and 72% statement coverage. Coverage is strongest in durable storage and registry handling, and weakest in the PTY tap and CLI orchestration; PTY statement coverage increased from 23% to 33%, while subprocess behavior is primarily proven by the real-tmux test. The Forgejo CI job installs tmux and uv, runs the real-tmux and isolated installed-package session tests with a deterministic gita fixture, and retains CLI help/version smoke checks on Python 3.11.

Next Usability Gates

• TAMQ-WP-0003-T01 and T02 still own bounded retry state and acknowledgement enforcement. Its real tmux/PTY lifecycle gate (T03) is complete.
• 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