---
id: TAMQ-WP-0016
type: workplan
title: "Structured communication protocol capture"
domain: communication
repo: tmux-amq
status: finished
owner: codex
topic_slug: structured-protocol-capture
created: "2026-08-25"
updated: "2026-08-25"
state_hub_workstream_id: "21950dee-3e54-5307-9087-53890cae0257"
---

# Structured communication protocol capture

Retain reviewable evidence of TAMQ exchanges so agent onboarding and protocol
friction can be assessed without recording arbitrary terminal sessions.

## Define the evidence and privacy boundary

```task
id: TAMQ-WP-0016-T01
status: done
priority: high
state_hub_task_id: "24911e5f-a242-5b80-8d88-9dd01675ad4d"
```

Capture only TAMQ protocol facts: addressed messages, provenance, worker block
boundaries, allowlisted commands, line-limit decisions, endpoint lifecycle, and
delivery outcomes. Do not capture unrelated pane output or ordinary shell
input. Retain a message body once at acceptance rather than duplicating it at
each lifecycle event.

## Add an append-only protocol ledger

```task
id: TAMQ-WP-0016-T02
status: done
priority: high
state_hub_task_id: "05b3184e-7059-5f93-b222-505ec44ed03c"
```

Add structured protocol events to SQLite schema version 5. Make acceptance
events atomic with message admission, represent existing message lifecycle
history during migration, and retain stable message/endpoint/repository links
for filtering.

## Instrument onboarding-sensitive transitions

```task
id: TAMQ-WP-0016-T03
status: done
priority: high
state_hub_task_id: "7ba25c70-f8bf-5636-b3cc-64633051d7df"
```

Record operator versus worker origin, worker block start and close reason,
invalid targets, limit blocks, operator-only command results, delivery mode,
attempt, success, and failure class. Never store unrecognized command text or
raw terminal output in event details.

## Provide a review and analysis path

```task
id: TAMQ-WP-0016-T04
status: done
priority: medium
state_hub_task_id: "a3f88ca9-8533-509b-bbda-91ed56b39ebc"
```

Add `tamq capture` with repository, endpoint, message, event-type, and bounded
event-count filters. Render a summarized Markdown review by default and stable
JSONL for analysis. Document the workflow and retention/privacy boundary in the
agent introduction, README, CLI help, and scope assessment.

## Evidence

- Schema migration backfills existing acceptance/display/injection/ack events
  without duplicating newly captured events on later opens.
- Focused store, broker, service, renderer, and CLI tests cover atomic capture,
  worker termination evidence, provenance, failure classes, filtering, and
  Markdown/JSONL output.
- `make check` passes the complete suite.

## Residuals

The capture deliberately describes transport behavior, not recipient
comprehension or authorization. Long-term event retention and automated
protocol-quality recommendations can be added after real captures show which
summaries are useful.