feat: complete reliable coordination adapter

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a03397-4d51-7fd1-8ff2-946eb22ea2bc

SCOPE.md

@@ -14,7 +14,8 @@ tamq does not choose or infer them.
 ## In Scope
 
 - Local SQLite message history, leases, endpoint registrations, delivery state,
-  acknowledgements, replay, export, and bounded purging.
+  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
@@ -30,8 +31,8 @@ tamq does not choose or infer them.
   an empty line.
 - 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.
+- 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,
@@ -63,13 +64,14 @@ transport.
 | 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. Messages remain pending until acknowledgement. Inbox-only mode is explicit. |
+| 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. |
-| 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`. |
+| 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
 
@@ -89,22 +91,24 @@ Suitable today:
   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.
-- Developing and testing the future coordination-engine adapter against the
-  local socket boundary.
+- Integrating coordination-engine through the implemented transport adapter and
+  durable receipt boundary.
 
 Not yet suitable:
 
-- Unattended pane injection where bounded retries and positive recipient
-  acknowledgement are required.
+- 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 166 passing tests. It includes atomic counter races,
+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
@@ -112,10 +116,11 @@ 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.
+- 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