---
id: TAMQ-WP-0007
type: workplan
title: "Target-pane terminal output notifications"
domain: communication
repo: tmux-amq
status: finished
owner: codex
topic_slug: coulomb-social
planning_priority: P0
planning_order: 12
created: "2026-08-24"
updated: "2026-08-24"
state_hub_workstream_id: "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

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

The `audit-core` pane receives terminal output equivalent to:

```text
#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

```task
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

```task
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

```task
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

```task
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

```task
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.