tmux-amq/workplans/TAMQ-WP-0007-terminal-output-notifications.md

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
TAMQ-WP-0007	workplan	Target-pane terminal output notifications	communication	tmux-amq	finished	codex	coulomb-social	P0	12	2026-08-24	2026-08-24	99c8039f-6230-55af-bb67-9b0245d9909f

Target-pane terminal output notifications

Make a durably routed message visibly appear in its target repository terminal without turning any bytes into input for the pane occupant.

Required operator contract

tamq flex-auth audit-core
# in flex-auth
@audit-core: Some message!

The audit-core pane receives terminal output equivalent to:

#flex-auth: Some message! [m-...]

Tamq resolves the target pane's pseudo-terminal through tmux and writes a sanitized notification to that device's output queue. It never uses send-keys, never sends Enter, and never alters the foreground process's stdin. The notification may visually interleave with a prompt or be redrawn by a full-screen program; the durable inbox remains authoritative.

Messages remain pending after display until tamq ack or a successful explicit inbox filter. A persisted display timestamp prevents successful notifications from being emitted repeatedly after broker polls or restarts.

Specify and isolate the output channel

id: TAMQ-WP-0007-T01
status: done
priority: high
state_hub_task_id: "00972410-bc94-50f7-b7be-8c3c8228a43a"

Define terminal-output delivery separately from legacy pane-input injection. Resolve only tmux-reported /dev/pts/<number> character devices owned by the current user, sanitize terminal control bytes, use bounded non-blocking writes, and document visual interleaving as a display limitation rather than an input safety failure.

Completed with a dedicated terminal-output module, strict tmux PTY path and ownership validation, non-blocking output-only writes, printable Unicode retention, terminal-control escaping, and comment-prefixed CRLF framing.

Persist one-time display state

id: TAMQ-WP-0007-T02
status: done
priority: high
state_hub_task_id: "e9bc0a58-3488-5122-a899-26dc1b4b2f88"

Add a migration-safe displayed_at marker. Claim a pending message before output, record successful display and release its lease atomically, retain its pending acknowledgement state, and make broker restart/poll behavior idempotent after a successful write.

Completed with SQLite schema v3 and displayed_at. Successful output records the timestamp and releases the lease without changing the pending state; subsequent polls skip it. Failed writes retain the claim until expiry and then retry without falsely recording display.

Make terminal output the normal managed-session mode

id: TAMQ-WP-0007-T03
status: done
priority: high
state_hub_task_id: "e59a59b0-af2d-570b-9e35-963216dedfa4"

Register ordinary started sessions in output mode and advertise the required broker capability. Preserve --tap --command as explicit pane-input mode, provide --no-display for durable inbox-only operation, and restart an older broker before registering the new mode.

Completed with normal output registration, terminal_output capability negotiation and legacy-broker restart, explicit --no-display manual mode, and the unchanged explicit --tap --command pane-input boundary.

Prove output without input

id: TAMQ-WP-0007-T04
status: done
priority: high
state_hub_task_id: "e51146f4-0e44-5de9-87dd-725fe78c792a"

Use a real pseudo-terminal and real tmux acceptance to prove the notification appears in pane output, never reaches foreground-process stdin, remains pending for acknowledgement, emits only once across polls, handles multiline/control content safely, retries failed output, and retains manual and explicit tap modes.

Completed with real PTY proof that output reaches the master while the slave stdin remains unreadable, invalid-device rejection, control-character and multiline formatting, successful one-time display, failure/lease retry, schema migration, and real installed tmux capture evidence.

Install and document the operator workflow

id: TAMQ-WP-0007-T05
status: done
priority: high
state_hub_task_id: "af6100d5-ee2c-5bf4-9086-1578dec770ec"

Update help, README, SCOPE, and installed-package acceptance. Install the verified build, recreate or re-register a live two-repository session, exchange and acknowledge one visible smoke message, and record State Hub evidence.

Completed with updated CLI help, README, and SCOPE; 93 passing tests at 76% statement coverage; and an installed live flex-auth/audit-core session in output mode. Both previously pending user messages and a fresh smoke appeared in the target pane. The smoke alone was acknowledged; the two user messages remain pending with persisted display timestamps.