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 send/inbox/acknowledgement with per-window repository identity, readable To:/From: framing, explicit operator/worker provenance, and 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 input placement and trigger submission for known queue-capable interactive programs.
• Explicit opt-in control-mode pane delivery and the full-duplex tamq tap PTY broker for integration experiments.
• Exact gita validation and direct, case-insensitive To:repo: keyword routing from operator input or normalized worker output.
• Operator-only allowlisted Cmd: runtime changes and atomic, session-lifetime per-window message/input/output line budgets.
• 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 and case-insensitive To:repo: body keyword parsing are shared across operator input and worker output. Legacy @/# addressing and the composer are removed.
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 output messaging	Implemented for local alpha	Normal endpoints write one sanitized From: line above a stable shell input row without injecting stdin; /o marks operator origin. Messages remain pending until acknowledgement. Inbox-only mode is explicit.
Experimental pushy and trigger delivery	Explicit opt-in	Pushy places a non-routable From: line without Enter; trigger adds exactly one Enter. Both are capability-gated and mark accepted delivery injected, but cannot identify pane occupants or protect input already being edited.
Full-duplex observation	Implemented for managed messaging	Every messaging-enabled new window runs its neutral shell or explicit command behind the PTY observer. It preserves geometry, resize, mouse input, and raw forwarding; normalizes worker output, recognizes conservative full-screen worker-output gutters, deduplicates redraws, and fails closed on exact recent operator echoes.
Runtime commands and generation budgets	Implemented for local alpha	Operator-only Cmd: changes mode or per-window limits and resets the current ledger. Defaults are 8 message, 1024 input, and 32768 output lines. Admission and counter increments are atomic and survive service/tap restarts in one session generation.
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 is exercised with an isolated installed tool and real tmux/PTYs. Repository-first startup creates two observed ordinary shells at exact gita paths without selecting an agent. Tests prove per-window identity, stable reuse, operator and worker To: routing, exact /o attribution, echoed-input suppression, stable target output above unchanged partial input, inbox/filter/ack exchange, pushy placement, trigger submission, line-limit/reset behavior, service restart, explicit-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 message exchange between managed repository windows, including explicit pull-time loggers and filters.
• Controlled experiments with pushy placement or trigger submission to interfaces known to queue asynchronous 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 136 passing tests. It includes atomic counter races, pseudo-terminal normalization, real tmux pushy/trigger behavior, operator-echo suppression, and an isolated installed-package workflow with deterministic gita fixtures. Forgejo CI installs tmux and uv 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