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`