docs: plan terminal output notifications

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

WORK-RECORDS.md

@@ -15,6 +15,7 @@
 | workplan | TAMQ-WP-0004 | finished | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.md |
 | workplan | TAMQ-WP-0005 | finished | — | workplans/TAMQ-WP-0005-terminal-neutral-manual-messaging.md |
 | workplan | TAMQ-WP-0006 | finished | — | workplans/TAMQ-WP-0006-shell-native-message-routing.md |
+| workplan | TAMQ-WP-0007 | active | — | workplans/TAMQ-WP-0007-terminal-output-notifications.md |
 | task | TAMQ-WP-ADHOC-2026-08-24-T01 | done | — | workplans/ADHOC-2026-08-24.md |
 | task | TAMQ-WP-0001-T01 | done | — | workplans/TAMQ-WP-0001-statehub-bootstrap.md |
 | task | TAMQ-WP-0001-T02 | done | — | workplans/TAMQ-WP-0001-statehub-bootstrap.md |
@@ -40,3 +41,8 @@
 | task | TAMQ-WP-0006-T03 | done | — | workplans/TAMQ-WP-0006-shell-native-message-routing.md |
 | task | TAMQ-WP-0006-T04 | done | — | workplans/TAMQ-WP-0006-shell-native-message-routing.md |
 | task | TAMQ-WP-0006-T05 | done | — | workplans/TAMQ-WP-0006-shell-native-message-routing.md |
+| task | TAMQ-WP-0007-T01 | progress | — | workplans/TAMQ-WP-0007-terminal-output-notifications.md |
+| task | TAMQ-WP-0007-T02 | todo | — | workplans/TAMQ-WP-0007-terminal-output-notifications.md |
+| task | TAMQ-WP-0007-T03 | todo | — | workplans/TAMQ-WP-0007-terminal-output-notifications.md |
+| task | TAMQ-WP-0007-T04 | todo | — | workplans/TAMQ-WP-0007-terminal-output-notifications.md |
+| task | TAMQ-WP-0007-T05 | todo | — | workplans/TAMQ-WP-0007-terminal-output-notifications.md |

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

@@ -0,0 +1,109 @@
+---
+id: TAMQ-WP-0007
+type: workplan
+title: "Target-pane terminal output notifications"
+domain: communication
+repo: tmux-amq
+status: active
+owner: codex
+topic_slug: coulomb-social
+planning_priority: P0
+planning_order: 12
+created: "2026-08-24"
+updated: "2026-08-24"
+---
+
+# 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: progress
+priority: high
+```
+
+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.
+
+## Persist one-time display state
+
+```task
+id: TAMQ-WP-0007-T02
+status: todo
+priority: high
+```
+
+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.
+
+## Make terminal output the normal managed-session mode
+
+```task
+id: TAMQ-WP-0007-T03
+status: todo
+priority: high
+```
+
+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.
+
+## Prove output without input
+
+```task
+id: TAMQ-WP-0007-T04
+status: todo
+priority: high
+```
+
+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.
+
+## Install and document the operator workflow
+
+```task
+id: TAMQ-WP-0007-T05
+status: todo
+priority: high
+```
+
+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.