tmux-amq/SCOPE.md

SCOPE

One-liner

Repository-aware tmux sessions and durable local messaging for users or processes working across gita-registered repositories.

Core Idea

Keep neutral tmux topology and durable local message state behind a small CLI and Unix-socket protocol. Pane occupants may be humans, shells, tools, or agents; tamq does not choose or infer them.

In Scope

• Local SQLite message history, leases, endpoint registrations, delivery state, acknowledgements, replay, export, and bounded purging.
• Managed neutral-shell tmux lifecycle and explicit initial commands.
• Durable manual send/inbox/acknowledgement with per-window repository identity, shell-native direct and latest-counterparty reply commands, comment-safe display, and explicit pull-time filters.
• Sanitized one-time output notifications through target tmux pane PTYs, with inbox-only delivery as an explicit option and no foreground-process input.
• Explicit opt-in control-mode pane delivery and the full-duplex tamq tap PTY broker for integration experiments.
• 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.
• Selecting a coding agent, starting one implicitly, or assuming a pane accepts machine-generated terminal input.
• 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 for local alpha	Exact gita validation, per-session @repo/@repo: commands, bare @ latest-counterparty replies, and long-form parsing are covered without modifying shell configuration.
Durable, inspectable local queue	Implemented	SQLite history, manual inbox, 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.
Neutral tmux session lifecycle	Implemented for local alpha	Repository-first startup opens untouched shells at exact gita paths, exports per-window identity, and runs no initial command unless --command is explicit. Stable reuse, service restart, and cleanup are covered by the installed-package test.
Safe manual messaging	Implemented for local alpha	Normal endpoints write one sanitized comment above a stable shell input row without injecting stdin; conservative fallback handles the first row and alternate screens. Messages remain pending until acknowledgement. Inbox-only manual mode is explicit with --no-display.
Full-duplex input observation	Explicit opt-in	--tap --command ... enables the PTY integration path. It is absent from neutral startup and remains covered for geometry, resize, raw mouse input, and lifecycle behavior.
Bounded retry behavior	Not enforced	Failed output or 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	Terminal output remains pending until explicit acknowledgement, while legacy pane injection becomes injected; the configured delivery_ack_mode does not yet govern both paths.
Coordination-engine interoperability	Not implemented	The adapter contract and implementation remain in TAMQ-WP-0002.

Practical Usability

The terminal-neutral alpha path was exercised successfully on 2026-08-24 with an isolated installed tool. Repository-first startup created two ordinary shells at exact gita paths without sending initial keystrokes. The test proved per-window repository identity, stable reuse, shell-native addressing, latest-counterparty replies, comment-safe target output above an unchanged partial input line and cursor, inbox/filter/ack exchange, zero target-input mutation, service restart, endpoint disappearance, explicit initial-command startup, and cleanup.

Suitable today:

• Local queue, history, export/replay, and diagnostic use.
• Interactive local shell or explicitly commanded sessions over one or more gita-registered repositories.
• Durable manual message exchange between managed repository windows, including explicit pull-time loggers and filters.
• Developing and testing the future coordination-engine adapter against the local socket boundary.

Not yet suitable:

• Unattended pane injection 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 100 passing tests and 76% 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