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`