coulomb/tmux-amq
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: make sessions terminal neutral
Some checks failed
tamq-ci / test (push) Failing after 6s
Details

Browse source 
Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a03397-4d51-7fd1-8ff2-946eb22ea2bc
This commit is contained in:
tegwick 2026-08-24 20:10:08 +02:00
parent 408d32df88
commit 74b2f27997
20 changed files with 608 additions and 182 deletions
Download patch file Download diff file Expand all files Collapse all files

48
SCOPE.md
View file

@ -2,20 +2,23 @@
## One-liner
Local durable message queue and tmux endpoint runtime for coordinating agent workers across gita-registered repositories.
Repository-aware tmux sessions and durable local messaging for users or
processes working across gita-registered repositories.
## Core Idea
Keep tmux topology, terminal input observation, and durable local message state
behind a small CLI and Unix-socket protocol that agents can use without owning
a distributed coordination service.
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 tmux endpoint lifecycle, control-mode output/injection, and the
full-duplex `tamq tap` PTY broker.
- Managed neutral-shell tmux lifecycle and explicit initial commands.
- Durable manual send/inbox/acknowledgement with per-window repository identity.
- 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: message` routing.
- Unix-socket operations for local clients and a future coordination-engine
adapter.
@ -27,6 +30,8 @@ a distributed coordination service.
- 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 assuming a pane accepts
machine-generated terminal input.
- Bypassing `gita` registration or injecting arbitrary pane input outside the
supported tap/control-mode boundaries.
- Owning tmux, Codex, State Hub, or adjacent repositories' lifecycle.
@ -40,41 +45,42 @@ transport.
| Intent capability | State | Evidence and remaining gap |
| --- | --- | --- |
| Direct repository addressing | Implemented | Exact `gita` validation and `@repo:` parsing are covered by tests. |
| Durable, inspectable local queue | Implemented | SQLite history, leases, endpoint records, inspect/history, JSONL export/replay, acknowledgement, and purge are present. |
| Durable, inspectable local queue | Implemented | SQLite history, manual inbox, leases, endpoint records, inspect/history, JSONL export/replay, acknowledgement, and purge are present. |
| Local socket service | Implemented | Peer-credential checks and structured ping/register/send/history/ack/endpoints/disconnect operations are tested. |
| Tmux endpoint lifecycle and delivery | Implemented for local alpha | Real isolated-tmux and installed-package tests prove exact repository windows, stable reuse, control-mode injection, durable history transition, service stop, and bounded cleanup. |
| Full-duplex input observation | Implemented for local alpha | `tamq tap` uses raw outer-terminal mode, copies and propagates window dimensions, forwards lifecycle signals, preserves mouse/control bytes, and observes CR/LF address lines. A real tmux fixture covers geometry, resize, and raw mouse input. |
| 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. |
| Safe manual messaging | Implemented for local alpha | Manual endpoints never inject pending messages into panes. Installed testing proves send/inbox/ack exchange while the target pane remains unchanged; legacy rows migrate to manual mode. |
| 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 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 | Explicit acknowledgement and the configuration field exist; delivery always marks a successful tmux injection as `injected`, irrespective of `delivery_ack_mode`. |
| Coordination-engine interoperability | Not implemented | The adapter contract and implementation remain in `TAMQ-WP-0002`. |
## Practical Usability
The installable alpha path was exercised successfully on 2026-08-24 with both
isolated fixtures and the operator's registered repositories. `make install`
produced a user-level `tamq` command; `tamq start --detach --command codex
railiance-platform activity-core` created two same-named live panes rooted at
their exact gita paths. Repeating the command retained the same session instance
and pane PIDs. The automated installed-package path also proved message
injection, history, status, service stop, and cleanup.
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, manual send/inbox/ack exchange,
zero target-pane mutation, service restart, endpoint disappearance, explicit
initial-command startup, and cleanup.
Suitable today:
- Local queue, history, export/replay, and diagnostic use.
- Interactive local Codex sessions over one or more gita-registered repositories.
- Controlled message-routing experiments between managed tmux endpoints.
- Interactive local shell or explicitly commanded sessions over one or more
gita-registered repositories.
- Durable manual message exchange between managed repository windows.
- Developing and testing the future coordination-engine adapter against the
local socket boundary.
Not yet suitable:
- Unattended or high-confidence delivery where bounded retries and positive
recipient acknowledgement are required.
- Unattended pane injection where bounded retries and positive recipient
acknowledgement are required.
- 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 69 passing tests and 72% statement coverage. Coverage
The suite currently has 77 passing tests and 74% 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