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, a recipient-aware inline composer, 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 experimental pushy delivery that submits a sanitized comment and Enter to target pane input for known queue-capable interactive programs, with #repo: routing observed through the PTY tap.
• 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:/#repo: 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.
• Dry-run emergency cleanup for verified services, tamq-marked sessions, transient registrations/leases, generated shims, and owned stale sockets; durable history remains separately controlled.

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 silently assuming a pane accepts machine-generated input; pushy delivery requires explicit mode selection by the operator.
• 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: shell commands, tapped #repo: agent-input routing, a bare @ composer with latest-counterparty default and Tab recipient cycling, and long-form parsing are covered.
Durable, inspectable local queue	Implemented	SQLite history, manual inbox, leases, endpoint records, inspect/history, JSONL export/replay, acknowledgement, age/size purge, and exact reflected-chain 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.
Emergency local cleanup	Implemented for local alpha	tamq cleanup dry-runs by default; confirmed cleanup verifies ownership before stopping the broker or marked session, clears only transient DB state, removes configured runtime files/generated shims/owned stale tmux sockets, and preserves history.
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.
Experimental pushy delivery	Explicit opt-in	--mode pushy --command ... observes outbound #repo:/@repo: lines and submits a non-routable # from sender: envelope plus Enter through a checked tmux command. Startup rejects stale framing capabilities, and the tap recognizes durable legacy delivery receipts as a feedback circuit breaker. It marks successful delivery injected, but cannot identify pane occupants or protect input already being edited.
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 in safe modes, service restart, endpoint disappearance, explicit initial-command startup, and cleanup. Isolated pushy-mode coverage additionally proves one #repo: route, one non-routable target submission, and no feedback message.

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.
• Controlled experiments with pushy delivery to coding-agent interfaces known to queue asynchronous user prompts.
• 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.
• Pushy delivery to arbitrary shells, editors, or panes with unknown input state.
• 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 131 passing tests and 78% 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