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, bounded purging, and a structured communication-protocol ledger for review.
• 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 blocks terminated by an empty line.
• Operator-only allowlisted Cmd: runtime changes and atomic, session-lifetime per-window message/input/output line budgets.
• Versioned Unix-socket operations and a transport-only coordination-engine client adapter with correlation and idempotent wake admission.
• 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, non-routable From: block above a stable shell input row without injecting stdin; /o marks operator origin. Inbox-only mode is explicit. The selected acknowledgement policy determines completion.
Experimental pushy and trigger delivery	Explicit opt-in	Pushy places a non-routable From: block without Enter; trigger waits past paste detection and adds exactly one Enter. A startup grace protects first delivery. 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; collects worker To: blocks through an empty row, recognizes conservative full-screen worker-output gutters and row gaps, 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.
Protocol review capture	Implemented for local alpha	An append-only SQLite ledger records addressed-message acceptance, provenance, worker block boundaries, allowlisted command outcomes, endpoint changes, limit blocks, and delivery outcomes. tamq capture renders filtered Markdown or JSONL without recording unrelated pane output or shell input.
Bounded retry behavior	Implemented for local alpha	Lease acquisition increments a persistent attempt count. Failures and lease expiry schedule bounded backoff; cap exhaustion becomes inspectable failed, and tamq retry explicitly resets a terminal message.
Acknowledgement policy	Implemented for local alpha	injected completes on successful terminal write. acknowledged enters awaiting_ack, redelivers the same message ID after a deadline, exhausts with ack_timeout, accepts late acknowledgements, and exposes duplicate-delivery semantics.
Coordination-engine interoperability	Implemented transport boundary	The versioned same-user Unix-socket client negotiates capabilities, resolves an exact live endpoint, admits idempotent correlated wakes, recovers receipts after restart, and exposes ack/retry without importing tmux control code. Coordination-engine still owns its orchestration runtime.

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.
• Reviewing repository-to-repository exchanges and onboarding friction through structured Markdown or JSONL protocol captures.
• Controlled experiments with pushy placement or trigger submission to interfaces known to queue asynchronous prompts.
• Integrating coordination-engine through the implemented transport adapter and durable receipt boundary.

Not yet suitable:

• Treating terminal delivery or acknowledgement as proof of completed work; workflow completion remains coordination-engine/State Hub state.
• 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 182 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

• Operational soak evidence is still needed before treating input delivery as production-grade or unattended across arbitrary terminal applications.
• Coordination-engine owns implementing its trigger observer, coordination leases, safety gates, checkpoints, and State Hub projections on top of this completed local transport boundary.

Getting Oriented

• Start with: INTENT.md
• Agent instructions: AGENTS.md
• Workplans: workplans/
• Developer workflow: uv sync --extra dev, make test, and make check