tmux-amq/workplans/TAMQ-WP-0008-reply-shorthand-stable-output.md

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
TAMQ-WP-0008	workplan	Counterparty reply shorthand and stable terminal output	communication	tmux-amq	finished	codex	coulomb-social	P0	13	2026-08-24	2026-08-24	3c58a8aa-1602-5946-af59-c9fc68be0e4a

Counterparty reply shorthand and stable terminal output

Add a conversation-oriented reply convention and keep asynchronous message output above the current input row instead of visually breaking the prompt.

Required operator contract

If audit-core most recently received a message from flex-auth, this sends a reply to flex-auth:

@ Thanks, I will take a look.

The generic @ command resolves the latest durable inbound message for the current TAMQ_REPO, regardless of acknowledgement state. It excludes self-addressed messages. If there is no counterparty, it fails visibly and queues nothing.

When a message arrives, tamq uses tmux's current pane cursor position and VT100-compatible scroll margins to scroll only the rows above the input cursor, write the comment immediately above it, restore the full scroll region, and restore the cursor. The current input row and cursor position remain stable.

Add durable latest-counterparty resolution

id: TAMQ-WP-0008-T01
status: done
priority: high
state_hub_task_id: "aad3dea8-b5c9-5b07-97bb-92aba18137d8"

Query the latest inbound message by creation order for the current repository, excluding self-addressed rows. Add tamq reply MESSAGE... and a tamq-owned generic @ executable alongside the repository-specific shims. Preserve argument boundaries, require TAMQ_REPO, reuse target validation and send transport, and refuse collision with an unrelated existing @ command.

Keep input position stable during output

id: TAMQ-WP-0008-T02
status: done
priority: high
state_hub_task_id: "f9893aba-e2b4-50da-9632-0f2e7f3b8c45"

Resolve cursor_y, pane_height, and the pane PTY atomically through tmux. For a cursor with rows above it, generate a bounded DECSTBM scroll-region frame that saves/restores the cursor and resets the full scrolling region. Sanitize message content before framing and retain the simple output fallback when no row exists above the cursor. Never emit input bytes.

Prove conversation and screen behavior

id: TAMQ-WP-0008-T03
status: done
priority: high
state_hub_task_id: "f81290ce-5bf6-5c08-a0b1-efb2fb8b5782"

Test latest inbound selection across pending/acknowledged and self-addressed messages, missing identity/counterparty errors, generic shim arguments and ownership collision, cursor-aware frames, and real tmux behavior with a partial input line. Prove the input text and cursor coordinates are unchanged while the message becomes visible immediately above them.

Install and document the interaction convention

id: TAMQ-WP-0008-T04
status: done
priority: high
state_hub_task_id: "944c7fea-2e7c-5fcc-9fc6-1abc6a8cc784"

Update help, README, and SCOPE; run complete checks; install the build; exercise @ MESSAGE in both directions in a live two-window session; and retain only user messages pending after acknowledging controlled smoke records.

Completion evidence

• make check: 100 tests passed, including a real tmux pane proving that a partial input row and both cursor coordinates remain unchanged.
• Coverage: 76% overall; terminal framing is 84% and control handling is 81%.
• make install: installed tmux-amq==0.1.0 and verified tamq --version.
• Live flex-auth/audit-core: bare @ routed in both directions. Incoming comments appeared immediately above SECOND-PARTIAL and THIRD-PARTIAL without moving either cursor. Only the three controlled smoke messages were acknowledged; all pre-existing user messages remain pending.